Note: Updated documentation is coming soon. Below is slightly outdated version for PD4ML v3
Creating PDF documents with Notes Java agent and PD4ML v3
As a starting point we recommend to look through "Leverage DXL to Overcome Web Browser Rich Text Limitations" Lance Spellman Workflow Studios. The document describes the concept of DXL (Domino XML) language and XSL transformations needed to convert DXL to HTML.The example Notes agent extracts selected document(s) in DXL form from database, performs XSL transformation of the DXL to HTML, converts the HTML to PDF and stores the resulting PDFs as attachments to the original document(s). The agent code can be easily adjusted to your particular needs: sending of emails with PDF attachments, external archiving of documents in PDF form etc.
See the main page for a general Notes-to-PDF conversion info.
We start with a blank database creation in IBM Domino Designer.
The following description/screenshots correspond to R6 version of Domino Designer; with the most recent versions of the Designer application the flow differs only in minor details.
(If you do not want to follow all the steps, download a copy of preconfigured NSF R9 database)
After the database is produced, create an agent.
The type of the agent should be set to "Java":
Copy-paste the agent code (R7 agent code) to the agent editor. An attempt to save would cause an error: there are still missing libraries there.
In order to add the missing resources press "Edit Project" button and add pd4ml.jar (or pd4ml_demo.jar) from PD4ML distribution, ss_css2.jar and dxl4pd4ml.xsl.
There is also optional fonts.jar contains TTF fonts, for a case it is not possible to refer to a local font directory like "c:\windows\fonts".
The sample fonts.jar directory structure:
More about TTF embedding is here (TODO).
Now it is time to create a document form
save it, switch to IBM Notes and create a document instance:
Now we can activate the agent with Actions->Create PDF menu item. Close the document and open it again (No idea how to refresh the document view from Java code).
The new attachment icon should allow us to open the just generated PDF version of the document.
Remarks:
- Starting with Lotus Notes R7 the way of XSL transformation has been changed for Lotus platform. If for some reason you use R6 or older, here is an legacy NSF demo database compatible with the older XSL trasnformation appraoch. Also there is a database version, created with Domino Designer R7. The R6 and R7 databases include slightly outdated versions of PD4ML and XSL stylesheet, so we recommend to evaluate using the actual R9 database.
Note: sometimes Notes fails to start the PDF generation agent of the demo database and hangs. Actually Notes does not trust the fake agent signature and for some reason it fails to show its security alert dialog. Try to restart Notes and to reopen the database.
- The XSL we use in the example does the basic transformation to HTML, handles images, attachments and page breaks, but it is still far away from the full DXL features support. We constantly work on improving it. Please request PD4ML support for the most recent and feature-rich version of DXL converting XSL stylesheet.
- The example is tested with Notes/Domino 6.5.4 and newer. Older versions do not allow to load resources via Java ClassLoader, so it is needed to store the XSL to the database as a "normal" document and to read it from there by usual for Lotus Notes way.
- The agent debug output can be seen under Tools->Show Java Debug Console menu item
- The following needs to be done to set the Java properties for Domino on the iSeries:
- Create an entry in the notes.ini pointing to custom Java user settings file (JavaUserOptionsFile=/notes/wdomino1/javaOptions.txt)
- Create the file using the ASCII character set and add the following entry or any other properties that need to be set... java.awt.headless=true
- For some document types, producing broken PDF layout, (especially if generated PDFs contain snippets of LotusScript code) it helps after String xml = dxl.exportDxl(tmp); Java agent code line is substituted with
String xml = dxl.exportDxl(doc); - Dxl2Pdf command-line tool
- If a conversion returns a blank PDF page, first inspect its source DXL. If it consists of a single
<rawitemdata type="1">object, often it is a sign of DXL export failure: Notes cannot represent a particular document in DXL form, so it base64-encodes the original Notes binary document object and sends it back. (<rawitemdata type="1">is also returned for XPage documents, but it is another story)If you have a control over the document, a tactics to debug is as follows. Open the database in Domino Designer and start to delete document input fields one by one (and test every step in Notes) until it produces a correct DXL. After a problematic input field is found, return it back to the document and start to clean its properties one by one (again with DXL testing). According to our experience, usually it is a single property value makes DXL exporter to give up. For example, any value in "Field Hint" property make IBM Notes 9.0.1 to fail with a DXL export. Hopefully someone from IBM works on the issue.
