IBM Workplace Forms: Guide to Building and Integrating a Sample Workplace Forms Application

Chapter 9. Domino integration 313

9.5.3 Template Database: Receiving submitted forms in Domino

A submitted form will be passed to the server as content in a POST requests. Domino can

receive POST requests running an agent and retrieve the content using CGI variables.

Unfortunately there are limitations to the size of received information. Actually a CGI variable

can store messages with up to 30.000 characters. For bigger submits other techniques must

be engaged.

This is the point where a servlet comes into the game. Basically we will have two benefits

from using a servlet to receive POST messages:

򐂰 There is an unlimited length for the contained data.

򐂰 Using Java, we can utilize all benefits coming with the Forms API.

Figure 9-28 shows the main components engaged in receiving submitted documents.

Figure 9-30 Flow on form submission to Domino

To build this scenario, we have to create the following components:

򐂰 The receiving servlet named ProcessXFDL and accordingly the deployment information

(setvlets.properties file on Domino server)

򐂰 A form in the Template Database capable of storing the incoming documents along with

the extracted metadata (QuotationRequest documents)

򐂰 A maintenance view for these documents

򐂰 A lookup view for the servlet to find the corresponding request document for the incoming

XFDL form on the server (if there is any)

Now, let us build these components.

314 IBM Workplace Forms: Guide to Building and Integrating a Sample Workplace Forms Application

ProcessXFDL servlet receiving incoming XFDL documents

Building the servlet can be done using eclipse, RAD6, or any other Java development

environment. The servlet is contained in a single Java file. There is some basic information

needed to configure the servlet. This can be done in the servlet.properties file, or it can be

read from the incoming XFDL document or from any other datasource). What portion of

information comes from what data source will depend on the environment and design guides

in place. In this redpaper we will read all information from servlet.properties file.

The servlet should process the following tasks:

򐂰 Read setup information (init method). Since our setup information is static (stored in the

servlet.properties file), we can read it in the init method.

– Identify the database and form and field name to store the request document.

– Connect to the database (username/password).

– Detect the data instance ID to extract from the incoming XFDL form.

򐂰 Receive incoming POST messages (this will be done in the doPost method):

– Extract the Success URL from the incoming message (URL parameter).

– Read the incoming XFDL form.

– Extract the assigned data instance from the XFDL file using the Forms API.

– Read the custom ID from XFDL using the Forms API. This will be the key to search for

a related request document in the target database.

– Prepare the XML stream for the DXLImporter for document creation/update with the

extracted data instance.

– Run the DXLImporter to create/update the request document.

– Store the received XFDL file to the just-created/updated request document as an

attachment.

– Submit the Success URL to the browser.

򐂰 Receive GET messages (for debug purposes only). The doGet method will submit the

settings read from the servlet.properties file rendered in an HTML page.

The full servlet code is given in Example 9-16. For details, see the in-line comments.

Example 9-16 Listing of full servlet code

/**

* @version 1.0

* @author Cees Vandewoude, Andreas Richter

* @comment Improved simple servlet version for IBM Workplace Forms Integeration

* Redpaper

*/

import java.io.*;

import javax.servlet.*;

import javax.servlet.http.*;

import lotus.domino.*;

import java.util.Vector;

Note: The servlet.properties file can store multiple virtual addresses for the same servlet

and assume, for each virtual address, different parameters. This makes it possible to use

one generic servlet processing different XFDL forms.

Chapter 9. Domino integration 315

import com.PureEdge.DTK;

import com.PureEdge.xfdl.FormNodeP;

import com.PureEdge.xfdl.XFDL;

import com.PureEdge.IFSUserData;

import com.PureEdge.IFSUserDataHolder;

import com.PureEdge.error.UWIException;

import com.PureEdge.IFSSingleton;

public class ProcessXFDL extends javax.servlet.http.HttpServlet implements

javax.servlet.Servlet {

// form name or alias to store the xfdl document and data

String form;

// relative path to target database to store the xfdl document and data

String dbPath;

// field to store the request

String targetField;

// file name for the created attachment containing the POST data

String fileName;

// debug mode (will print to console, if set to "on"

static String debugMode;

// content type for incoming message. Will be assigned to the mime entity

String contentType;

// username to create domino session and access target database

String userName;

String password;

//Data instance to t´retriece

String instanceID;

// servlet name

static String sv;

// initi params for Forms API

private static FormNodeP theForm;

static DxlImporter importer = null;

public void init(ServletConfig config) {

// Read servlet configuration parameters

try {

super.init(config);

sv = this.getClass().getName();

//read values from servlets.properties

debugMode = config.getInitParameter("debugMode");

if (debugMode == null)

debugMode = "on";

if (!(debugMode.equals("on")))

debugMode = "off";

debugOut(" debugMode: '" + debugMode + "'");

dbPath = config.getInitParameter("dbPath");