Introducing IBM Workplace Forms Server API 2.5

Josephine E. Justin, Staff software engineer, IBM, Software Group

Josephine E. Justin is a staff software engineer in the IBM India Software Labs. Her areas of expertise include IBM WebSphere Portal, IBM Workplace Web Content Management, and IBM Workplace Forms. She has more than five years of experience in J2EE.

Summary: If you are new to Workplace Forms application development, get an overview of the IBM Workplace Forms Server API in this article that introduces you to some of the more common classes in the API and that provides a sample application for download.

Date: 18 Apr 2006
Level: Intermediate
Comments:

IBM Workplace Forms 2.5 provides the end-to-end platform for managing the lifecycle of an electronic form (e-form) from design to validation to storage and retrieval of the e-form. The platform on the server-side provides an API for necessary processing of the form details. The API provides the capabilities to store and retrieve the form, to validate the digital signatures associated with the form, to extract form data elements and file attachments, and to operate on the XML instance of data from the e-form. This article explains how you can use the IBM Workplace Forms Server API to realize these functionalities. It is intended for application developers familiar with Workplace Forms and experienced in XML.

IBM Workplace Forms Server API overview

The Workplace Forms Server API allows you to develop applications that can interact with extensible forms description language (XFDL) forms. The API also lets you access and manipulate e-forms as structured data types. All classes of the Workplace Forms Server API belong to the Package com.PureEdge.

The Workplace Forms Server API is broadly divided into two libraries: the Form library and the Function Call Interface (FCI) library. The Form library allows you to create applications that:

Read and write forms
Retrieve information from the form elements
Insert information into form elements
Manipulate and verify digital signatures
Retrieve and store attachments

The FCI library provides additional methods that:

Create packages of functions for XFDL forms
Set up the packages as extensions for Workplace Forms Viewer or Designer
Determine how and when the functions are used

This article focuses on the Form library. Creating custom functions and form extensions, which is part of the FCI library, is not covered in this article.

Database interactions and interactions with external systems and services is independent of the Workplace Forms Server API. You can use the Workplace Forms Server API within a Java servlet or within a portlet. Then you can use the servlets or portlets to interact with a database or an external system.

Overview of e-form structure

Understanding how an e-form is structured helps you to use the API appropriately and to refer to the form elements correctly. This section introduces the node structure, node hierarchy, and the way to reference an e-form item.

Node structure

When an e-form is loaded into memory, it is denoted as a series of linked nodes -- each node representing the e-form element. Together these nodes create a tree that describes the e-form. Each node in the tree has four properties:

Type. Represents the type of node, such as page, button, field, and so on.
Literal. Represents the value of the node.
Identifier. Represents the unique identifier for the node.
Compute. Represents the compute statement assigned to the node.

NOTE: Depending upon the type of node, some or all of these properties may be null.

Node hierarchy

Each node in the tree formed when the e-form is loaded into the directory is part of an overall hierarchy. The following are the elements in the hierarchy in descending order:

Form. Every e-form has a form-level node, and this is the root node of the tree.
Page. Each e-form has pages that are represented as children of the form node. There are at least two page nodes as part of each e-form -- one for the global page that stores the global settings and one for the first page of the e-form.
Item. Each page contains e-form items. Each page contains at least one global item to set global properties for that page.
Option. Each item contains options.
Arguments. Each option may contain settings or arguments.

References

References provide the path to each item in the node hierarchy, which allows you to identify the specific page, item, option, or argument. The syntax follows this general pattern:

page.item.option[argument]

in which page, item, option, and argument are part of the node hierarchy. For example, in the sample application that you can download with this article, to refer to the value of the item named field1 in the page named PAGE1, the syntax is:

PAGE1.field1.value

Dereferencing

Dereferencing allows you to make a dynamic reference that is evaluated at runtime. This is necessary sometimes because the item node to be referenced in the node hierarchy may depend upon the user action. For example, you can use dereferencing to retrieve the value of a selected cell from a popup or list item.

