Body

How to use IBM Form Lookup function
Author: Tao Liu (tltaoliu@cn.ibm.com)

This document introduced the development of IBM Form lookup function during BPF to ICM transition project,
Introduction
IBM Form provides a Lookup Extensions interface that allows custom lookup capability to be provided for individual Case fields in such a way that one of three possible results will always occur for a correctly configured lookup.

• If more than one matching record is found, a popup will be displayed showing the fields and values for each record in a tabular form. When the user clicks on one of the rows in this popup table, the configured Case field(s) will be updated with the selected value(s).

 
 
 
 
 
 
 
 
 
 
 
 
 
 

• If user select one record and click finish button, the configured Case field(s) will automatically be updated with the value(s) returned. The screen shot shown user choose the record with ID “14-123”, then the case fields “Customer Name”, “Customer Number” and “Date” is automatically updated with the value(s) returned.

In the guide, I will show you how to develop a custom JSP page to implement the Lookup function. It can be divided into two steps. One step is to design the lookup button on IBM Form template in the IBM Form designer. The other step is to develop the JSP page.
Develop a custom lookup function by JSP
Step 1. Design the lookup button on IBM Form template
You can follow below steps to Design the lookup button:

1.Create a Button on the form template.



Another thing you need to know is how to send the parameter the JSP page. Since the lookup results should base on the input value of the lookup field, the value of the lookup field must be send to the JSP page. We used the Http Get method here. In the script, below code is added to the JSP:
key='+. get('instance("Generated")/page1/pane1/pane5/field9', '', 'xforms')
Key is the parameter name in httpRequest. And the Form function get(reference, referenceType, scheme) is used to return the value of the case field. There are 3 parameters for the function. The first parameter “reference” is the most important. It is the reference of the case field. To get the reference value of the field, you can click the filed on the form template in Form designer, and then switch the viewer to source, and then the reference can be found, such as:
<field sid="FIELD9">
                     <xforms:textarea ref="instance('Generated')/page1/pane1/pane5/field9">
The ref is the reference. The detailed instruction of function get is put in the appendix of this document.
Note: To enable source view, you must open the perspective to Advanced Lotus Forms Designer.



Step 2. Develop the JSP page

In the WebformSampleApp.ear I have developed a Look up JSP page dynamiclookup.jsp. I will take this JSP page as an example to explain how to develop to JSP. You can follow below steps to develop the JSP page:
1.Get the lookup key from the Http request. At step 1, the value of lookup case field is send to the JSP as a lookup key, the key can be gotten from Http request by following code:


3.After the user select one record, generate result XML and use form API XFDL.getCurrentForm().updateXFormsInstance(null, String theNodeRef, null, String theUpdateXML, XFDL.UFL_XFORMS_UPDATE_REPLACE) to update the form fields.
In the updateXFormsInstance API, the most important parameter is theNodeRef and theUpdateXML

• theNodeRef

It is An XPath reference to the instance (or portion of an instance) you want to insert data into or replace. An empty string indicates the default instance of the selected model. Since At step1 we have found the xForm XML data model, and we can find the XPath reference is "instance('Generated')/page1/pane1/pane5".

• theUpdateXML

It is the input XML String that provides the data that replaces or adds to the XForms instance. Note that this data must be UTF-8. Since at step 1, we have found the xForm XML data model, and the XML is:
    <pane5>
             <field9></field9>
             <amount></amount>
             <date></date>
       </pane5>
Below code can be used to generate the updateXML:
Get
Gets the value of either an XFDL option or an element in the XForms model.
Syntax
   get(reference, referenceType, scheme)

The value of the form option reference or an empty string if an error occurs.
Examples
In this example, get retrieves the value of "Field1", which is "gold".
   <field sid="Field1">
      <label>Field 1</label>
      <format>
         <datatype>string</datatype>
         <constraints>
            <mandatory>on</mandatory>
         </constraints>
      </format>
      <value>gold</value>
   </field>
   <field sid="Field2">
      <label>Test get()</label>
      <format>
         <datatype>string</datatype>
      </format>
      <value compute="get('Field1.value')"></value>
   </field>
The following sample demonstrates how to use the get function to retrieve a value (“Tatyana Kartoff”) from the XForms data model element “name”:
   <xforms:instance id = 'loan'>
      <loan>
         <Borrower>
            <Name>Tatyana Kartoff</Name>
            <Address>
               <street></street>
               <city></city>
               <state></state>
               <country></country>
            </Address>
        ...other data model elements...
         </Borrower>
      </loan>
   </xforms:instance>
   <field sid="Field2">
      <label>Test get()</label>
      <format>
         <datatype>string</datatype>
      </format>
      <value compute="get('instance(&quot;loan&quot;)/Borrower/Name', &#xA;
         '','xforms')"></value>
   </field>
Usage details

• The get function does not support XPath referencing for the entire form. Use XPath references only when getting data from the XForms data model.

• If you use the instance function to access a particular data instance, you must use the escape sequence for the quotations marks (&quot;) around the parameter. For example:  get('instance(&quot;loan&quot;)/Borrower/Name', '','xforms')
  

• If you intend to use the XForms scheme, you must surround the parameter with single quotation marks. For example:  'xforms'
  

• If you attempt to get the value of an element in the XForms data model, and that element is a parent (that is, it contains child elements), then the value of the first child text node is returned.

• If you reference an item that changes, the change does not automatically trigger a re-evaluation of the function.

• The get and set functions are the only XFDL functions you should use to modify the XForms