Integrating XML forms-based processes into Service-Oriented Architectures using IBM Workplace Forms Services Platform

This article outlines how to integrate XML form-based processes into Service-Oriented Architectures (SOA), using the new IBM Workplace Forms Services Platform, which was released as a component of IBM Workplace Forms Server V2.7.

Padraig O'Dowd (odowdp@ie.ibm.com), Associate IT Architect, IBM

Dr. Padraig O'Dowd is an Associate IT Architect based in IBM's Dublin Software Lab. He is currently working on a number of SOA growth projects. He has a Ph.D. in Distributed and Grid Computing from University College Cork, Ireland.



Con O'Leary (olearyc@ie.ibm.com), Solution Architect, IBM

Con O'Leary is a Solution Architect with a proven track record in guiding project teams to achieve the successful implementation of many different technologies and computer software applications in numerous client environments across a multitude of industrial and consumer businesses.



03 April 2007

IBM Workplace Forms is an XML-based technology used to gather data from a user much as paper forms are used to gather data. Both the presentation layer and complicated business logic of the form can be embedded in a Workplace Forms document. You use the data gathered by a form to start a business process. It is vital that Workplace Forms can be easily integrated into Service-Oriented Architectures (SOAs). For example, when you use the Business Process Execution Language (BPEL), tasks in a business process are created as Web services. Integrating Workplace Forms into these business processes requires mapping between the data models in the forms and Web services (that is, XForms instances to WSDL and WSDL to XForms instances).

The new IBM Workplace Forms Services Platform and its use of an embedded IBM WebSphere Transformation Extender runtime provide functionality that easily allows e-forms to be integrated into SOAs. For example, previously when you used SOA (Web) services in an IBM Workplace Forms application, you had to manually write code to format the Web service response appropriately for the form. As this article shows, using the Workplace Forms Services Platform, you can now quickly create a WebSphere Transformation Extender map that transforms the Web service response into an appropriate format, and then you can use the Workplace Forms API to write the outputted instance directly into a form. This approach considerably reduces the time needed to develop a Workplace Forms application. Another big advantage of the Workplace Forms Services Platform is that it cuts down considerably on the knowledge required to build Workplace Forms applications, allowing users without extensive technical knowledge to develop and deploy Workplace Forms applications.

IBM Workplace Forms Services Platform

This section presents a high level overview of the main features of the Workplace Forms Services Platform; for in-depth details on installation and configuration, refer to the help documentation that ships with the product. The Workplace Forms Services Platform is a new addition to the Workplace Forms family that allows developers to quickly integrate Workplace Forms into back-end systems. Though in this article the main focus is on SOA (Web) services, the Workplace Forms Services Platform allows easy integration with any technology that is supported by WebSphere Transformation Extender.

WebSphere Transformation Extender is a data transformation tool that allows data to be easily mapped from one system to another. WebSphere Transformation Extender currently supports more than 40 technologies, including Web services, databases, SAP, and more. A WebSphere Transformation Extender embedded runtime is available that can be integrated directly into applications that want to use its data transformation capabilities. The product also includes a number of designer tools for creating Transformation Extender maps.

The Workplace Forms Services Platform consists of two main components as shown in figure 1:

  • A Web application that is installed on IBM WebSphere Application Server
  • A number of Eclipse plug-ins that are added to IBM Workplace Forms Designer
Figure 1. Main components of IBM Workplace Forms Services Platform
Main components of Workplace Forms Services Platform

IBM Workplace Forms Services Platform Web application

Workplace Forms Services Platform is built on top of Open Services Gateway Initiative (OSGI); this lets you easily create your own custom OSGI bundles (plug-ins) that can be integrated into the server. See figure 2. Users can create their own OSGI services using the provided APIs. These OSGI bundles can then be deployed to the Workplace Forms Services Platform server by placing them in the following directory on the server:

<Services Platform installation dir>\extentsions

Figure 2. Workplace Forms Services Platform architecture
Workplace Forms Services Platform Architecture

Users can create their own OSGI bundles (plug-ins) to connect different repositories to the Workplace Forms Services Platform -- for example, Content Manager and FileNet among others. The example application described in this article uses a simple file-system repository that is shipped with Workplace Forms Services Platform.

You can think of Workplace Forms Services Platform as a base framework, one that users can extend by creating their own pipelines (Properties files) and OSGI bundles and integrating them into Workplace Forms Services Platform at runtime.

