Home Page FO Designer 1.6. XSL-FO Editor for the Java[TM] Platform
Home
FO Designer
Introduction
Documentation
Videos
Version history
PDF interactive forms
Free FOP server
Oracle Application Express
APEX Plugin
SAP XI / PI
Oracle BPEL
Mule ESB
Apache Cocoon
Download
Pricing & Purchase
License
SAP XI / PI

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

  1. SAP PI 7.1 or later (we can also help you with previous versions, contact us in this case).
  2. 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:

  1. Download the file FOApp.sda. Note this is an evaluation version. The registered version is available for registered users of the J4L FO Designer.
  2. Copy the downloaded file to /usr/sap/<systemID>/SYS/EPS/in
  3. start the JSPM tool running the start script in the  /usr/sap/<systemID>/<central instance name>/j2ee/JSPM directory
  4. 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:

  1. start FO Designer 
  2. load the XML schema  file. You normally can export the schema file from the SAP PI repository.
  3. load the XML data file (this is any example XML document you may have)
  4. design your report and save it
  5. 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:

  • type "Local Enterprise Bean"
  • name localejbs/J4LFO
  • the module will require these 2 parameters:
    • parameter 1 name= defFile
    • parameter 1 value = /shared/orderdef.xml
    • parameter 2 name= action
    • parameter 2 value = convert

    Parameter defFile can be skipped if you are converting the Text and not to XML.