How to use FO Designer in Oracle BPEL and SOA suite
Introduction
Oracle BPEL in the Oracle SOA suite is a language for execution of business
processes based on web services and therefore based on XML. There are situations
where a business process might need to convert the XML documents to a human
readable PDF format. In this situations FO Designer can help you by providing
you:
- A way to create PDF from XML without need to learn XSL-FO language.
- High productivity by using a visual tool.
- A runtime module that can be integrated within a BPEL is just a few
minutes.
Requirements
- Oracle BPEL has been installed
- It is assumed you have some basic knowledge of Oracle BPEL.
Installation of the J4L FOP server
The J4L FOP server is a Java Servlet that can be deployed in the Oracle
Application Server. You have to download the file J4LFOPServer.war and
deploy it to your server from the Oracle Application Server Control.
This Java Servlet can be integrated in the Oracle BPEL as we will see later
using HTTP binding.
Note this servlet is an
evaluation version. The registered version is available for registered users
of the J4L FO Designer.
Example step by step
Overview
In this example we will convert the departmentEmployees.xml file to a PDF list
of employees as in the example included in FO Designer.
The BPEL works like this:
- The file adapter reads our departmentEmployees.xml file
- We invoke the Xml2Pdf service, this service takes as input:
- the departmentEmployees.xml document
- and the xsl-fo file used for converting to PDF. The xsl-fo file is
part of the URL used for invoking our J4LFOPServer application. The link
is:
http://localhost:8888/J4LFOPServer/FOPServerXML?template=c:/data/departmentEmployees.fo
note this URL is coded inside the WSDL file of the Xml2Pdf service.
- The output of the Xml2Pdf web service looks like this:
<pdfElement xmlns="http://java4less.com/pdf">
JVBERi0xLjQKJaqrrK0KNCAwIG9iago8PAovUHJvZHVjZXIgKEFwYWNoZSBGT1AgVmVyc2lvbiAw
Ljk1KQovQ3JlYXRpb25EYXRlIChEOjIwMTAwMTI4MjEzMzIwKzAxJzAwJykKPj4KZW5kb2JqCjUg
...
NzU2OEZCMEM+XQo+PgpzdGFydHhyZWYKNjI0NwolJUVPRgo=
</pdfElement>
this is
This is a simple XML file with the <pdfElement> tag which contains the
PDF file in Base64 format.
- Finally we use the file adapter to write the <pdfElement> to a PDF
file. For this we use an "opaque" variable, so the file adapter
will convert the base64 content to binary.
Download sample files
Download the sample files from EmployeesBPELOracle.zip.
In this file you will find a sample data file (departmentEmployees.xml), the
schema file (departmentEmployees.xsd) and the WSDL file for the Xml2Pdf service
(employees2pdf.wsdl). Additionally you will also find the bpel files we created
in your project which can useful for your reference while setting up this
example.
Create the BPEL
The following diagram shows the structure of the test BPEL:
The BPEL is made of the following steps:
- Create the directions c:/data/in, c:/data/out and copy
departmentEmployees.fo to c:/data/departmentEmployees.fo.
- Create a partner link called FileIN using the File adapter which is
used to read the file departmentEmployees.xml from the c:/data/in
directory. The schema associated to the file in located in public_html\departmentEmployees.xsd
- Create a Receive_1 step link it to the FileIN partnerLink. For this
you will need to create a variable called InVar.
- Create a partner link called Xml2Pdf and select the existing wsdl
file employees2pdf.wsdl for the service. Note if your Oracle
application server is not running on port 8888, you have to modify the employees2pdf.wsdl
file.
- Create a Invoke activity and link it to Xml2Pdf. You will need to
create 2 new variables for this, InPdfVar and OutPdfVar.
- Insert an assign activity after the Receive_1 step and copy
variable InVar to InPdfVar as shown in the screenshot
- Create a partner link called FileOUT which writes to the
c:/data/out file and uses an opaque schema.
- Create a Invoke activity, placed as last activity in the BPEL and link it to
FileOUT. You will need to
create 1 new variable, we called the variable OutOpaqueVar.
- Insert an assign activity before the last invoke activity and copy
variable OutPdfvar to OutOpaqueVar as shown in the screenshot
- Now you deploy the BPEL, copy the departmentsEmployees.xml file to
c:/data/in and the process will run. The PDF file will be written to the
c:/data/out directory.
How to create your own WSDL
The key point of the BPEL process is the employees2pdf.wsdl file. This
file contains the following items:
- the xml schema of the input document (departmentEmployees.xml).
- the xml schema of the output document (the PDF data in base64 format).
- the URL of the service, this URL contains the xsl-fo file name used for
the Xml to PDF conversion..
When you create your own WSDL file for your own XML document, you will have
to modify items 1 and 3.
The following WSDL file can be used as template to create your own Xml2PDF
services. Note the red lines have to be modified:
<?xml version="1.0" encoding="utf-8"?>
<!-- ENTER YOUR NAMESPACE IN THE DECLARATION BELOW -->
<definitions xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:tns="http://java4less.com/pdf/employees"
xmlns:pdf="http://java4less.com/pdf"
targetNamespace="http://java4less.com/pdf/employees"
xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
xmlns:plnk="http://schemas.xmlsoap.org/ws/2003/05/partner-link/"
xmlns="http://schemas.xmlsoap.org/wsdl/">
<types>
<!-- THIS IS THE SCHEMA OF OUR SAMPLE INPUT XML FILE, YOU SHOULD REPLACED IT WITH YOUR OWN XML SCHEMA -->
<xsd:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://java4less.com/pdf/employees">
<xsd:element name="departments">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="department" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="departmentName" type="xs:string"/>
<xsd:element name="person" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="name" type="xs:string"/>
<xsd:element name="address" type="xs:string"
minOccurs="0"/>
<xsd:element name="status" type="xs:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
<xsd:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://java4less.com/pdf">
<xsd:element name="pdfElement" type="xsd:base64Binary"/>
</xsd:schema>
</types>
<message name="GetPDFIn">
<!-- THE INPUT DOCUMENT MUST BE THE ROOT ELEMENT OF YOUR DOCUMENT, in our example it was departments -->
<part name="InputDocument" element="tns:departments"/>
</message>
<message name="GetPDFOut">
<part name="pdf" element="pdf:pdfElement"/>
</message>
<portType name="GetPDF">
<operation name="GetPDFMethod">
<input message="tns:GetPDFIn"/>
<output message="tns:GetPDFOut"/>
</operation>
</portType>
<binding name="PDFGetBinding" type="tns:GetPDF">
<http:binding verb="POST"/>
<operation name="GetPDFMethod">
<!-- IN THE LOCATION YOU REPLACE OUR SAMPLE TEMPLATE FILE WITH YOUR OWN FILE CREATED USING FO Designer -->
<http:operation location="/J4LFOPServer/FOPServerXML?template=c:/data/departmentEmployees.fo"/>
<input>
<!-- if the input message has several parts
<mime:content type="application/x-www-form-urlencoded"/>
-->
<!-- for get operations
<http:urlEncoded/>
-->
<mime:mimeXml part="InputDocument"/>
</input>
<output>
<mime:mimeXml part="pdf"/>
</output>
</operation>
</binding>
<service name="PdfService">
<port name="GetPDF" binding="tns:PDFGetBinding">
<!-- NORMALLY YOU WILL NOT MODIFY THE LOCATION http://localhost:8888, unless Oracle Application server uses a different port -->
<http:address location="http://localhost:8888"/>
</port>
</service>
<plnk:partnerLinkType name="PdfServicePartnerLink">
<plnk:role name="PdfServiceProvider">
<plnk:portType name="tns:GetPDF"/>
</plnk:role>
</plnk:partnerLinkType>
</definitions>
| 