WebSphere Adapters are used to communicate with external systems in IBM Business Process Manager (IBM BPM). This article introduces a commonly used end-to-end business scenario to demonstrate how to develop and deploy a WebSphere Apdater on IBM BPM. Using a sample business scenario, you'll see how an external record in a database comes into IBM BPM, gets processed by a human task, and finally is stored into SAP systems.
This article assumes you have a basic understanding of IBM BPM and WebSphere Adapters. You'll need the following products installed to follow the steps in the article:
- IBM WebSphere Adapter for JDBC V220.127.116.11
- IBM Business Process Manager V8, with IBM Integration Designer
Sample business scenario
The sample scenario imagines that a company needs to synchronize data between the HR department and a SAP system. The HR department stores all information employee information, including personal and salary information. The SAP system is used to store the bank information of the wage card. When a new employee comes on board, HR creates a new record in its DB, including name, band, salary, and the bank information of the wage card. The company requires that the personal information and salary information automatically synchronizes with the SAP system separately. Before the record comes into the SAP system, a manual approval is required and supervisors can change values as needed. Meanwhile the supervisors can create a bank record in the same Coach view and insert it into SAP system via the SAP Adapter.
A WebSphere Adapter for JDBC (JDBC Adapter) inbound process is used to poll events from the HR system. The IBM BPM Coach view provides a user interface for auditors to view and modify values. A WebSphere Adapter for SAP (SAP Adapter) BAPI outbound process is responsible for inserting bank information into the SAP system, as shown in Figure 1.
Figure 1. Sample business scenario
The following sections walk you through the steps to develop and test the scenario.
Configure the HR database
Before developing the sample business scenario, you need to create and trigger the following tables in the HR database. We used Oracle® Database 9i in this scenario.
Listing 1. Scripts to create the Oracle database
/*Scripts for creating the tables in Oracle database*/ CREATE TABLE Employee ( empl_id int not null Constraint pk_emplid PRIMARY KEY, empl_fname varchar(50) not null, empl_lname varchar(50) not null, empl_age varchar(10) null, empl_band varchar(10) not null, empl_salary varchar(30) not null, empl_bankid varchar(10) not null, empl_bankname varchar(50) null, empl_bankcoun varchar(50) null, empl_bankcity varchar(50) null, empl_bankstreet varchar(255) null ); CREATE TABLE wbia_jdbc_eventstore ( event_id NUMBER(20) PRIMARY KEY, xid VARCHAR2(200), object_key VARCHAR2(80) NOT NULL, object_name VARCHAR2(40) NOT NULL, object_function VARCHAR2(40) NOT NULL, event_priority NUMBER(5) NOT NULL, event_time DATE DEFAULT SYSDATE NOT NULL, event_status NUMBER(5) NOT NULL, connector_ID VARCHAR2(40), event_comment VARCHAR2(100) ); /*Scripts for creating the trigger for Employee table*/ CREATE SEQUENCE event_sequence start with 1; CREATE OR REPLACE TRIGGER event_create AFTER INSERT ON Employee FOR EACH ROW BEGIN INSERT INTO wbia_jdbc_eventstore (event_id, object_key, object_name, object_function, event_priority, event_status,connector_ID) VALUES(event_sequence.nextval, :NEW.empl_id, 'JcajdbcEmployeeBG', 'Create', 1, 0, 'CreateEmployee'); END;
Connect to the SAP system using the SAP Adapter
In this example, we use the BAPI call
BAPI_BANK_CREATE to create bank information in
SAP. SAP Adapter Outbound sends a request to the SAP server. The SAP
Adapter BAPI import component is invoked by IBM BPM and uses RFC to
connect to the SAP system to insert records. To make the SAP Adapter
Outbound module reusable by other applications, we'll package it into a
toolkit. To configure the SAP Adapter for outbound processing and package
it in a toolkit, complete the following steps:
- Open IBM Integration Designer and connect to Process Center by
clicking Getting Started with IBM Process Center, as shown in
Figure 2, select Toolkits.
Figure 2. Getting Started with IBM Process Center
- Click Create new toolkit on the right, name the toolkit
SAPAdapter_BankCreateTK, and open the new toolkit in the workspace.
- Select File => New => External Service.
- Select SAP under Available types and click Next.
- Select IBM WebSphere Adapter for SAP Software with transaction support(IBM:18.104.22.168_IF01) and click Next.
- Import CWYAP_SAPAdapter_Tx and click Next.
- Find and select the three JCO files and click Next.
- Select Outbound and click Next.
- Specify the appropriate properties for your environment and select BAPI for SAP interface name, then click Next.
- Locate the BAPI BAPI_BANK_CREATE and add it to Selected object, then click Next.
- Click Next again.
- Check Using security properties from the managed connection factory under Deployment Properties, and click Next.
- Select the SAPAdapter_BankCreateTK_Implementation module and
click Finish. You should see an adapter import component
generated in the assembly diagram, as shown in Figure 3.
Figure 3. New import component in assembly diagram
- Right-click the Adapter project CWYAP_SAPAdapter_Tx, select Associate with Process Center, then complete the wizard using the default options.
- Drag the business object and interface from
SAPAdapter_BankCreateTK_Library, as shown in Figure 4.
Figure 4. Move the business object and interface
- Add an export component in the assembly diagram called
- Add an interface called
SAPOutboundInterfaceto the CreateBank export component.
- Right-click CreateBank and select Generate Binding => SCA binding.
- Wire the two components in the assembly diagram and save the changes.
- Right-click SAPAdapter_BankCreateTK and slect Refresh and Publish to save the changes to Process Center.
- Open the toolkit in the Process Center perspective and click
Create New Snapshot on the in right, as shown in Figure 5.
Figure 5. Create a new snapshot
SAPAdapter_BankCreateTK_V1as the name of the new snapshot.
You have now configured the SAP Adapter for outbound processing and created a SAP Adapter outbound toolkit.
Create a new process and bind the Advanced Integration Service
The process we create will be used to receive messages from the HR system via JDBC Adapter outbound processing, will provide a Coach view so that supervisors can review, and will then deliver the message to SAP via the SAP Adapter. To create this process, complete the following steps:
- Open Process Designer and create a new process application named
- Open the new application in Process Designer.
- Create a new business object (BO) by clicking Business Object
under Data on left and name it
- Add the following parameters to this BO, as shown in Figure 6:
Figure 6. Add parameters
- Create a new AIS by selecyting Implementation => Advanced
Integration Service and name it
- Add an input variable under the parameters of the AIS and name it
BankBOAIS, then set the Parameter Type to the BankBO you defined above.
- Create a new process by selecting Processes => Business Process
Definition and name it
- Add an input variable to the process named
myBandBOand set the Variable Type to BankBO.
- Add a human task to the process and name it
- Right-click the new human task, select Activity Wizard and then complete the wizard using the default options.
- Double-click the Supervisor Review human task to open the Coach.
- Select the Coaches tab, then click New in the bottom
right to create a new Coach view, as shown in Figure 7. Name the view
Figure 7. Create a new Coach view
- In the Coach view, drag the BankBO variable on the right into the
Layout panel. Your Coach view should now look like Figure 8.
Figure 8. Coach view layout
- Save and close the Coach view and the Coach.
- Add a system task to the process and name it
SAP Adapter Outbound, and bind it to the SAPAIS AIS you created earlier, as shown in Figure 9.
Figure 9. Bind the system task to AIS
- Under Data Mapping of the Property of SAP Adapter Outbound, select tw.local.myBankBO for Input Mapping.
- Wire all components in the following sequence: Start +>
Supervisor Review => SAP Adapter =>End, as shown in
Figure 10. Wire the components
Next we'll implement the AIS component in Integration Designer.
Implement the AIS
In this section, we'll implement the AIS with the SAP Adapter. ??? users are able to input value in coach and deliver to SAP then.
- Open IBM Integration Designer and connect to Process Center.
- Open the JDBC2SAP project in the workspace.
- Right-click Dependent Toolkits and select Change Toolkit Dependencies.
- In the pop-up window, select the SAPAdapter_BankCreateTK_V1 snapshot that you created earlier.
- Open the dependency JDBC2SAP_Implementation and add SAPAdapter_BankCreateTK_Library to Libraries, then click Save.
- Right-click the AIS component SAPAIS and click
Implement, as shown in Figure 11.
Figure 11. Implement the AIS
- Select Microflow and complete the wizard using the default options.
- Open the assembly diagram for JDBC2SAP_Implementation.
- Add an import component in the assembly diagram and name it
CreateBankInfo, then add an interface named
- Right-click CreateBankInfo and select Generate Binding =>SCA Binding.
- On the Properties tab of CreateBankInfo, under
Binding specify a new module with the name
SAPAdapter_BankCreateTK_Implementationand an export name of CreateBank.
- Wire SAPAIS_Process to CreateBankInfo.
- Right-click SAPAIS_Process, then select Regenerate Implementation, and then Save.
- In the regenerated microflow SAPAIS_Process, add a variable
SAPBapiBankCreateBOwith a type of
- Put a Data Map between Receive and Reply. A Map wizard displays to help you initialize the mapping, and specify configuration such as the type of map, and the input variable and output variable.
- Select XML Map and name it
BankBO2SAPBO, then add BankBOAIS as an input variable and add SAPBapiBankCreateBO as an output variable.
- Map attributes from BandBOAIS to SAPBapiBankCreateBO, as shown in
Figure 12. Map attributes
- Add an invoke component between the DataMap and the Reply and bind it
to SAPOutboundInterfacePartner, as shown in Figure 13.
Figure 13. Add an Invoke component
- Right-click JDBC2SAP and select Refresh and Publish to save changes in Process Center.
Users can now input values in the Coach and update the SAP system. We'll test this is Test the scenario.
Connect to HR database with JDBC Adapter inbound processing
JDBC Adapter inbound processing enables an application to receive notification when objects in the database are changed. In this scenario, the HR system inserts a record into the employee table in the database. The change triggers an update to the event store with information about the change. Periodically, JDBC adapter polls the event store, retrieves and processes events, and then delivers them to the export of a module that is part of an application that runs in BPM.
Complete the following steps to configure the adapter for inbound processing:
- Start the external service wizard by selecting File => New => External Service.
- Under Available Types, select Adapters => JDBC and click Next.
- Select IBM WebSphere Adapter for JDBC (IBM: 22.214.171.124) and click Next.
- In the Connector project field, enter
CWYBC_JDBC, and choose IBM Process Server v8.0 as the runtime environment. Click Next.
- In the JDBC driver JAR files field, click Add to add the JDBC driver file to establish the connection with Oracle Database. Browse to select the driver JAR file and click Next.
- We need to detect new record in Oracle Database in this scenario, so choose Inbound in the Select Processing Direction window, and click Next.
- Specify connection properties for the external service wizard in the Specify the Discovery Properties window. Expand the Oracle node in the database system connection information area and then select the correct version. Specify appropriate values in the System ID, Host name, Port number, User name and Password fields, and click Next.
- Select the business objects and services to be used with JDBC adapter under Find Objects in the Enterprise System window.
- In the Find Objects in Enterprise System window, click Run Query. Expand the schema in which the prerequisite Oracle tables are created. Select and expand Tables, then select the Employee table and click the > button to add it to Selected objects area. Click Next.
- The Specify Composite Properties window enables you to choose operations for selected business objects. For our example, keep Create and remove the others, then click Next.
- In the Specify the Service Generation and Deployment Properties
window, select the security credential Using security properties
from the activation specification. The user and password
information are displayed in the window, as shown in Figure 14. You
don't need to change any other configuration in this window. Click
Figure 14. Specify deployment properties
- In the Select a Business Integration Project Type window, browse to and select the JDBC2SAP_Implementation module and click Finish.
- After generating the artifacts of the JDBC adapter inbound process,
you need to associate the connector project CWYDB_JDBC with the
process application JDBC2SAP. Otherwise, you'll get runtime errors.
Right-click on CWYDB_JDBC and select Associate with Process
Center, as shown in Figure 15.
Figure 15. Associate with Process Center
- In the Associate with a Process Application or Toolkit window, select
the process application JDBC2SAP that will contain the project,
as shown in Figure 16, and click Finish.
Figure 16. Associate with process application
Assemble JDBC Adapter Inbound in the process
In this section, we'll make the JDBC Adapter Inbound able to deliver a message to the process. To do this, please complete the following steps:
- Drag MyProcess from the left into the assembly diagram, select
Use a one-way invocation style, and click OK, as
shown in Figure 17.
Figure 17. Add MyProcess to assembly diagram
- Add a BPEL process component into the assembly diagram and
change its name to
JDBCAdapter2Process, then add JDBCInboundInterface to it.
- Wire JDBC Adapter Inbound => Component1 => MyProcess. Your
assembly diagram should look like Figure 18.
Figure 18. Assembly diagram
- Double-click JDBCAdapter2Process and click Yes in pop-up diagram to implement the BPEL process.
- Add a variable named
myBankBOwith a type of
- Put a Data Map between Receive and End. A a wizard will display to help you initialize the mapping and specify information such as the type of map, and the input variable and output variable.
- Select XML Map and specify
JDBCBO2BankBOas the name, then add createJcajdbcEmployeeBGFInput as input variable and add myBankBO as output variable.
- Map attributes from JcajdbcEmployeeBG to BankBO, s
shown in Figure 19.
Figure 19. Map attributes
- Add an invoke component between the DataMap and the End and bind it to MyProcessOneWayPartner, then bind the input variable to myBankBO.
- Right-click JDBC2SAP and select Refresh and Publish to save changes to Process Center.
Test the scenario
Now that the scenario implementation is complete, you can test it using the test cases in this section.
Test 1: Crreate bank information using the Coach
- Open Process Designer.
- Start MyProcess.
- Specify the values
Dong Bei Wang west street) in the Coach and submit.
The information is submitted to SAP via the SAP Adapter. You should be able to see that the bank information has been created in the SAP system.
Test 2: Synchronize bank information into SAP when new employee information is created in the HR database
- Use the SQL script below to insert a record into the HR Oracle
Listing 2. Insert employee record
/*Scripts to insert a new record in Oracle database*/ Insert into Employee values ( '111', 'san', 'zhang', '31', '7', '11000', '123', 'ICBC', 'CN', 'Beijing', 'Dong Bei Wang west street'); commit;
The predefined trigger in Oracle will automatically add one event record in the JDBC Adapter event table. The event is picked up by the JDBC Adapter export component. The event is delivered to process and waits for supervisors to review.
- Using tw_admin, log on to Process Portal and view the message.
- Change nothing and click the button to approve.
- Check SAP and you should see that the bank information is already created.
This article introduced how to use the JDBC Adapter and SAP Adapter in IBM Business Process Manager to synchronize Oracle Database with a SAP system. We created a human task that enabled supervisors to modify the information between the JDBC Adapter and SAP Adapter. Following the steps in this article, you've seen how to use WebSphere Adapters to integrate BPM and external systems. Your BPM applications can leverage existing systems and quickly deliver business data wherever its needed.
- IBM Business Process Manager V8.0 Information Center
- Business Process Management Samples & Tutorials - Version 7.5
- IBM WebSphere Adapter for JDBC Samples
- IBM WebSphere Adapter for SAP Software Samples
- developerWorks BPM zone: Get the latest technical resources on IBM BPM solutions, including downloads, demos, articles, tutorials, events, webcasts, and more.
- IBM BPM Journal: Get the latest articles and columns on BPM solutions in this quarterly journal, also available in both Kindle and PDF versions.