Extending the XML data model to XFDL forms using IBM Workplace Forms V2.6

Every year, organizations spend billions of dollars on printing paper forms. To ease this expense, Extensible Forms Description Language (XFDL) has been developed. XFDL is an application of XML that helps move the traditional paper-based forms system to the Internet while maintaining the non-repudiation and auditability features of paper-based forms. XFDL also promotes application interoperability and adherence to Internet standards.

This article discusses the concept of an XML data model for the XFDL form. We use a simple XFDL form, a leave application, as an example to demonstrate the use of the XML data model in separating the form's data layer from the presentation layer. At the end of this article, you learn about the XML data model concept, assess a comparison of XML data model and the XForms model, and follow the steps to create an XML data model.

Introduction to XML data model

XFDL is document-centric: It combines the form's presentation, logic, and data in a single file. In other words, the form’s data is embedded in the XFDL form itself. This document-centric quality makes XFDL a legally binding document. The purpose of XFDL is non-repudiation for legal documents and digitally signed documents. Storing the entire form -- including the logic, data, and presentation -- is therefore necessary. Some applications, though, such as an employee's application form for time off, do not require the entire form for processing or storing. In this case, only the required data such as name, dates, and leave type -- rather than the entire form -- are sent to the processing application.

For that reason, XML data model was introduced. XML data model makes it easier to integrate existing XFDL forms with applications that offer an XML interface. By adding an XML data model to the XFDL form, you can collect required data and place it in a separate block of XML in the form. This is an arbitrary block of XML, which means it can be formatted to match any XML schema. With this, the data of the form is separated from the actual presentation (the user interface). Rather than parsing the entire form to the processing application, you can define which data to collect from the form and which data to send to the processing application.

Figure 1 shows that the data entered on the form is automatically populated on an XML block. When the submission is triggered (usually using a Submit button), the XML is sent over. The receiving application can perform the processing almost immediately as long as the XML follows the defined schema. This significantly reduces your effort in writing custom code to perform the data extraction from the XFDL form. As discussed, this block of XML can be formatted in any manner.

One of the questions you may ask is: because XFDL is based on XML, why do we need to create another block of XML to carry the data? You do so because you will have control of the data. This is true especially for large and complex forms applications. Let's take a look at the example shown in figure 2. If an XML data model is not used, you may end up having all the data embedded in the fields of the form, making the data difficult to extract and maintain.

As shown in the XML snippet on the right, only the required data is collected if we use an XML data model. You collect clean XML with only the required data.

In addition to promoting interoperability, XML data model also simplifies the information exchange between form pages. Using this model, data changes on a page can be automatically reflected on another page. This is done through bindings, which we discuss in more detail in the following section.

Smartfill, which is also based on this model, is a feature available in IBM Workplace Forms. With Smartfill, you can automate the form completion based on saved user data. This significantly reduces the time to complete a form, reduces human errors, and improves the overall user experience.

To create a complete XML data model, you need three elements -- data instances, bindings, and submission rules.

Data instances

Data instances are arbitrary blocks of XML. You can have more than one data instance in an XML data model. If there is more than one data instance, you must define unique IDs for each instance. In listing 1, we have LeaveAppInstance as the instance ID. This instance contains four elements used to store the leave application details: name, leave type, start date, and end date. You can format the instance data however you like, as long as it matches the defined schemas. Listing 1 is an example of the leave application data instance.

<xforms:instance id="LeaveAppInstance" xmlns="http://www.ibm.com/xmlns/prod/XFDL/Custom">
   <leaveApplicationData>
      <name>David</name>
      <LeaveType>Annual</LeaveType>
      <StartDate>8 February 2007</StartDate>
      <EndDate>9 February 2007</EndDate>
      </leaveApplicationData>
</xforms:instance>      

To define additional data instances, add another block of <xforms:instance>. The best practice is to group the data based on its purpose. Take the leave application as an example; you may want to have two data instances -- one to be sent to the application that processes your leave and another to the application that updates your calendar.

Bindings

Bindings describe the relationship between elements and items on a form. As discussed, a binding creates the relationship between elements on the XML data model and fields on a form. Binding is defined using the <bindings> tag. Figure 3 depicts the relationship between the Name text field on the form and the Name element of the data instance.

