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

Chapter 5. Building the base scenario: Stage 2 181

Some developers may prefer to use a third party XML parser to interface with their forms.

Depending on the parser and the types of tasks to be performed, this may provide some

benefits in terms of speed or developer comfort (if the developer has a great deal of

experience with XML parsers).

However, the API is able to perform some tasks that are impossible for an XML parser. For

example, computes can continue to run in the form (or be activated by the API) while the form

is in memory, so any form data that is dependent on continuously evaluated computes will

remain accurate. Additionally, since most applications use compressed forms, which cut down

transmission speeds and use of disk space dramatically, the API is able to automatically

decode Base 64 data and uncompresses forms as it reads them. With an XML parser, you

must force it to decode and uncompress the forms to run them.

The API also provides methods for verifying and handling digital signatures. Most applications

need to verify signatures on the server side, and occasionally even apply signatures on the

server. These tasks are virtually impossible to perform without the Workplace Forms API. The

API can also encode and decode data items stored such as images, enclosures, and digital

signatures. In the case of images and enclosures, this means that using the API it is possible

to extract attachments or images from the form and store them separately on the server, or

insert attached files into forms as they are sent out to the user.

5.4.3 Form prepopulation

In this stage we will provide server side prepopulation (Figure 5-6) using the Forms API.

Server side form prepopulation takes place before a user opens a form. The engaged module

(such as a servlet) takes control over the initial XFDL form (stored form or empty template as

file or stream), accesses the internal values (using API or text parsing) and submits the

changed XFDL file / stream to the invoking instance (the viewer or any other module

requesting the form).

Figure 5-6 Server side form prepopulation

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

The basic idea is here to get the original XFDL information (template), transform it adding

external data to the form and then send it to the client. Assuming an invocation URL fired from

the client browser to open a form, in a servlet environment, prepopulation will occur usually in

the doGet method. The URL must now point to the servlet (not directly to the stored template

on file system) and contain a reference to the chosen template.

Form download based on a POST action fired by a browser or another system would be

handled in the doPost method. This will not occur in our scenario, but it is possible to do so.

The coding in Example 5-17 gives a simple example of how prepopulation can be done in the

doGet method.

Example 5-17 Prepopulation executed in doGet servlet method

public void doGet(HttpServletRequest request, HttpServletResponse response)

throws ServletException, IOException {

try {

//get the tem plate oath from the request parameter “template=”

String formTemplate = request.getParameter("template");

FileInputStream fis = new FileInputStream(formTemplate);

XFDL theXFDL = IFSSingleton.getXFDL();

FormNodeP theForm = theXFDL.readForm(fis,XFDL.UFL_SERVER_SPEED_FLAGS);

....

//Set some internal values like this

//address the internal element to update using xfdl specific pathes.

String mgrThreshold = “10000”;

theForm.setLiteralByRefEx(null,

"global.global.xmlmodel[xfdl:instances][3][null:BusinessRuleParams][null:QuoteLevelOneThres

hold]",0, null, null, mgrThreshold);

.....

//Return the prepopulated form

response.setContentType("application/vnd.xfdl");

theForm.writeForm(response.getOutputStream(), null, 0);

} catch (Exception doGetE) {

System.out.println("SubmissionServlet: doGet: Exception processing request: "

+ doGetE.toString());

returnText(response,"SubmissionServlet: doGet: Exception occured: "

+ doGetE.toString(), "text/plain");

{

}

As discussed in Stage 1, it is a best practice to access form data using data instances, not

field values. The example above does access an data instance (in the code, see reference

global.global.xmlmodel[xfdl:instances][3][null:BusinessRuleParams][null:QuoteLevelOneThresh

old

), but the instance is selected by position ([3])- not by name. This can break when

instances are moved in the form. As in value extraction, there is a better way to reference the

instance by instance ID.

The next example shows how to address a field value synchronized with an XFDL data

instance by position or by name. See the following data instance in the XFDL form

(Example 5-18).