Namespaces in references

Namespaces are used to identify the information in the XML document. Similarly, the XFDL namespace contains information to describe e-forms. When you create a Workplace e-form using Workplace Forms Designer, the XFDL form is automatically added with the following two namespaces:

XFDL. Prefixed by xfdl, this namespace is used to identify all e-form-related XML.
Custom. Prefixed by custom, this namespace is defined as a convenient place for e-form developers to store custom information, such as metadata and computes.

Workplace Forms allows the usage of any additional namespaces also as part of the e-form.

Core classes of IBM Workplace Forms Server API

The following is a list of core classes for the Workplace Forms Server API Form library.

DTK class

The DTK class is used to initialize the Form library. This is the first class that you use as part of the API.

XFDL class

The XFDL class includes methods to load an e-form into memory from the specified file or stream. This class also creates root nodes of the e-form. This class can also be used to create new nodes.

IFSSingleton class

The IFSSingleton class provides a static interface to the application's XFDL object.

FormNodeP class

As noted in the section "Overview of e-form structure," when an e-form is loaded into memory, it is represented as linked nodes. Each of these nodes, regardless of their hierarchical level, is represented by a FormNodeP object. The functions available in the Form library provide methods to perform the following:

Duplicate nodes
Populate nodes
Navigate nodes
Retrieve information from nodes
Destroy the e-form to remove it from memory (This can be done by calling the destroy method at the root node of the e-form.)

Miscellaneous classes

These are additional classes that you may find helpful when using the Workplace Forms Server API Form library.

Certificate class

The Certificate class allows you to work with certificates. It allows you to retrieve the binary long objects and to retrieve certificate details from the certificates used when signing an e-form.

Hash class

The Hash class allows you to hash the messages. This class is used when validating Authenticated Clickwrap signatures, which contain a hash of a shared secret, which identifies the signer.

LocalizationManager class

The LocalizationManager class lets you set the locale for reporting errors. The Workplace Forms Server API supports only en_US and fr_CA locales in version 2.5. By default, the Workplace Forms Server API uses English.

SecurityManager class

The SecurityManager class can be used to retrieve the hash object. This hash object would be used to hash the shared secrets for the Authenticated Clickwrap signatures.

Signature class

The Signature class allows you to work with signature objects in an e-form. Workplace Forms supports different kinds of signatures, such as RSA, Clickwrap, and Authenticated Clickwrap. Depending upon the type of signature, you can use the Signature class to retrieve different pieces of data from the signature enclosed in the e-form or to extract the signing certificate from the signature.

Now that you have a basic understanding of the Workplace Forms Server API, let's proceed to installation of the Workplace Forms Server API on your IBM WebSphere Application Server. This article assumes that you have already installed IBM Workplace Forms Server 2.5.

Installing and setting up the Workplace Forms Server API on WebSphere Application Server

To setup the Workplace Forms Server API to work with WebSphere Application Server, perform the following procedure.

On your Workplace Forms Server, locate the directory <Workplace Forms Server Directory>\x.x\API\redist\msc32, in which x.x is your version of IBM Workplace Forms.
Within this directory, locate the following DLL files:
- MSLUR71.dll
- pe_cc.dll
- pe_com.dll
- pe_java.dll
- unicows.dll
- uwi_java.dll
Copy these DLL files into the WebSphere Application Server's bin directory.
Create a new text file called PureEdgeAPI.ini that includes the following lines, and then place this file in the <WebSphere install dir>\AppServer\java\bin directory:
[API] *=<<Workplace Forms Server Directory>>\redist\msc32\PureEdge\xx
Change xx to the version of IBM Workplace Forms installed on your server.

Giving WebSphere Application Server access to the API JAR files

Grant the WebSphere Application Server access to the API's JAR files for use.

Create a directory <WebSphere installation directory>\AppServer\shared.
Locate the directory <Workplace Forms Server Directory>\redist\msc32\PureEdge\xx\java\classes.
Copy the following files from the previous directory into the directory created in step 1:
- pe_api.jar
- pe_api_native.jar
- uwi_api.jar
- uwi_api_native.jar

