Taking Notez – Island Pond Consulting

Working with Web Services to Submit a Data Entry Form

When working with IBM Form Designer V8.0 you may want to submit an entire form page of  XForm data to a web service.  This is not a pattern typically thought of when interacting with web services. A more common example can be seen when pre-loading some form data. Another common example is employment of web services to dynamically populate list boxes contingent on other selections made on the form. In any case, a Web Services tool provides a mechanism for managing service inputs but there is a limitation to the default implementation.

In case you want a PDF of this blog article: IBM Form Designer- Working with Web Services | Taking Notez

Here’s how the tool works out-of-the-box.

FIgure 1: Web services panel

When you “wire” your form to a web service using the tool a wizard interface prompts for selection of a WSDL file or URL. Once a choice is made, the tool will display web service Inputs, Outputs, and other aspects of the form-service interaction such as the Trigger. The display of these items is found in the Web Services panel of the Outline view normally located at the bottom left of the Advanced IBM Forms Designer perspective.

In the Figure 1 note the names of members such as processSubmit and xfdlFormSubmitData. These names are generated by the designer from values defined in the web service WSDL file.

In Figure 2 observe these same names.  The members, or elements, are defined in the web service schema. Looking at the “Input” described by the tool (Figure 1) and the “processSubmit” described in the WSDL schema a clear correlation of element names should emerge.

For example, the tool represents two categories of input: “Header” and “Body”. Similarly, the web service schema also describes these two complex type elements.  Taking time to examine the WSDL schema assigned to your form development project will help you to understand how the data in your form will be handled by the service to which you send the data.

In the example provided in Figure 2 we can see that the header consists of seven discrete elements.

Figure 2. WSDL (web service) schema

Among them are formName, action, actionTarget, and actionType. This should suggest to the form developer that there would probably be specific XForm bound controls that will be mapped to these header elements. For example we can send the name of our form to the service in an element named formName by mapping the tool’s representation of the WSDL schema (Input > processSubmit > formName) to a specific XForm instance.  Mapping is described in detail later in this article.

In contrast, this WSDL shows that the body of service request should contain a single element named xfdlFormSubmitData (Figure 3).

Figure 3. xfdlSubmitFormData

The form developer will typically create a form with many XForm bound controls for data entry. However, the structure of this web service schema suggests that the service expects all of the XForm instances created by the form developer to be mapped to a single element.

How is this mapping done? The tool provides a convenient mechanism for mapping the web service inputs (and outputs) to XForm instances. The procedure labeled “mapping” can be performed in a couple of ways. One typically used for the service request header employs a drag and drop approach. The other, typically used for mapping data entry XForm instances, typically relies on use of a context menu.

In this example our design calls for a form page that will be only contain header information.

Figure 4. Dragging header to form

After we have added a page to the form and named it with a meaningful name such as “header” we drag the entire “header” group to the form page  (Figure 4). Other properties for the page would probably include deselecting the option to include this page when the form is printed. Also, other pages in the form would not include navigation buttons that would expose this page to the form user.  The screen shot also shows that the tool has generated XForm bound controls for each element belonging to the header.

The form developer will provide values in the Initial Content input of each control. This step effectively defines a static value that will be passed to the web service.

Figure 5. Mapping results of drag and drop procedure.

Now, if we examine the Web Services outline  (Figure 5) we will see the mapping of each of the elements to the XForm instances that have been created through our drag and drop procedure.

The other approach to mapping the web service inputs to XForm data is to employ the context menu of the Web Services outline.

Figure 6. Using context menu to map data

By using a right mouse click on a web service element such as xfdlFormSubmitData (Figure 6).

Then, the form developer can browse the XForm containers on the form.

Figure 7. Select XForm data node

Remember that pages are the root container for all of the XForm data bound to controls on a page (Figure 7).

In our example we have created a page named “dataentry”. As we browse the XForm data structure we can select all of the data that a form user may enter by choosing the page itself. Alternatively we could select some subset of the page or even a discrete XForm instance. Again, in our example, we want to capture all of the data and map it to a single web service input.

Remember that in our example we are providing a single page for data entry. If multiple pages are used for data entry the form developer will face a challenge when it comes time to map the data to a single web service input. This is because the choice of containers is constrained to pages or children of pages. Solving this challenge is beyond the scope of this article.

Once the data has been mapped a review of the web service outline will show the mapping (Figure 8).

Figure 8. Result of data mapping procedure.

At this point the form developer has completed the initial integration of the web service with the form. However, in our example the data mapping of multiple XForm instances to a single web service input has a potentially unexpected result. That is, the values of each of the XForm instances will be concatenated as a string when passed to the web service. This means that the structure of the data as represented by the XForm schema is lost.

Why does this happen? The manipulation of XForm data is achieved through the XForms action created when the bindings are made. To see these actions we need to examine an outline of the source code for the form (Figure 9). To view the outline, choose the Source tab of the form editor. This tab is only available when the form developer is using the Advanced IBM Form Designer perspective. Once the Source tab has been selected the form developer will see an outline view of the source Figure 9.

Figure 9. Source outline view

In the outline (Figure 9) two highlights illustrate the XForms action and the selected node being acted upon.  Specifically, the action is setvalue and the node is xfdlFormSubmitData. The wizard generated the data when the form developer mapped the selected node to the body of the web service request.

By examining the screen shot (Figure 9) farther we can see that the same pattern exists for all of the other nodes such as formName, etc.

Now, by examining the implementation of these actions we can see more details (Figure 10).  (Note: This screen shot captures two similar nodes. A complete capture would show more.)

Figure 10. Implementation of xforms action in source code

The xforms:setvalue action includes an attribute, “ref” and a parameter, “value”.  The wizard implements the ref attribute and creates a single node binding the web service element named formName. It may help to regard the ref attribute as the target of the setvalue action. The value parameter to the uses an XPath reference linking to a data element in the XForms model.

To paraphrase the meaning of the second setvalue action stanza seen in Figure 10 we could say, the data found on a page named dataentry will be passed as a single string to an xml node in the web service named formName.

Is there a problem with this? In many cases, perhaps not. In this example there is a problem. The problem is that the string does not reflect the XML structure of the data found on the form page.

How do we solve this problem? We change the xforms action in the second stanza in our Figure 10 example. Instead of using a setvalue action, we will use an insert action.

An insert action has two parameters we need to implement, context and origin. The insert action will copy the xml structure and data “from” the origin to the context. Doing so will preserve the entire XML structure of the data even though it is being passed to a single web service input.

Changing the action type is done as follows:

1. Select the Source tab of the form editor if it has not already been selected.
2. Locate in the source code the stanza needing to be changed.

Searching for the setvalue stanza that contains the name of page containing the data sources can do this. (In the previous example this would be a page named “dataentry”.

1. Make the following edits to the selected stanza:
   1. Change the action from setvalue to insert.
   2. Change the ref attribute to a context attribute.
   3. Change the value parameter to an origin parameter.NOTE: These changes are illustrated in a “before” and “after” example illustrated in Figure 11.

Figure 11 Revised xforms action

In this article I discussed a use case where we want to submit all of our customer’s data to a single web service input. To do this I talked about working with the IBM Form Designer to implement a web service and how to make modifications to the xforms action so that the data is copied as a complete XML structured string and not as an unstructured string.

I welcome your comments, suggestions for improvement, or any indication of whether this post is helpful to you in your work with IBM technologies such as IBM Form Designer v8.0