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
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
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
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:
- 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.
- Create a new Integration Project in Workplace Forms Designer.
- Create or import the form template.
- Create WebSphere Transformation Extender type trees for all the XForms instances.
- Create WebSphere Transformation Extender maps.
- Create the SOA pipelines.
- Configure the forms submission rules to point to the correct pipelines.
- Upload all components to the Workplace Forms Services Platform server.
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.
- 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.
- 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.
- 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.
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
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
The customerlookup pipeline is composed of the following pipes:
- 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.
- 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.
- 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.
- 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.
- 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):
CustomerLookup map: (Top level map)
- Takes in a CustomerInformation instance (containing a CRM number).
- 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.
- 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.
- Builds a SOAP message.
- Invokes the CustomerLookup Web service with the SOAP message that was created by Output Card 1.
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
- Input Cards:
- Takes in a CRM number.
- Takes in the SOAP response that was returned by the CustomerLookup Web service.
- Outputs the completed CustomerInformation instance, containing the CRM number and all the data returned by the CustomerLookup Web service.
- Input Cards:
Figure 7 shows a simplified overview of the execution flow of the CustomerLookup map.
Figure 7. 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("CustomerInformation")" replace="instance"> </xforms:submission>
Figure 8. 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
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.
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.
Thanks to Mike Mansell and Chris Philips of the IBM Workplace Forms team for reviewing this article and providing valuable feedback.
- Refer to Appendix A here.
- Read the developerWorks article, "Extending the XML data model to XFDL forms using IBM Workplace Forms V2.6."
- 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."
- Learn more about IBM WebSphere Transformation Extender.
- Read all the developerWorks resources on SOA and Web services.
Get products and technologies
- Download a trial version of IBM Workplace Forms V2.6 Viewer and Designer.
- Participate in the discussion forum.
- Check out John Boyer's blog, Workplace Forms and the Next Generation Web Applications.
Dig deeper into IBM collaboration and social software on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Keep up with the best and latest technical info to help you tackle your development challenges.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.