Creating a library for the API JAR files

Now, create a library for the Workplace Forms Server API JAR files.

Select Environment - Shared Libraries.
Click New to create a new shared library.
In the Name file field, type PureEdgeLib.
In the Classpath field, provide the path to the JAR files copied in the previous procedure.
Click Apply, and then save the configuration to the master.

Adding IBM libraries to the WebSphere Application Server ClassLoaders

Now, add the Workplace Forms Server API library to the WebSphere Application Server classloader so that the APIs are available at the server startup.

From the WebSphere Application Server Administrative Console, select Servers - Application Servers.
Under Application Server, select the server on which you installed the Workplace Forms Server API.
Under Configuration, select Classloader.
Under Classloader, click New.
Under Configuration, click Apply, and then click Libraries.
Under Library Ref, click Add.
In the Library name drop-down list, select PureEdgeLib.
Click Apply.
Click Save.

Now that you have installed the Workplace Forms Server API and configured the WebSphere Application Server, you can download and install the Workplace Forms sample application that accompanies this article. You may need to restart the server before installing the sample application.

Using the sample application

The sample application, WFAPISample, demonstrates how to use the Workplace Forms Server API. After you download the sample application, install it on the WebSphere Application Server using the Administrative Console. Provide WFAPISample as the context root to the application. After you deploy the application on WebSphere Application Server, start the application. To view it, access the URL http://<IP address>:9080/WFAPISample in your Web browser.

This sample application is used to showcase the following features of the Workplace Forms Server API:

Initialize the Form library
Display a new/submitted e-form to the application user
Retrieve the e-form field values
Retrieve the e-form attachments
Verify digital signatures in the e-form
Retrieve information contained in the digital signature
Extract the XML instance contained in the e-form with the values provided by the application user
Store the submitted e-form in the local file on the server

This sample application stores all e-forms submitted by the user. These submitted e-forms are available to view and may be submitted again with a new set of data. This application contains a sample e-form. This e-form has two input fields: Input Field 1 and Input Field 2. It also allows you to add attachments to the application that can be processed and saved on the server. This e-form is also secured by digital signature, which can also be verified and validated by the server.

The following screenshot (figure 1) shows the e-form used by the sample application to showcase the features of the Workplace Forms Server API.

Figure 1. Sample e-form

This application provides the list of new e-forms available in a file system folder and also lists the submitted e-forms. Users can view the new or submitted e-forms. Once viewed, users can fill in the items in the e-form and submit it to the server for processing.

For retrieving the value of an e-form field, you can use the node hierarchy to identify an item. The value of the e-form field field1 in the page PAGE1 is retrieved using the getLiteralByRefEx() method.

This sample application has a servlet that extends the PureEdgeServlet so that the Workplace Forms Webform Server can translate from XFDL into HTML and JavaScript. If this feature is not expected as part of the Web application, then you can extend the servlet from HttpServlet.

In the init() method, the necessary folders for storing the submitted e-forms and the attachments or any other resources are created. This servlet initializes the Form library by calling the initialize() method on the DTK class.

DTK.initialize("FormsHandler", "1.0.0", "6.5.0");

The sample e-form is read into the memory by reading from the file input stream.

//Retrieve the Input stream for the form from the file
	fis = new FileInputStream(file);    
// Obtain the XFDL object to read a form
	XFDL theXFDL = IFSSingleton.getXFDL();   
// From the XFDL object, read the form using the file inputstream.
// Compute Engine is turned off when reading the form for better performance
	theForm = theXFDL.readForm(fis, XFDL.UFL_SERVER_SPEED_FLAGS);

The sample e-form can be written to the response output stream or to the file system using the writeForm() method.

// Writes form to the response output stream theForm.writeForm(request.getOutputStream(), null, 0);

String field1 = theForm.getLiteralByRefEx(null, "PAGE1.field1.value", 0, null, null);

