Before you start
Learn what to expect from this tutorial and how to get the most out of it.
About this tutorial
This tutorial covers the development and runtime of an example application that integrates IBM Lotus Forms with SAP using the Lotus Forms Services Platform.
In this tutorial, you learn how to integrate Lotus Forms with SAP using the Lotus Forms Services Platform (formerly called IBM Workplace Forms Services Platform).
This tutorial is written for architects and developers who already have a basic to intermediate knowledge of Lotus Forms, IBM WebSphere Transformation Extender, and SAP.
The following software is required to develop and execute the sample application in this tutorial:
- IBM WebSphere Application Server
- IBM Lotus Forms Server V3.0 (includes Services Platform)
- IBM Lotus Forms API V3.0
- IBM Lotus Forms Designer V3.0
- IBM Lotus Forms Viewer V3.0
- IBM WebSphere Transformation Extender V8.1 (Build 114 or later)
- SAP RFC client library 6.40
- SAP Extender Pack for WebSphere Transformation Extender V8.1
Editor's note: On September 28, 2007, IBM Workplace Forms will be renamed IBM Lotus Forms and the V3.0 release will be available. If you are reading this tutorial before September 28, note that all instances of IBM Lotus Forms refer to the renamed product.
IBM Lotus Forms software is an electronic forms solution that enables you to quickly build powerful portal applications, so you can easily render electronic versions of paper forms and simplify complex forms more quickly than with traditional software. For users, it provides instant access to forms and the information they contain. For organizations, it helps to streamline and reduce inefficiencies in processes. In the end, everyone benefits: simplified process management, faster application development, improved data integrity, and easier-to-use forms.
Lotus Forms software delivers a forms development environment that allows you to eaily integrate forms with SAP without having to write a lot of code. Writing less code means projects can be completed more quickly, which can lead to lower maintenance and growth costs, while helping succeeding projects come to market more quickly.
When used as a frontend to SAP business applications and processes, Lotus Forms enables you to leverage some distinctive benefits:
- Design role-based, intuitive user interfaces to access SAP data and processes.
- User interface adapts to the needs of specific users
- Build wizards, pre-populated fields, and help and data completion functions right into your forms.
- Reduced training efforts when exposing SAP Self Service Processes
- Work with validated, high-quality data on the server side only
- Streamline data collection and exchange between SAP and non-SAP Systems.
- Forms data can be mapped to any kind of system (not just SAP)
- Take your SAP processes and business logic offline.
- Use digital signatures to create business documents with SAP data.
- Flexible application of multiple, overlapping XML signatures
- Enable regulatory and legislative compliance through implementing security-rich, auditable e-record transactions based on an open-standards foundation.
This tutorial covers the development and runtime of an example application that integrates Lotus Forms with SAP using the Lotus Forms Services Platform. For an in-depth discussion on the Services Platform and how it works, read the developerWorks article, "Integrating forms into SOAs using the IBM Services Platform." It is expected that readers are familiar with the Services Platform before continuing with this tutorial.
The application we build in this tutorial is an example of an SAP HR self-service implementation. Based on his or her personnel number, an employee can retrieve his or her master data record from SAP and apply changes to the address and banking information. The employee can then apply his or her signature to the changes and submit the form back to the server, where the form is stored as a record and the xml data is extracted and submitted against the respective BAPIs on the SAP backend by the Lotus Forms Services Platform. Figure 1 describes the flow of action in the sample application.
Figure 1. Flow of action in the sample application
From a more technical perspective, the Lotus Forms Services Platform uses the SAP Adapters of WebSphere Transformation Extender to connect to the SAP backend and to call the respective SAP BAPIs necessary to fetch or write the data. To accomplish this, the Forms Services Platform project executes one or more WebSphere Transformation Extender maps either to prepopulate data from the SAP backend into the Lotus Form or to update the SAP backend with data from the form. See figure 2.
Figure 2. Architecture of the forms and SAP integration using the Services Platform
Required software and environment setup
The following software is required to develop and execute the sample application:
- WebSphere Application Server
- IBM Lotus Forms Server V3.0 (includes Services Platform)
- IBM Lotus Forms API V3.0
- IBM Lotus Forms Designer V3.0
- IBM Lotus Forms Viewer V3.0
- WebSphere Transformation Extender (TX) V8.1 (build 114 or later)
- SAP RFC client library V6.40
- SAP extender pack for WebSphere Transformation Extender V8.1
Set up the Lotus Forms Services Platform according to the documentation shipped with the product. The following additional steps are required to execute the example forms/SAP integration application:
- The SAP RFC client library V6.40 or later is required by the SAP Extender Pack for WebSphere Transformation Extender. If the SAP Front End has been installed on a Windows system, this library should already be installed in Windows\system32. If the SAP Front End is not installed, see your SAP Administrator to obtain this library from SAP.
- Ensure that it is version 8.1, build 114 or later of WebSphere Transformation Extender that is installed. Bugs in earlier builds of WebSphere Transformation Extender V8.1 occur when you generate Type Trees from SAP BAPIs.
- Install the SAP Extender Pack for WebSphere Transformation Extender.
- Add the new JAR files that are installed by the SAP Extender Pack for WebSphere Transformation Extender (for example, m4r3bapi.jar) to the class path in the file startDebugServer.bat on Windows (startDebugServer.sh on Linux). (NOTE: When you start the server make sure that the port number is set to 2500. The Services Platform by default tries to connect to the Transformation Extender RMI server on this port.)
SAP extender pack
The SAP extender pack is purchased as an add-on to WebSphere Transformation Extender 8.1. The pack supports the following versions of SAP:
- SAP R/3 4.6 and 4.7
- mySAP 2004 (ECC 5.0) and mySAP 2005 (ECC 6.0)
The pack supports integration with an SAP system using any of the following methods:
- Intermediate Documents
- Application Link Enabling (ALE)
- ALE Message Handler (AMS)
- Electronic Data Interchange (EDI)
- DXOB/Data Migration Interface (DMI)
- Business Application Programming Interface (BAPI)
- Batch Data Communication (BDC)
This tutorial focuses on integration with SAP using BAPIs.
Development of the sample application
The completed Lotus Forms Services Platform project is available in the Downloads section of this tutorial. When unzipped, the directory formsSAPIntegrationDemo can be placed directly into the directory c:\fsp-SDKProjectRepo\ as shown in figure 3. A user can then download the completed project to Lotus Forms Designer as shown in figures 4 and 5.
Figure 3. Place the unzipped directory in c:\fsp-SDKProjectRepo
Figure 4. Download the project to Lotus Forms Designer
Figure 5. The formsSAPIntegerationDemo project downloaded to Lotus Forms Designer
The completed pipelines (.properties files) and pipes (JAR files) are in the attached file extensions.zip and should be placed in the directory "Lotus Forms Installation Dir"\Server\3.0\Services Platform\extensions\.
Figure 6. Add the pipelines and pipes to the extensions directory
In the GetForm and SubmitForm .properties files, users need to configure the connection details for their SAP system; this is explained later in Listing 2.
The following steps are required to develop the application:
- Create the Transformation Extender Types Trees from the SAP BAPIs that are called.
- Create a new Integration Project in Lotus Forms Designer.
- Create or import the form template.
- Create WebSphere Transformation Extender type trees for all the XForms instances.
- Create WebSphere Transformation Extender maps.
- Configure the forms submission rules to point to the pipelines to be created.
- Upload all components to the Lotus Forms Services Platform server.
- Create the pipelines and required pipes.
Most of these steps are straightforward and are not explained in any more detail in this tutorial. Refer to the developerWorks article, "Integrating forms into SOAs using the IBM Services Platform" for more details.
Creating the Transformation Extender types for the SAP BAPIs that are called
The sample application uses the following BAPIs:
For in-depth information on how to create Type Trees from SAP BAPIs, refer to the documentation that comes with the Transformation Extender SAP Extender Pack. The following presents a summary of the process of creating a Transformation Extender Type Tree for the BAPI BAPI_ADDRESSEMP_CHANGE:
After selecting "Import a type tree," select SAP:BAPI as shown in figure 7.
Figure 7. Specify that the Type Tree is to be generated from an SAP BAPI
Enter the name of the required BAPI, or click the button and select it from the list as shown in figure 8.
Figure 8. Enter the name of the BAPI from which the Type Tree should be generated
When the generated Type Tree is opened in the designer, analyze the Type Tree as shown in figure 9. Click Save, and close the Type Tree Designer window.
Figure 9. Check the logic and structure of the generated Type Tree
Figure 10 shows the results of analyzing the Type Tree.
Figure 10. The results of checking the logic and structure of the generated Type Tree
Repeat this process for all the required BAPIs.
Create WebSphere Transformation Extender maps
In the component navigator, open the formsSAPIntegration.mms file in the WebSphere Transformation Extender Map designer. This file, shown in figure 11, contains all the Transformation Extender maps that are required by the sample application.
Figure 11. The formsSAPIntegration.mms file opened in the WebSphere Transformation Extender Map Designer window
Transformation Extender Maps required to fetch employee data from SAP
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 GetEmployeeData pipeline (see figure 12), a number of WebSphere Transformation Extender maps are required. Figure 13 shows a simplified overview of the execution flow of the Transformation Extender Maps executed to populate the employee instance with data from SAP; for example, input variables such as host, username, and password (for accessing SAP) are not shown.
Figure 12. Functionality required from WebSphere Transformation Extender, when executing the GetEmployeeData pipeline
Figure 13. Execution flow when populating the employee instance with data from SAP
The execution flow works by initially taking in an employee instance that contains just an employee number, and then a number of Transformation Extender Maps are executed that fetch (and format) the specified employee's data from SAP. Finally, a completed employee instance is output that can be returned to the form.
Transformation Extender Maps required to submit changes to an employee's address or bank details to SAP
Figure 14 shows a simplified overview of the execution flow of the Transformation Extender Maps executed to submit changes to an employee's address and/or bank details to SAP (again, input variables such as host, username, and password are not shown). The execution flow works as follows: When a form is submitted, the completed employee instance is extracted, and the new data is submitted to SAP by executing a number of Transformation Extender Maps. At the end, a result message is output to inform the user whether the submissions to SAP were successful or not.
Figure 14. Execution flow when submitting data from an employee instance to an SAP system
Configure the forms submission rules to point to the correct pipelines
The buttons on the form need to be configured to point to the pipelines that are loaded by the Services Platform. Listing 1 shows the xforms submission rule that links the Load Employee button to the getemployeedata pipeline.
Listing 1 Create an xforms submission rule to link the Load Employee button to the getemployeedata pipeline
<xforms:submission action=http://localhost:9080/wfsp/wfi/getemployeedata" id="loademployee" method="post" ref="instance("INSTANCE1")" replace="instance"> </xforms:submission>
All URLs in the form have been set to localhost, so you can run the example only on the same machine on which the Services Platform is running. If you want to run it on a different machine, you need to modify the URL for the loademployee submission rule and the submit form URL with the correct IP address for the machine that is running the Services Platform.
Create the pipelines
The sample application requires three pipelines:
Two custom pipes had to be developed for these pipelines:
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 Lotus Forms Services Platform, but you can also develop your own custom pipes as OSGI bundles using the provided API, for example, the LoadInstance and LoadVariables pipes used in this tutorial. These OSGI bundles can then be deployed to the Lotus Forms Services Platform server by adding them to the extensions directory. To see the code for these pipelines refer to the .properties files in the extensions.zip file in the Downloads section of this tutorial.
Pipelines are written in properties files and can be loaded at runtime by the Lotus Forms Services Platform by placing the properties file in the extensions directory. When this pipeline is executed it fetches the form from the repository and returns it to the requesting browser as shown in figure 15. This pipeline does not communicate with the SAP system.
Figure 15. The GetForm pipeline
Figure 16 shows the complete GetEmployeeData pipeline. This pipeline requires the creation of two new pipes called LoadInstance and LoadVariables.
- The LoadInstance pipe reads in a String object from the request object that is passed to the Head pipe.
- The LoadVariables pipe allows variables to be specified once and loaded into the pipeline. This avoids having to specify the same hard-coded
string variables multiple times in the same properties file. This pipe is used to load the variables host, username, and password that are
used to connect to a SAP system. If a user wants to connect to a different SAP system, he or she needs to change these variables in the properties
file. A user should configure these variables with the correct values for the SAP system before loading the pipeline into the Services
Listing 2. Variables that need to be configured so the pipeline can connect to the SAP system
ibm.forms_sap_integration.LoadVariablesPipe.GetEmployeeData.ipAddressVar = string:<add IP address of SAP system, include router string> ibm.forms_sap_integration.LoadVariablesPipe.GetEmployeeData.usernameVar = string:<sap username> ibm.forms_sap_integration.LoadVariablesPipe.GetEmployeeData.passwordVar = string:<sap password>
This GetEmployeeData pipeline executes the Transformation Extender Maps described in figure 13. The submitted employee instance contains an employee number that is used to fetch an employee's data from SAP. The final Transformation Extender Map outputs a completed employee instance that can be written directly into the form, when returned.
Figure 16. The GetEmployeeData pipeline
When this pipeline is launched it loads the submitted form. It extracts the employee instance from the form, and it then uses the instance to execute the Transformation Extender Maps described in figure 14, updating an employee's address and bank details in SAP. It stores a copy of the submitted form to the repository as a record. It finally informs the user on whether or not the submission to SAP was successful as shown in figure 17.
Figure 17. The SubmitForm pipeline
As with the GetEmployeeData pipeline, a user needs to configure the host, username, and password variables in the SubmitForm properties file with the correct values for his or her SAP system before loading the pipeline into the Services Platform.
Runtime of the sample application
How users access published forms can vary immensely depending on the setup of their Lotus Forms Services Platform; for example, forms might be accessed through a portlet or rendered directly in a browser (using the Forms Viewer). When the project is published to the server, users are able to request the published form, and then they can complete and submit the form, causing a number of pipelines on the server to be executed during the process. In this tutorial, a user requests the form by typing a specific URL in a browser that invokes a GetForm pipeline that displays the form in the browser.
The runtime of the application can be broken into the following steps:
- Request the form.
- Enter the employee number.
- Make changes and submit the form.
- Check that the submitted form was stored on the server (optional).
- Check the SAP system to verify that the changes have been committed (optional).
Request the form
Type the URL http://<host>:<port>/wfsp/wfsp/getform into a browser. The form is then displayed as shown in figure 18.
Figure 18. The form is rendered in a browser
Enter the employee number
Type in an employee number, and click the Load Employee button. In this tutorial, the employee number 10199218 is used as shown in figure 19.
Figure 19. Type in an employee number and click the Load Employee button
If the specified employee exists, the form is populated with the employee's data as shown in figure 20.
Figure 20. The form is populated with the employee's information
Make changes and submit the form
Make changes to the form, and then click Submit. (Remember to sign the form before you click the Submit button.) For example, in figure 21, the employee's address, telephone number, account number, and pay purpose are modified.
Figure 21. Make modifications to the employee's data and click Submit Form
The form is submitted to Services Platform; when the SubmitForm pipeline is executed, the employee data is extracted from the form and the SAP system is updated. The result of the operation is returned and displayed in the browser window as shown in figure 22.
Figure 22. The result returned from the SubmitForm pipeline
If a user enters incorrect data (for example, an invalid account number) as shown in figure 23, the execution of the BAPI fails during the execution of the SubmitForm pipeline, and the problem is reported to the user as shown in figure 24.
NOTE: This example illustrates how the Services Platform handles errors in the inputted data if it encounters them, but if the validation rules in the form are written correctly this never happens. The validation rules in Lotus Forms can validate all data when inputted by the user, so once a form is developed with the correct validation rules, only valid data gets sent to the backend system. In the case of SAP, this gives a powerful mechanism for the end user because the data submitted against a BAPI usually is subject to a rigid schema.
Figure 23. Enter an invalid account number and submit the form
Figure 24. An error is reported after trying to submit an invalid account number to SAP
Check that the submitted form was stored on the server (optional)
When the submitform pipeline is executed, the submitted form is stored in the directory c:\fsp-SDKProjectRepo\formsSAPIntegrationDemo\submittedforms\ as shown in figure 25.
Figure 25. The submitted form was saved to the repository
Check the SAP system to verify the changes have been committed (optional)
Use the SAP frontend as shown in figure 26 to verify that SAP has been updated with the changes that were submitted in figure 21.
Figure 26. Use the SAP frontend to verify the changes were committed to SAP
In this tutorial, you learned how to build a Lotus Forms and SAP integration in an easy-to-use, intuitive visual environment. Lotus Forms Designer and WebSphere Transformation Extender, which is part of Lotus Forms Services Platform, allow you to create this project without writing a lot of code. Finally, you also learned how to deploy and run your project on Lotus Forms Services Platform. You are now able to use the advanced features of Lotus Forms Services Platform to call any BAPI in SAP to create a highly dynamic, interactive forms application that consumes and provisions data to an SAP backend.
- Read the developerWorks article, "Integrating IBM Workplace Forms V2.7 with IBM WebSphere Portal V6.0 Document Manager."
- Read the developerWorks article, "Extending the functionality of IBM Workplace Forms with Web services."
- Read the developerWorks article, "Extending the XML data model to XFDL forms using IBM Workplace Forms V2.6."
- Read the developerWorks article, "Integrating XML forms-based processes into Service Oriented Architectures using IBM Workplace Forms Services Platform."
- 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."
- Read the developerWorks Workplace Forms product documentation page.
- Refer to the IBM Workplace Forms support site.
- Read the developerWorks Workplace Forms page.
Get products and technologies
- Download the IBM Lotus Forms V3.0 trial.