Integrating IBM Lotus Forms with SAP using the Lotus Forms Services Platform

This tutorial outlines how to integrate IBM Lotus Forms with SAP, using Lotus Forms Services Platform, released as a component of IBM Workplace Forms V2.7. Using an embedded IBM WebSphere Transformation Extender runtime allows the easy mapping of data between Lotus Forms and SAP.

Share:

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.



Bernd Beilke (BEILKE@de.ibm.com), IT Specialist, IBM

Bernd Beilke is an accredited IT Specialist based in Berlin, Germany. He is currently working on the Techworks Team as a Presales Specialist to support IBM Lotus Forms engagements in Northeast Europe. He has 10 years of experience with various IBM Lotus products working in different areas of IBM. His areas of expertise include Lotus Forms, Portal, and Collaboration products.



25 September 2007

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.

Objectives

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).

Prerequisites

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.

System requirements

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

Tutorial

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.

Sample application

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
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
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.)

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
Place the unzipped directory in c:\wfsp-SDKProjectRepo
Figure 4. Download the project to Lotus Forms Designer
Download the project to the Forms Designer
Figure 5. The formsSAPIntegerationDemo project downloaded to Lotus Forms Designer
The formsSAPIntegerationDemo project downloaded to the 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
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:

  1. Create the Transformation Extender Types Trees from the SAP BAPIs that are called.
  2. Create a new Integration Project in Lotus 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. Configure the forms submission rules to point to the pipelines to be created.
  7. Upload all components to the Lotus Forms Services Platform server.
  8. 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:

  • BAPI_ADDRESSEMP_CHANGE
  • BAPI_ADDRESSEMP_GETDETAIL
  • BAPI_ADDRESSEMP_GETLIST
  • BAPI_BANKDETAIL_CHANGE
  • BAPI_BANKDETAIL_GETDETAIL
  • BAPI_BANKDETAIL_GETLIST
  • BAPI_EMPLOYEE_GETDATA
  • BAPI_EMPLOYEET_DEQUEUE
  • BAPI_EMPLOYEET_ENQUEUE

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
    Specify that Type Tree is 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
    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
    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
    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
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
Functionality required from WebSphere Transformation Extender, when executing the GetEmployeeData pipeline
Figure 13. Execution flow when populating the employee instance with data from SAP
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
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(&quot;INSTANCE1&quot;)" 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:

  • GetForm
  • GetEmployeeData
  • SubmitForm

Two custom pipes had to be developed for these pipelines:

  • LoadInstancePipe
  • LoadVariablesPipe

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.

GetForm Pipeline

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
The GetForm pipeline

GetEmployeeData 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 Platform.
    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
The GetEmployeeData pipeline

SubmitForm 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
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:

  1. Request the form.
  2. Enter the employee number.
  3. Make changes and submit the form.
  4. Check that the submitted form was stored on the server (optional).
  5. 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
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
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
The form is populated with the employee's information
Form is populated 2
Form is populated 3

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
Make modifications to the employee's data and click Submit Form
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
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
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
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
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
Use the SAP frontend to verify the changes were committed to SAP
Use the SAP frontend to verify the changes were committed to SAP

Conclusion

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.


Downloads

DescriptionNameSize
Sample codeextensions.zip12KB
Sample codeformsSAPIntegrationDemo.zip184KB

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. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. 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


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus, WebSphere
ArticleID=257850
ArticleTitle=Integrating IBM Lotus Forms with SAP using the Lotus Forms Services Platform
publish-date=09252007