When you want to create a new Workplace Forms integration application, you create a number of pipelines, which can then be deployed to the Workplace Forms Services Platform server; see figure 2. These executable pipelines form the heart of Workplace Forms Services Platform. A pipeline consists of a number of pipes that are executed in sequential order. The Workplace Forms Services Platform comes with a library of existing reusable pipes, but you are free to create custom pipes as well. When Workplace Forms Services Platform's front-end Web Dispatcher receives requests, it passes them to the corresponding pipeline by invoking the pipeline's Head pipe.

The Services Platform is used at both design and runtime. You can upload, download, and publish projects (which are Workplace Forms applications) to the server. When users are completing forms, requests are sent to the server's Web Dispatcher, which then invokes the correct pipeline.

IBM Workplace Forms Designer plug-ins

A number of Eclipse plug-ins were created for IBM Workplace Forms Designer to allow you to do the following:

  • Download, upload, and publish integration projects to a Workplace Forms Services Platform server.
  • Create WebSphere Transformation Extender type trees from the data models contained in a form and create Transformation Extender maps using the automatically generated type trees.

Component Navigator plug-in

The Component Navigator is an Eclipse view with the following features:

  • It shows the data models (for example, XForms instances) of a form in a tree viewer.
  • It allows you to create WebSphere Transformation Extender maps that map the data models to back-end systems.

Using the Component Navigator, shown in figure 3, users can view the data models of a form, generate Transformation Extender type trees from these data models, and launch the Transformation Extender Map Designer to create Transformation Extender maps. All these data models and generated Transformation Extender artifacts are available to browse through the Component Navigator's tree viewer.

Figure 3. Component Navigator
Component Navigator

Integrating e-forms into SOAs

This section discusses how IBM Workplace Forms technology can be easily integrated into SOAs using the Workplace Forms Services Platform. The development of a Workplace Forms integration application can be broken down into the following steps:

Application Design Time

The development and deployment of the Workplace Forms integration project:

  1. The SOA (Web) services should be up and running. WebSphere Transformation Extender type trees for these services should be created using the WebSphere Transformation Extender WSDL Importer.
  2. Create a new Integration Project in Workplace Forms Designer.
  3. Create or import the form template.
  4. Create WebSphere Transformation Extender type trees for all the XForms instances.
  5. Create WebSphere Transformation Extender maps.
  6. Create the SOA pipelines.
  7. Configure the forms submission rules to point to the correct pipelines.
  8. Upload all components to the Workplace Forms Services Platform server.

Application Runtime

How users access published forms can vary immensely depending on the setup of their Workplace Forms Services Platforms; for example, forms might be accessed though a portlet or through a simple HTML page. When the project is published to the server, users are able to request the published form, and then complete and submit the form, causing a number of pipelines on the server to be executed during the process. The execution flow of an example Workplace Forms integration application might work as shown in figure 4.

  1. A user types a URL into a browser, which invokes a GetForm pipeline on the Workplace Forms Services Platform server. During the execution of the pipeline the required form template is fetched from a repository and populated with data from a database. The pipeline finishes by returning the form to the user, and the form is displayed in the user's browser.
  2. Any buttons in the form can be configured to point to appropriate pipelines on the server. In the example SOA pipeline that follows, a customer Look Up button is connected to a customerlookup pipeline.
  3. The submission button in a form may point to a pipeline that accepts the entire form as input, then extracts any required information from the form, invokes some business process with the data, and finally stores the entire form to a database (or repository) as a record.

Refer to Figure 4 here.

SOA pipeline

As mentioned, a pipeline consists of a number of pipes that are executed in sequential order. A pipe can be thought of as a single unit of work. A number of standard pipes are shipped with Workplace Forms Services Platform, but you can also develop your own custom pipes as OSGI bundles using the provided API. These OSGI bundles can then be deployed to the Workplace Forms Services Platform server by adding them to the extensions directory.

We now describe an SOA pipeline called customerlookup. This pipeline forms part of a Workplace Forms invoicing application and shows what's involved in integrating an e-form with an SOA service. A purchase order form contains an XForms instance CustomerInformation, and a pipeline needs to be created that allows users to enter their CRM number and click a button, which then submits the entered customer number to the server and causes the customerlookup pipeline to be launched.

Figure 5 shows what is needed from WebSphere Transformation Extender: Get the CRM number from a CustomerInformation instance, invoke a customerLookup Web service with the CRM number, and format the SOAP response into the correct XML type for the form -- that is, a completed CustomerInformation instance.

Figure 5. Functionality required from WebSphere Transformation Extender, when executing the customerlookup pipeline
Functionality required from Transformation Extender