To retrieve the file attachment use the dereferenceEX() method, and then call the extractFile() method to extract the attachment from the e-form.

tempNode = theForm.dereferenceEx(null, "PAGE1.TestSingle", 0, FormNodeP.UFL_ITEM_REFERENCE , null); tempNode.extractFile(resourceStorageDir + File.separator + attachmentFileName);

This sample application uses the Clickwrap signature, which has two questions: name and age of the signer. To verify the digital signature, verifyAllSignatures() is used in this sample application to check the correctness of the digital signature. Individual signatures can be retrieved from the FormNodeP object. To retrieve the details contained in the signature, the sample application uses the Signature class.

// This verifies the signatures present in the form
	theForm.verifyAllSignatures(false); 
	tempNode = theForm.dereferenceEx(null, "PAGE1.SIGNATURE1", 0, 
	FormNodeP.UFL_ITEM_REFERENCE, null);
//Signature object is used to retrieve the signature details.
	Signature theSignatureObject = tempNode.getSignature(); 
// Holder object to hold the return parameter
	BooleanHolder encodedData = new BooleanHolder(); 
//Retrieve the Signature details
	String signerCommonNameQuestion = theSignatureObject.getDataByPath
	("Question1Text", false, encodedData);
	String signerCommonName = theSignatureObject.getDataByPath
	("Answer1Text", false, encodedData);
	String signerAgeQuestion = theSignatureObject.getDataByPath
	("Question2Text", false, encodedData);
	String signerAge = theSignatureObject.getDataByPath
	("Answer2Text", false, encodedData);

The XML data model is intended to ease integration with other XML processors. The XML data model allows you to copy information from the XFDL form to an XML file that you can format so that the XML processor processes the XML instance instead of the whole XFDL form. Each XML instance has three basic parts:

Instance data. Each XML instance is a collection of data elements.
Bindings. Each data element can be mapped to one or more XFDL form elements. This creates a binding between that data element and the form elements.
Submission rules. Each instance may define submission rules. These rules determine the data to be filtered and other related properties.

These XML instances can be directly submitted to a backend XML processor. This sample application submits the whole XFDL form; the XML instance is extracted using the API.

The sample form also holds an XML model that binds with the two form field values, field1 and field2. The XML form instance can also include the namespace used. The data instance is placed in the custom namespace by default. This sample instance uses the default namespace. The instance is also provided with an identifier that uniquely identifies the instance.

<xmlmodel xmlns:xforms="http://www.w3.org/2003/xforms">
  <instances>
    <xforms:instance xmlns="http://test.ibm.com" id="UserAuthenticationResponse">
      <getUserAuthenticationResponse>
         <field1></field1>
         <field2></field2>
      </getUserAuthenticationResponse>
     </xforms:instance>
   </instances>
   <submissions></submissions>
   <bindings>
     <bind>
       <ref  xmlns:default="http://test.ibm.com">
[default:getUserAuthenticationResponse][default:field1]
</ref>
       <boundoption>PAGE1.field1.value</boundoption>
     </bind>
     <bind>
 <ref xmlns:default="http://test.ibm.com">
 [default:getUserAuthenticationResponse][default:field2]
 </ref>
       <boundoption>PAGE1.field2.value</boundoption>
     </bind>
   </bindings>
</xmlmodel>

When the user submits the form with field values provided, the sample application extracts an instance from the XML data model, creating an XML file that can be passed off for processing. The extractInstance() method is provided with the identifier of the XML instance and the namespace provided in the e-form:

theForm.extractInstance("UserAuthenticationResponse", null, "default",xmlFileName, 0, null, null, null);

Conclusion

This article introduced you to the IBM Workplace Forms 2.5 API and also provided a sample application that demonstrates the use of API. You can extend this application to include a Business Process Execution Language (BPEL) based instance within the XML model; and you can use it to invoke business logic and rules. You can also extend this sample application to include a digital certificate.

Download