J4L PDF modules for SAP PI
Introduction
The PDF modules for SAP PI provide capabilities for converting:
- XML to PDF
- PDF to XML
- PDF to TXT
- and creating PDF digital signatures
- starting with version 1.5 you can create (prefilled) PDF interactive forms and
extract data from PDF forms.
Requirements
- SAP PI 7.1 or later (we can also help you with previous versions, contact
us in this case).
- We assume you have SAP PI skills to be able to setup a simple file to file scenario.
Creation of a PDF file
A common approach for converting a XML document to PDF format in the SAP
integration product, SAP PI (previously XI), is the use of Apache FOP. Apache
FOP takes as input 2 parameters, the first one is the XML document to be
converted, the second is a formating file called xsl-fo which tells Apache FOP
how to do the conversion. These 2 inputs are used by Apache FOP to create the
PDF output.
J4L FO Designer is a visual tool you can use to create the xsl-fo file. You
can read aboutthe benefits of using J4L FO Designer in the main
page.
The
integration of Apache FOP within SAP PI can be performed in several way, among
them:
- writing a custom adapter module which is executed in communication channel
of SAP PI and creates the output PDF. This document describes this option.
- writing a custom servlet which can be called from an integration process
using the HTTP adapter. The Servlet would take as input an XML document and
return the PDF format. The disadvantage of this approach is you need to use
an integration process.
Deployment of the SAP PI module
The adapter module must be deployed in the JEE server, this can be done using
the JSPM tool as follows:
- Download the file FOApp.sda. Note this is an
evaluation version. The registered version is available for registered users
of the J4L FO Designer.
- Copy the downloaded file to /usr/sap/<systemID>/SYS/EPS/in
- start the JSPM tool running the start script in the /usr/sap/<systemID>/<central
instance name>/j2ee/JSPM directory
- Select type "hot fix" in the JSPM tool and deploy the file.
you can also use other options like deploying from the Netweaver Development
Studio.
Create the XSL-FO file using FO-Designer
The normal process for creating the XSL-FO file is:
- start FO Designer
- load the XML schema file. You normally can export the schema file
from the SAP PI repository.
- load the XML data file (this is any example XML document you may have)
- design your report and save it
- export the XSL-FO file from the FO Designer
However for an initial test within the SAP PI environment, you do not have to
do this, instead you can use our example examples\employees\departmentEmployees.fo
included in the J4L FO designer
evaluation version.
Load the XSL-FO file into PI
The XSL-FO file ( departmentEmployees.fo ) must be placed in a
directory which can be accessed from SAP PI.. For example, let's assume you
place the file in a directory called /shared.
Run the SAP PI scenario to convert from XML to PDF
Create a File to File scenario in SAP PI. The file departmentEmployees.xml
should be read from an input directoy by the file adapter a written to an
output direct using the file adapter. The receiver channel which writes to the
output directoy must contain the J4LFO module which will convert the XML
document to PDF. The configuration of the module must be:
- type "Local Enterprise Bean"
- name localejbs/J4LFO
- the only parameter of the module is the name of the xsl-fo file:
- parameter name= xslfo
- parameter value = /shared/departmentEmployees.fo
Adding digital signatures to the PDF File (J4L FO
Designer 1.4 or later)
You can use our the J4LFO module to add a digital signature to an existing PDF
file or to the PDF file you just created.
If you want to add a digital signature to the PDF file you have execute the
J4LFO module a second time after the PDF has been create. However before you do
that you need to:
- read the digital signature section in the FO
Designer user guide.
- request a certificate from a Certification Authority. You can also create
your own certificate with tools like openssl but in that case the intended
receivers of your PDF documents must add your own created certificate to
their list of trusted certificates. For testing purposes you can use the
certificate we provide in the certs subdirectory of the FO designer
distribution.
The configuration of the module must be:
- type "Local Enterprise Bean"
- name localejbs/J4LFO
- the only parameter of the module is the name of the xsl-fo file:
- parameter name= action
- parameter value = signature
- parameter name= p12file
- parameter value = /shared/j4l_test.fo
- parameter name= p12psw
- parameter value =test
Note from the configuration above that in the current version the private key
and certificate used for the signature have to be stored in the file system. In
this example the file /shared/j4l_test.fo. In future version this
file will be stored in the SAP keystore.
Creation of a PDF interactive form (J4L FO
Designer 1.5 or later)
PDF forms can be used for collecting data from your business partners, here
you can learn about a possible way to use it. SAP PI can be used to convert XML data to a PDF form which, for example, can be
sent by email to a customer.
Each customer would receive a PDF form with her own data. You can read about
such an example here.
PDF forms can be created exactly in the same way as regular PDF files. The
only difference is, when you design the PDF template using the J4L FO Designer
you have to define some fields as Input Fields. This process is described
in the user
guide. At runtime the process is exactly the same as described in this
section.
Extracting values from filled forms
You can use our module to extract the values from the form once it has been
filled by the user. The module must be configured in this way:
- type "Local Enterprise Bean"
- name localejbs/J4LFO
- the only parameter of the module is the action to be executed
- parameter name= action
- parameter value = extract
This will convert the PDF file in the main payload of the message, to XML.
The XML payload will have the format:
<formData>
<fields>
<field name="fieldname1">
<value>fieldvalue1</value>
</field>
<field name="fieldname2">
<value>fieldvalue2</value>
</field>
....
</fields>
</formData>
Converting a PDF file to XML
This section describes how to convert a PDF to XML or Text. Note however the
PDF file must contain text elements and not just an image. PDF files created by
scanners or faxes do not contain text and must be converted using a OCR software
(see our OCR tools)
Deploy the SAP PI module
See deployment section
Create a document definition file
If you are going convert the PDF file to Text there is no need to create a
definition file, however if you want to extract data from the text and put it
into a XML document, you must create a definition file as described here.
If order to run an example you can download the evaluation
version of J4L OCR tools and use the file orderdef.xml as definition
file. The file order.pdf will be used in the next section.
Run the SAP PI scenario to convert PDF to XML
Create a File to File scenario in SAP PI. The file order.pdf should be read from an input directoy by the file adapter a written to an
output direct using the file adapter. The receiver channel which writes to the
output directoy must contain the J4LFO module which will convert the XML
document to PDF. The configuration of the module must be:
| 