Figure 4 illustrates the relationship created among Page 1, Page 2, and the leave application data. Changes to Page 1 update Page 2.

>Submission rules

The submissions rules control how and which data instance can be transmitted to the application for processing. The submission rule is not required if you want to submit the entire form to the processing application. Which data instance to be submitted is defined in the submissions properties of the submission rule. The submission rule is typically associated with the Submit button of the form.

There are additional parts of the XML data model, such as the schema for data instance validation and the data fragment that Smartfill uses. We do not discuss the details of the schema and the data fragment in this article.

Back to top

XML data model and XForms model

XML data model was introduced in the prior versions of IBM Workplace Forms. Starting with IBM Workplace Forms V2.6, there are two options for the data model: XML data model and XForms model.

The purpose of XForms model is similar to that of XML data model: to separate the data layer from the presentation layer. Like XML data model, XForms model is used to describe the data. XForms model consists of three core parts, too, that work together to create a complete model: data instances, binds, and submissions.

XForms is a World Wide Web Consortium (W3C) standard, and it will be the next generation of forms. Thus, if you create a new form and want to add a data layer to it, you may consider XForms. Using XForms model is not always an option, though, especially when you have older forms that contain XFDL items. Converting each individual XFDL item to an XForm item is time-consuming, especially for large and complex forms applications. Therefore, this article shows you how to create an XML data model for your existing form.

Back to top

Creating an XML data model for XFDL forms

Before you create an XML data model, you must first have a form. The form can be an existing XFDL form or, if you just want to learn the concept, it could be a new form you create using IBM Workplace Forms Designer. For your convenience, we created a simple leave application form to use in this article. You can download this form from the Download section of this article. Detailed instructions on how to create this form are not discussed here.

Requirements

To follow the steps in the next section of this article, you need to have the following products installed:

• IBM Workplace Forms Designer V2.6
• IBM Workplace Forms Viewer V2.6
• Microsoft Internet Explorer V6.0

The leave application form we use is a typical XFDL form, and it is not XML data model-enabled. The form consists of five fields:

• Name. This is a text field to enter an applicant’s name.
• Leave type. This is a pop-up item where the applicant can choose the type of leave, for example, annual, medical, and marriage leave.
• Start date. This is a date picker combo box to enter the start date of the leave.
• End date. This is a date picker combo box to enter the end date of the leave.
• Submit. This is a button to submit the leave application.

The first four items (Name, Leave Type, Start Date, and End Date) are the data that you want to collect. This is the data that you group under one data instance. The Submit button triggers the submission of this data instance to the processing application. The leave application form is shown in figure 5.

Preparing the environment

To work with the XML data model, you need two views: XMLModel view and XMLModel Instance view. The IBM Workplace Forms default perspective does not display these views. Follow these steps to enable these views:

1. From IBM Workplace Forms Designer, navigate to Window - Show View - XMLModel as shown in figure 6. Repeat this step to enable XMLModel Instance view. TheXMLModel view gives you a preview of your XML data model, which includes the data instance, bindings (fields that you have bound to), and submissions (submission rules and actions). The XMLModel Instance view, on the other hand, gives you an overview of the instances you defined.

2. Verify that both XMLModel and XMLModel Instance are visible.

Creating the XML model

The sample form for the leave application by default is not XML model-enabled, so we add an XML data model to the leave application form. In the XMLModel view, right-click "No XML Model Exists" and choose "Add XML Model" to the form. Once this is done, you see that a model "XML Model Instances (1) instances" is created.

Click the Source view of the form. You then see that an XML data model <xmlmodel> and a default data instance <instances> are added to the form.

<xmlmodel>
   <instances>
      <xforms:instance id="instance1"
      xmlns="http://www.ibm.com/xmlns/prod/XFDL/Custom"></xforms:instance>
   </instances>
</xmlmodel>

NOTE: You may add as many data instance as you like by selecting "Create XML Model Instance" from the XMLModel Instance view. In this article, we use the default data instance (that is, instance1). If you have more than one instance, you must assign a unique ID for each instance.

