XMLMill - convert xml to pdf with java. Generate PDF from xml/xsl.

XMLMill for Domino: UseCases

Version: 2.80 Date: November 4th, 2006
This tutorial is opened in a separate window in order to maximize the legibility of this tutorial.
To return to XMLMill, close this browser window

This page as PDFPrinter friendly pageThis guide (!) as PDF

Working with XMLMill in a Domino R5/R6/R7 environment

XMLMill is originally developed as a JAVA-tool to transform XML/XSLT-files into one or more PDF's. XMLMill can be used as a standalone application, in batch or in a servlet container. This product is marketed as XMLMill for JAVA . The PDF-generation process can be summarized as follows:

images/xmlxsl.jpg
Select to enlarge

  1. An XML-file and an XSL-file are sent to XMLMill. The XML-file contains the data to be published. The XSL-file contains the formatting and transformation instructions needed for converting the XML-file to a XMLMill XML-file.
  2. The XMLMill application will convert your XML file, based on your XSL specifications, to an internal XMLMill XML- file. The XMLMill XML-file should be compliant with the xmlmill.dtd specifications. Therefore your XSL file should contain a reference to the xmlmill.dtd with the doctype-system= "xmlmill.dtd" reference in the <xsl:output> directive.
  3. XMLMill will convert the generated internal XMLMill XML-file to 1 or more PDF documents.

Since the market asked us to be able to use XMLMill in a Domino-environment, we developed a connector between XMLMill and Domino, so that we could create a PDF dynamically from within a Notes-document or a Notes-view. This product is currently marketed as XMLMill for Domino .

Domino R5 or R6 or R7?

Many of you have asked us wether you can use XMLMill for Domino in a R5 environment. The answer is: it depends on what you want to do.

On-the-Fly generation of PDF's (R6/R7 only)

On-the-Fly generation of a PDF means that the user presses a button on a view or a document in the Notes client or the Browser and the resulting PDF is shown immediately to the user. For this scenario you need R6/R7.

Due to the JDK differences in XMLMill and Domino R5, you cannot use XMLMill for on-the-fly generation of PDF's in an R5-environment that uses the DOMINO Servlet Manager for Java-support (see serverdocument in Domino Directory).

Domino R5 comes with JDK 1.1.8 natively. This is an old JDK and the JDK cannot be changed to a more recent version. XMLMill is written with JDK 1.3.1 and uses classes and methods not available in JDK 1.1.8.

Since Domino R6/R7 uses a more recent JDK, XMLMill can be used for on-the-fly generation of PDF's in Domino R6/R7.

If you have websphere as part of your environment, you can use websphere for Servlet Manager Support in Domino R5, in order to make XMLMill work for generating a PDF on the fly in a Domino R5 environment.

For Domino R6/R7 the connector was designed in such a way, that a Notes-developer can first define his XML-structure through a simple lotus script agent, write his XSLT-stylesheet for layout-definition and then call the connector to transform both to a PDF using XMLMill. We will explain the use of the connector in the first use case in this manual. The PDF-generation process for the Domino connector used in R6/R7 for on-the-fly-generation of PDF's can be summarized as follows:

  1. A user views a Notes-document through the Notes- or Webclient. He presses a button View PDF
  2. The XMLMill-servlet, running on the Domino-server is invoked, connects to the Notes-database and creates an empty document which will contain the XML-structure and the name of the XSLT-stylesheet. The servlet calls an agent in the Notesdatabase.
  3. The agent in the Notesdatabase is written by the Notes Developer and defines the XML-structure. This datastructure is written in a rich-textfield in the new document created by the servlet.
  4. The agent also fills a second field in the Notes document containing the path- and filename of the XSLT-file, written by the Notes Developer and containing the required lay-out instructions.
  5. The servlet picks up the XML-structure from the Notes-document and the XSLT-stylesheet from the filesystem and calls XMLMill to convert both to a PDF.
  6. The PDF is shown to the user.

The picture below summarizes this flow. We will come back with a detailed explanation of this method in our first use case.

images/xmlxsldominogeneral.jpg
Select to enlarge

Batch generation of PDF's (R5/R6/R7)

Batch generation of 1 or more PDF's means that you run eg. a scheduled agent that calls XMLMill through a batch-procedure. The resulting PDF's are placed in a directory on your filesystem. You may either leave them there or an agent might pick them up and attach them to Notes-documents or create a link to them in the correct Notes-document.

