The current implementation of Open ESB provides the developer with the
ability to generate pdf based reports for their BPEL processes. By its
nature this functionality is restricted in what it can provided and
often does not meet the projects requirements simply taking the
documentation added to the the various BPEL activities and writing it
out to a pdf whilst also generating a graphical representation of the
BPEL that frequently does not fit into the document correctly.
Having discussed this with a some of our pre-sales representatives I decided to see what I could achieve and build a flexible template based alternative. Much of the code used within the generation process is based on the previous work I did generating SVG from BPEL but enhanced to improve performance and flexibility.
This first blog entry describes the command-line interface to generating the the BPEL Documentation whilst a subsequent entry will describe the NetBeans Plug-in I have built to proved the additional functional at a single click.
Overview
OpenOffice (or StarOffice), and its associated API, is used to provided the Document Template functionality and as such the user will be able to define their own structure based on a few simple requirements. Once the template document has been defined then the generator will be able to build the document and save it in a number of formats:
Requirements
The following software and jar files are required:
In addition the jars, properties and script files generated as part of this blog can be found below:
Creating a Template Document
At this point it will be worth opening the template document, above, so that we can see the requirements. You will notice that the example one provided simply has a title page, table of contents and a number of sections.
The key components of the document are the named fields and the bookmarks because these are what the underlying code uses to generate the document contents. The following Named Fields, Bookmarks and Tables are required.
Named Tables
Bookmarks
The methods mentioned above are Abstract methods within the Abstract Document Generator class and will be overridden in the implementation class to provide the appropriate information. Extending the documentation functionality by writing your own concrete class will be the subject of another blog entry.
Configuration File
When executing the Document Generation you will need to specify a configuration properties file which I will describe below:
Example
Two execute the generation class I have provided an example bat file which should be modified to match you installation.
If we take the following BPEL Process as an example and then run the Documentation Generator against it the resulting pdf will look like the example below.
Having discussed this with a some of our pre-sales representatives I decided to see what I could achieve and build a flexible template based alternative. Much of the code used within the generation process is based on the previous work I did generating SVG from BPEL but enhanced to improve performance and flexibility.
This first blog entry describes the command-line interface to generating the the BPEL Documentation whilst a subsequent entry will describe the NetBeans Plug-in I have built to proved the additional functional at a single click.
| Document
Generator Trail |
Overview
OpenOffice (or StarOffice), and its associated API, is used to provided the Document Template functionality and as such the user will be able to define their own structure based on a few simple requirements. Once the template document has been defined then the generator will be able to build the document and save it in a number of formats:
- Word Doc
- HTML
- OpenOffice
Requirements
The following software and jar files are required:
In addition the jars, properties and script files generated as part of this blog can be found below:
- Documentation Jar - BpelDocumentGenerator.jar.
(GROK
Entry)
- OpenOffice Template - BPELReportTemplate.odt.
- Configuration File - config.properties.
- Generator bat File - GenBpelDoc.bat.
- Logging Properties - logging.properties.
- Example SVG Icons - svg.zip.
Creating a Template Document
At this point it will be worth opening the template document, above, so that we can see the requirements. You will notice that the example one provided simply has a title page, table of contents and a number of sections.
The key components of the document are the named fields and the bookmarks because these are what the underlying code uses to generate the document contents. The following Named Fields, Bookmarks and Tables are required.
Named Fields
- BPELModuleName - This field will be set at runtime to the name of the BPEL Module being processed. In the example document it is used in the headers and on the front page.
Named Tables
- ImportsTable - Table
consisting of 3 columns and 1 heading row. This table will contain the
information associated with the BPEL imports. In the current release of
the Generator it must match the structure of the table in the example
template.
- PartnerLinksTable - Table
consisting of 4 columns and 1 header row. This table will contain the
information associated with the BPEL Partner Links. In this release of
the Generator its structure must match that of the table in the example
document template.
- VariablesTable - Table
consisting of 2 columns and 1 header row. This table will contain all
the information associated with the Variables defined within the BPEL
Process. In this release the structure of this table must match that of
the one defined in the example template document.
Bookmarks
- BPELActivities - Defined
the location where the individual Activity information will be
inserted. This is the starting bookmark and all activity information
will be inserted below this. The exact processing associated with each
Activity type will vary depending on the type. Composite Activities
will generate the document information and display an image of the Sub
Activities they contain whilst a Simple Activity will just display
information about itself.
- BPELModuleActivities -
Defines the location where the Module Activities Summary information
will be written. This information will be obtained from the call to getBPELModuleActivitiesText(TProcess
process) in the generation class. The information returned will
be written into the example template below the Activities Heading.
- BPELModuleImports - Defines the location where the Module Import Summary information will be written. This information will be obtained from the call to getBPELModuleImportsText(TProcess process) in the generation class. The information returned will be written into the example template below the Imports Heading.
- BPELModuleOverview - Defines the location where the Module Overview information will be written. This information will be obtained from the call to getBPELModuleOverviewText(TProcess process) in the generation class. The information returned will be written into the example template below the Overview Heading.
- BPELModulePartnerLinks - Defines the location where the Module PArtner LinksSummary information will be written. This information will be obtained from the call to getBPELModulePartnerLinksText(TProcess process) in the generation class. The information returned will be written into the example template below the PartnerLinks Heading.
- BPELModuleTechnicalInformation
- Defines the location where the Module Technical information
will be written. This information will be obtained from the call to getBPELModuleTechnicalInformationText(TProcess
process) in the generation class. The information returned will
be written into the example template below the Technical Information
Heading. In addition a graphic representing the whole of the business
process will be inserted into the document.
- BPELModuleVariables - Defines the location where the Module Variable Summary information will be written. This information will be obtained from the call to getBPELModuleVariablesText(TProcess process) in the generation class. The information returned will be written into the example template below the Variable Heading.
The methods mentioned above are Abstract methods within the Abstract Document Generator class and will be overridden in the implementation class to provide the appropriate information. Extending the documentation functionality by writing your own concrete class will be the subject of another blog entry.
Configuration File
When executing the Document Generation you will need to specify a configuration properties file which I will describe below:
| Property |
Description |
|---|---|
| document.writer.class |
Defines the document generation
concrete class to be used for generating the document information. As
mentioned how you write your own will be the content of another blog
entry. At the moment only the default
com.tox.doc.gen.oo.SimpleBpelWriterDocumentGenerator exists. |
| svg.generator.class |
Defines the SVG Generation
Concrete class that will be used to generate the SVG from the BPEL
process. At present only the default
com.tox.doc.gen.svg.SimpleBatiksBpelSvgDocumentGenerator exists. |
| svg.icon.source.dir |
Specifies the source directory
for the icons to be used in the generation of the SVG document. Each
icon must have the appropriate name to match the Activity it is used
for. The examples of this can be found in the attached SVG Icons zip
file. |
| svg.icon.extension |
Defines the extention of the
icons to be used. |
| open.office.exe.folder |
Specifies the program folder for
your OpenOffice installation; e.g.
C:/Software/OpenOffice3.1/OpenOffice.org 3/program |
| odt.template.name |
Fully qualified name of the
OpenOffice document to be used as the template. |
| odt.output.directory |
Destination Directory |
| odt.save.pdf |
Flag to indicate if the document
should be saved as a pdf. |
| odt.save.odt |
Flag to indicate if the document should be saved as a OpenOffice odt. |
| odt.save.html |
Flag to indicate if the document should be saved as html. |
| odt.save.doc |
Flag to indicate if the document should be saved as a Word doc. |
| odt.close.after.generation |
Flag to indicate if the
generated document should be closed after generation. |
| odt.increment.headings |
Indicates if the Heading style
should be incremented. |
| odt.image.vertical |
Flag to indicated if the
generated SVG for the BPEL should be vertical (true) or horizontal
(false). |
| odt.image.show.flow |
Flag to indicate if an image of
the flow content should be displayed. |
| odt.image.show.foreach |
Flag to indicate if an image of the for each content should be displayed. |
| odt.image.show.if |
Flag to indicate if an image of the if content should be displayed. |
| odt.image.show.pick |
Flag to indicate if an image of the pick content should be displayed. |
| odt.image.show.repeatuntil |
Flag to indicate if an image of the repeat until content should be displayed. |
| odt.image.show.scope |
Flag to indicate if an image of the scope content should be displayed. |
| odt.image.show.sequence |
Flag to indicate if an image of the sequence content should be displayed. |
| odt.image.show.while |
Flag to indicate if an image of the while content should be displayed. |
| odt.image.embed | Indicates if the generated
images should be embedded into the generated document or simply linked
to. In general embedded will be more appropriate but if you choose to
save the document as html then it may be better choosing to link the
images. |
Example
Two execute the generation class I have provided an example bat file which should be modified to match you installation.
SETLOCAL
@ECHO OFF
SET DOCGEN_HOME=C:\Development\NetBeansModules\BPELDocumentation\BpelDocumentGenerator
SET OPENOFFICE_HOME=C:\Software\OpenOffice3.1\OpenOffice.org 3
SET OPENOFFICE_HOME=C:\Program Files\Sun\StarOffice 9
SET BATIK_HOME=C:\Software\java\batik-1.7
SET OPENOFFICE_LIB=%OPENOFFICE_HOME%\lib
SET OPENOFFICE_CLASSPATH=%OPENOFFICE_HOME%\URE\java\juh.jar;%OPENOFFICE_HOME%\URE\java\jurt.jar;%OPENOFFICE_HOME%\URE\java\ridl.jar;%OPENOFFICE_HOME%\Basis\program\classes\unoil.jar
SET MY_CLASSPATH=%DOCGEN_HOME%\dist\BpelDocumentGenerator.jar
SET BATIK_CLASSPATH=%BATIK_HOME%/lib/batik-anim.jar;%BATIK_HOME%/lib/batik-awt-util.jar;%BATIK_HOME%/lib/batik-bridge.jar;%BATIK_HOME%/lib/batik-codec.jar;%BATIK_HOME%/lib/batik-css.jar;%BATIK_HOME%/lib/batik-dom.jar;%BATIK_HOME%/lib/batik-ext.jar;%BATIK_HOME%/lib/batik-extension.jar;%BATIK_HOME%/lib/batik-gui-util.jar;%BATIK_HOME%/lib/batik-gvt.jar;%BATIK_HOME%/lib/batik-parser.jar;%BATIK_HOME%/lib/batik-script.jar;%BATIK_HOME%/lib/batik-svg-dom.jar;%BATIK_HOME%/lib/batik-svggen.jar;%BATIK_HOME%/lib/batik-swing.jar;%BATIK_HOME%/lib/batik-transcoder.jar;%BATIK_HOME%/lib/batik-util.jar;%BATIK_HOME%/lib/batik-xml.jar;%BATIK_HOME%/lib/js.jar;%BATIK_HOME%/lib/pdf-transcoder.jar;%BATIK_HOME%/lib/xalan-2.6.0.jar;%BATIK_HOME%/lib/xerces_2_5_0.jar;%BATIK_HOME%/lib/xml-apis-ext.jar;%BATIK_HOME%/lib/xml-apis.jar;
SET CLASSPATH=%CLASSPATH%;%OPENOFFICE_CLASSPATH%;%BATIK_CLASSPATH%;%MY_CLASSPATH%
ECHO "*********************** CLASSPATH *********************************"
ECHO MY_CLASSPATH = %MY_CLASSPATH%
ECHO OPENOFFICE_CLASSPATH = %OPENOFFICE_CLASSPATH%
ECHO BATIK_CLASSPATH = %BATIK_CLASSPATH%
ECHO CLASSPATH = %CLASSPATH%
ECHO "*********************** CLASSPATH *********************************"
java -Djava.util.logging.config.file=C:/Development/NetBeansModules/BPELDocumentation/BpelDocumentGenerator/src/logging.properties com.tox.doc.gen.GenerateBpelDocumentation -f C:\Temp\BpelModule1\src\bpelModule1.bpel -c C:\Temp\DocGenTest\resources\config.properties
If we take the following BPEL Process as an example and then run the Documentation Generator against it the resulting pdf will look like the example below.