Next, rename the instance ID to LeaveAppInstance. You can rename it either from the XMLModel Instance view or from the form’s source code. The source code looks like the code shown in listing 3.

<xmlmodel>

   <nstances>

      <xforms:instance id="LeaveInstance" 
      xmlns="http://www.ibm.com/xmlns/prod/XFDL/Custom">

Switch back to the Design view.

Adding an element for the LeaveAppInstance data instance

In the previous section, you learned how to create an XML data model and data instance (the default instance). Each XML data model can contain any number of data instances; the data instance is linked to a button used to trigger the submission of a data instance. Before you proceed to link the data instance to the Submit button, you need to complete some steps first. You must define the list of elements and attributes that you want to include in the data instance -- in this case, the name, leave type, start date, and end date. You do this by adding elements and attributes to the data instance.

1. Create an element called LeaveApplicationData that is used to group the four subelements (Name, Leave Type, Start Date, and End Date). From the XMLModel Instance view, right-click <xforms:instance id=>, and then select Add Element.
2. New element <data1> is created.
3. Right-click <data1>, and then select Rename. Name it LeaveApplicationData.
4. Repeat steps 1 to 3 to create the elements for name, leave type, start date, and end date. These four elements are child elements of LeaveApplicationData. The final result looks like figure 7.

<xmlmodel>
   <instances>
      <xforms:instance id="LeaveAppInstance" 
      xmlns="http:..www.ibm.com/xmlns/prod/XFDL/Custom">
          <LeaveApplicationData>
			<Name></Name>
			<LeaveType></LeaveType>
			<StartDate></StartDate>
			<EndDate></EndDate>
			</LeaveApplicationData>
		</xforms:instance>
	</instances>
</xmlmodel>

5. Save the form.

Binding elements to the form

You have created the data instance and added elements to this instance. Next, bind each data node in the data instance to the XFDL items on the form. This creates a link between the data node and the XFDL item. If the value of one changes, the other bound elements are updated to reflect the changes.

1. In the XMLModel Instance view, click the element Name; drag and drop it to the XFDL item you want to bind -- in this case, the text Name field on the form design canvas.
2. In the XMLModel view, make sure that the bind is successfully created. You should see the binding details as shown in figure 8.

3. Repeat steps 1 and 2 for LeaveType.
4. For the StartDate and EndDate bindings, you may find a problem when you create the bind using drag and drop. This is a known issue and is scheduled to be fixed in the next release of IBM Workplace Forms Designer. For the time being, manually create the bindings. Add the code in listing 5 to the source code of your form in the area below the </bind> tag for the LeaveType element, but before the </bindings> tag.

<bind>
   <instanceid></instanceid>
   <ref>[custom:LeaveApplicationData][custom:StartDate]</ref>
   <boundoption>PAGE1.combo_startDate.value</boundoption>
</bind>
<bind>
   <instanceid></instanceid>
   <ref>[custom:LeaveApplicationData][custom:EndDate]</ref>
   <boundoption>PAGE1.combo_endDate.value</boundoption>
</bind>

5. In the XMLModel view, verify that the bindings for both StartDate and EndDate were created correctly.

You have finished creating the relationship between the items on the form and the data node in the data instance. Changes to the data layer update the presentation layer, just as changes to the presentation layer will update the data layer. You can bind the data node to multiple fields on a form; making the elements share data. This is particularly useful, for example, if the form has multiple pages; you may not want the user to reenter his or her name on every page of the form. By binding the Name data node to the Name items on the form, the data can be synchronized.

Submitting the XML model

Now you have finished creating the model, the instance, and the bindings. Next, you create the submission rule and Submit button to trigger the submission of the data instance to your processing application. This submission rule defines which data instance is submitted and how it is submitted. The submission rule is optional; you need it only if you want to submit just the data instance instead of the entire form.

To create the submission and the submission rule, do the following:

1. In the XMLModel view, right-click XML Model, and then choose Create submissions.
2. Verify that the submission is created.
3. Next, create the submission rule, which defines which data is submitted and how it is submitted. In the XMLModel view, right-click submissions and choose Create submission.
4. Next, set the submission’s properties. Select the submission rule you created in step 3; see figure 9. Then, expand the Miscellaneous property in the Properties view; you see a list of properties that you can configure. The ID is a unique name for the submission rule, and the instanceid is used to specify the instance you would like to submit; see figure 10. By default, the first instance in the form is submitted. If you want to submit other data instances, you must specify the instance IDs.