By using the batch-procedure, XMLMill is used outside the Domino-environment and does not use its JDK. Consequently, you can use XMLMill for batch-generation of PDF's in both Domino R5, R6 and R7.

When using the batch-procedure you can create PDF's from within R5/R6/R7. Normally, you would schedule the PDF-creation process, but in the use cases you have to click on a button in a view to start the process. The PDF-generation process used in the batch-procedure in the use cases can be summarized as follows:

  1. A user selects a view of Use case 1,2 or 3 and presses a button Create Productlist or Create invoices or Create Reminders.
  2. A Lotus-script agent, written by a Notes Developer is invoked. This agent opens a file on the filesystem and writes the required XML-structure to it.
  3. The agent then calls a batch-file. In this file, XMLMill is called and asked to transform the XML-file produced by the agent together with a predefined XSLT-stylesheet residing on the filesystem to 1 or more PDF's.
  4. After the PDF's have been processed, the agent captures them and attaches them to the right Notes-document or creates a link to them in the correct Notes-document.

Installing XMLMill for Domino

We have included all the material to try out the use cases in the trial version XMLMill for Domino. Even if you are running Domino R5, you can download this trial version. You can run 3 of the 4 use cases in a Domino R5 environment.

R5-users have to download and extract XMLMill for Domino and they are ready to try out usecases 2,3 and 4. R6/R7-users have to download and extract XMLMill for Domino and carry out a configuration procedure in order to prepare their Domino-server for communication with XMLMill, when they want to try out use case 1. R6/R7-users can try out all use cases 2,3,4 and 5 the same way as R5-users.

To install XMLMill for Domino, please go to the download page of the XMLMill website and choose the appropriate download distribution (.zip or .tar.gz format).

In case you are working in a Domino R6/R7 environment or if you are an R5-user and you want to do tests with scheduled agents, extract all the files in the download to a separate subdirectory on the filesystem of your Domino-server or a shared networkdrive on which the Domino-server has read and write access to. Make sure that you inherit the directory-structure when you extract the files from your .zip or .tar.gz download to your filesystem.

In case you are working in a Domino R5 environment and you want to test the use cases locally, extract all the files in the download to a separate subdirectory on your pc. Make sure that you inherit the directory-structure when you extract the files from your .zip or .tar.gz download to your filesystem.

For R6/R7-users only: the configuration of Domino R6/R7 for bridging with XMLMill in order to create PDF's on-the-fly (use case 1) is a step-by-step procedure which we have explained very thorougly in the installation_guide_r6.pdf you can find in the download in the subdirectory domino. Please read this very carefully and carry out every installation and configuration step.

R5-users should check if they have an adequate JRE installed (at least version 1.3.1). To check this and install the JRE if you don't have it on your system, please read the procedure in the installation_guide_r5.pdf you can find in the download in the subdirectory domino. Read this very carefully and carry out the installation of the JRE if necessary.

For our use cases we downloaded the XMLMill to the xmlmill-directory on our lab_server. Our JRE is installed in the program files of our lab_server. This directory is shared as progs. In the XMLMill-batch files and in our notes-agents, we use these filepaths. Keep in mind that you have to modify these in order to try out the use cases in your environment.

General architecture of the use cases

No matter whether you use XMLMill for generating PDF's on-the-fly or in batch, the PDF-generation process always involves following steps:

  1. A Notes-agent , created by the Notes developer, transforms the data in a view or in a document to an XML-structure.
  2. XMLMill is called either after invoking a servlet (if you generate a PDF on-the-fly) or by executing a batch-file.
  3. XMLMill uses the XML-structure and combines it with an XSLT-stylesheet on the filesystem to transform the data to a PDF.

As we mentioned in the preface we will now present our 4 use cases:

  1. On-the-fly creation of a PDF from a web- or notesclient (R6/R7 only)
  2. Create a PDF with bookmarks and a table of content based on a Notes-view using XMLMill as a batch-procedure (R5, R6 and R7)
  3. Create different invoice PDF's based on a Notes-view per customer using XMLMill as a batch-procedure (R5, R6 and R7)
  4. Create different reminder PDF's per customer based on a Notes-view using XMLMill as a batch-procedure (R5, R6 and R7)
Copyright © 2001 - 2012. All rights reserved. XMLMill and XMLMill logo are trademarks of Pecunia Data Systems, bvba.
Powered by Apache CocoonPowered by XMLMill