Figure 6 shows the complete customerlookup pipeline. Appendix A shows the code that creates this pipeline. Pipelines are written in Properties files and can be loaded at runtime by the Workplace Forms Services Platform by placing the Properties file in the extensions directory. This pipeline required the creation of one new pipe called LoadInstance. This pipe reads in a string object from the request object that is passed to the Head pipe. A new OSGI bundle was created containing this pipe and added to the Workplace Forms Services Platform's extensions directory. For details on the language used to describe the pipeline in the Properties file, readers are referred to the product documentation. (It is also possible to place the Properties file in the OSGI bundle instead of deploying it separately.)

Figure 6. Customerlookup pipeline
Customerlookup pipeline

The customerlookup pipeline is composed of the following pipes:

  1. Head pipe

    Specifies which pipe to execute when the pipeline is launched; in this case, it is the LoadInstance pipe. URLs for pipelines have the following format:

    http://<hostname>:<port number>/wsfp/wfi/<name of pipeline>

    When the front-end Web Dispatcher receives a request, it launches the pipeline with the name of the pipeline and passes it the request object. The buttons in a form can be configured to point at a pipeline, using the appropriate URL.

  2. LoadInstance pipe

    When the user clicks the Look Up button on the form (see figure 9), the CustomerInformation instance containing the CRM number is sent to the Web Dispatcher on the server, the customerlookup pipeline is launched and passed the request object from the Web Dispatcher, and this pipe then reads the CustomerInformation instance into memory from the request object.

  3. RepoLoad pipe

    This pipe loads a WebSphere Transformation Extender map (CustomerlookupMap.mmc) into the pipeline's memory from a repository. The WebSphere Transformation Extender map CustomerlookupMap was created in Workplace Forms Designer to take in a CRM number, to invoke the CustomerLookup Web service, and to output a completed CustomerInformation instance. The second RepoLoad pipe instance loads the ParseResponseCL map into the pipeline's memory.

  4. Map pipe

    The map pipe is the pipe of most interest in this article. This pipe invokes the WebSphere Transformation Extender (OSGI) service with the CustomerLookup map and the CRM number as parameters. The CustomerLookup WebSphere Transformation Extender map is covered in more detail later, but for now just know that when the map finishes executing, it outputs a completed CustomerInformation instance containing the data that was returned from a CustomerLookup Web service.

    Listing 1. Map pipe from the customerlookup.pipeline.properties file; see Appendix A for the complete pipeline
    # Run Instance through WebSphere Transformation Extender   
    	1  ibm.MapPipe.customerlookup.map = service:mapping.impl.tx
    	2  ibm.MapPipe.customerlookup.mapinputdata.Transformation ExtenderMap = 
    	string:customerLookupMap.mmc
    	3  ibm.MapPipe.customerlookup.mapinputdata.File1.data = key:txmap
    	4  ibm.MapPipe.customerlookup.mapinputdata.File1.name = string:customerLookupMap.mmc
    	5  ibm.MapPipe.customerlookup.mapinputdata.File2.data = key:txmap2
    	6  ibm.MapPipe.customerlookup.mapinputdata.File2.name = string:ParseResponseCL.mmc
    	7  ibm.MapPipe.customerlookup.mapinputdata.InputCard1.data =  key:incominginstance
    	8  ibm.MapPipe.customerlookup.mapinputdata.InputCard2.data = string:localhost
    	9  ibm.MapPipe.customerlookup.mapoutputdata.OutputCard3.data = key:outputinstance
    	10 ibm.MapPipe.customerlookup.pidOutputs.main = 
    	pipe:ibm.PreserveMapPipe.customerlookup
    • Line 1 specifies that this instance of the map pipe should use the WebSphere Transformation Extender mapper service.
    • Lines 2, 3, and 4 specify the top-level Transformation Extender map (MMC file) that is to be executed. This map was loaded into memory from the repository by the previous pipe ibm.RepoLoadPipe.customerlookup and stored using the key txmap.
    • Lines 5 and 6 specify another WebSphere Transformation Extender map (ParseResponseCL.mmc) that is executed by the top-level map.
    • Line 7 specifies the input to InputCard 1 of the WebSphere Transformation Extender map; in this case, it is the CustomerInformation instance (containing the CRM number) that was submitted when the Lookup button on the form was clicked.
    • Line 8 specifies the input to InputCard 2 of the WebSphere Transformation Extender map, the host name of the machine that is running the CustomerLookup Web service. In this solution, it is presumed the Web service is running on the localhost.
    • Line 9 specifies that the output that is required from the WebSphere Transformation Extender map will be on its third Output Card and the output value is to be stored using the key outputinstance. Other pipes in the pipeline can then access this outputted data (completed CustomerInformation instance) using the key outputinstance.
    • Line 10 specifies the next pipe that should be executed when this pipe completes.
  5. ReturnData pipe

    Returns the completed instance to the form; see figure 9.