5. Change the properties' values following the suggestions shown in table 1. The submission rule, named LeaveSubmission, is used to submit the LeaveAppInstance data instance you created earlier. Set the target output to application/xml content type.
   
   For this article, we do not submit to any action. If you want the XML to be submitted to an action, you must specify the action URL here. Includenamespace and ref are optional. If you want to restrict the data instance’s inherited namespaces, add them to the Includenamespace property. The ref property is required only if you want to submit a portion of the data instance.

6. Next, create a Submit button to trigger the submission. The sample form for a leave application that you downloaded includes a Submit button. Next, you need to modify the button's properties. First, select the Submit button.
7. In the Properties view, click the downward-pointing arrow, and then select Show Advanced Properties as shown in figure 11.

8. Under General, set value to Submit and type to submit as shown in figure 12.

9. Next, enter the URL to which the data will be sent in property url.
   
   NOTE: The target URL can be a servlet, cgi scripts, or the application that offers the XML interface. For more information on writing the receiving application, please refer to the IBM Workplace Forms Designer documentation: Using the XML data model.
10. Expand Transmit.
11. Set transmitformat to application/xml;id="SubmissionID" as shown in figure 13.

12. Replace SubmissionID with the name of your submission rule (that is, LeaveSubmission) as shown in figure 14.

13. Save the form.

Congratulations! You have completed the steps to create an XML data model. To submit the form, click the Submit button. The XML data will be sent over to the action URL you specified previously. If you do not have any receiving application, you may do a quick test on the XML output by specifying the URL to an email address, for example mailto:example@my.ibm.com, in the Submission button properties as shown in figure 15.

Save the changes and submit the form. The XML output looks like listing 6.

<LeaveApplicationData>
            xmlns="http://www.ibm.com/xmlns/prod/XFDL/Custom"
            xmlns:custom="http://www.ibm.com/xmlns/prod/XFDL/Custom"
            xmlns:designer="http://www.ibm.com/xmlns/prod/workplace/forms/designer/2.6"
            xmlns:xfdl="http://www.ibm.com/xmlns/prod/XFDL/7.0"
            xmnls:xforms="http://www.w3.org/2003/xforms">
                       
            <Name>David</Name>
            <LeaveType>Annual</LeaveType>
            <StartDate>8 Feb 2007</StartDate>
            <EndDate>9 Feb 2007</EndDate>
 </LeaveApplicationData>

Back to top

Conclusion

The XML data model makes XFDL forms integration with applications that offer an XML interface easier. XML data model creates a block of XML that is used to collect the form's data. Thus, rather than sending the entire form for processing, only the required data is sent. IBM Workplace Forms Designer, now called IBM Lotus Component Designer, provides the set of interface you need to create an XML data model for your XFDL forms, making XFDL forms integration with XML-enabled applications simpler.

Back to top

Download

Information about download methods

Resources

Learn

• Read the developerWorks article, "IBM Workplace Forms V2.6 integration with IBM DB2 V9."
  
  
• Read the developerWorks article, "Integrating IBM Workplace Forms with WebSphere Portal to create a form-centric application."
  
  
• Read the developerWorks article, "Extending the functionality of IBM Workplace Forms with the Function Call Interface."
  
  
• Read the developerWorks article, "Create a form with IBM Workplace Forms Designer."
  
  
• Consult the IBM Workplace Forms V2.6 Info Center.
  
  
• Read the IBM Workplace Forms V2.6 Information Roadmap.
  
  
• Read the IBM Workplace Forms documentation.
  
  

Get products and technologies

• Download a trial version of IBM Workplace Forms V2.6 Viewer and Designer.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Check out John Boyer's blog, Workplace Forms and the Next Generation Web Applications.
  
  

About the author

Comments

Back to top

Trademarks

Table of contents

• Introduction to XML data model
• XML data model and XForms model
• Creating an XML data model for XFDL forms
• Conclusion
• Download
• Resources
• About the author
• Comments