Creating WebSphere Transformation Extender maps that invoke Web services

In WebSphere Transformation Extender, input data to a map is placed on an Input Card, and the result from a transformation is placed on an Output Card. To implement the required functionality in WebSphere Transformation Extender for the CustomerLookup use case, two WebSphere Transformation Extender maps are required (see figure 7):

  1. CustomerLookup map: (Top level map)
    • Input Cards:
      1. Takes in a CustomerInformation instance (containing a CRM number).
      2. Takes in the directory location of any required maps -- for example, ParseResponseCL.mmc (see point 2 below). This example uses the file-system repository, and the required maps can be read from disk.
      3. Takes in the IP address of the machine where the CustomerLookup Web service is running. The idea is that if the Web service is moved, there is no need to recompile the map.
    • Output Cards:
      1. Builds a SOAP message.
      2. Invokes the CustomerLookup Web service with the SOAP message that was created by Output Card 1.
      3. Executes the ParseResponseCL map and passes the following to it as input:
        • The SOAP response that was returned from the Web service
        • The CRM number
    When the ParseResponseCL map completes, its output data is outputted on Output Card 3 of the CustomerLookup map. The second map (ParseResponseCL) is necessary because the Web service response needs to be formatted into the correct XML type (CustomerInformation instance) that can be written directly back into the form, using the Workplace Forms API.
  2. ParseResponseCL map
    • Input Cards:
      1. Takes in a CRM number.
      2. Takes in the SOAP response that was returned by the CustomerLookup Web service.
    • Output Cards:
      1. Outputs the completed CustomerInformation instance, containing the CRM number and all the data returned by the CustomerLookup Web service.

Figure 7 shows a simplified overview of the execution flow of the CustomerLookup map.

Figure 7. Execution flow of the CustomerLookup map
Execution flow of the CustomerLookup map

Executing the pipeline at runtime

The Look Up button in figure 8 is connected to the customerlookup pipeline using an XForms submission rule that submits the CustomerInformation instance (containing the CRM number):

Listing 2. XForms submission rule to connect to the customerlookup pipeline
        <xforms:submission   
	action=http://localhost:9081/wfsp/wfi/customerlookup id="LookUp" 
	method="post" ref="instance(&quot;CustomerInformation&quot;)" 
	replace="instance">
	</xforms:submission>
Figure 8. User enters CRM number and clicks the LookUp button
User enters CRM number and clicks the LookUp button

A user enters a CRM number and clicks the Look Up button. When the Web Dispatcher receives the request, the customerlookup pipeline is launched. When the pipeline finishes, the completed CustomerInformation instance is returned and displayed in the form; see figure 9.

Figure 9. Response returned from the server is displayed in the form
Response returned from the server is displayed in the form

Creating any WebSphere Transformation Extender map for the Workplace Forms Services Platform that invokes an SOA service follows a similar outline to the CustomerLookup example.


Conclusion

IBM Workplace Forms Services Platform provides an easy environment to develop complete IBM Workplace Forms applications. From within IBM Workplace Forms Designer, developers can create forms, and Websphere Transformation Extender maps for connecting these forms to back-end systems, and then publish all these artifacts to the Workplace Forms Services Platform server. When published, the new application is automatically accessible by users. If updates to the application are required later, you can download the application from the server, make the required updates, and redeploy the application to the server. This system breaks away from traditional deployment models, where less technical staff can now deploy applications in a runtime environment without needing in-depth knowledge of this environment. This new platform cuts down considerably on the knowledge and time required to build a complete IBM Workplace Forms integration application.

Acknowledgments

Thanks to Mike Mansell and Chris Philips of the IBM Workplace Forms team for reviewing this article and providing valuable feedback.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks


  • developerWorks Labs

    Experiment with new directions in software development.

  • developerWorks newsletters

    Read and subscribe for the best and latest technical info to help you deal with your development challenges.

  • JazzHub

    Software development in the cloud. Register today and get free private projects through 2014.

  • IBM evaluation software

    Evaluate IBM software and solutions, and transform challenges into opportunities.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus, WebSphere
ArticleID=206416
ArticleTitle=Integrating XML forms-based processes into Service-Oriented Architectures using IBM Workplace Forms Services Platform
publish-date=04032007