In Part one of this article series, we introduced you to WebSphere Business Integration. That article explained the components of WebSphere Business Integration (BI), including the WebSphere Business Integration Adapter (BIA) for Lotus Domino and WebSphere InterChange Server (ICS). In Part two, we're now ready to build a Domino business integration solution using the WebSphere ICS and WebSphere BI adapter technologies. This article assumes that you are an experienced Domino administrator with some familiarity with WebSphere technology.

The following procedure outlines the task that you need to complete to develop and test a Domino business integration solution with WebSphere BI:

1. Install and configure a WebSphere BIA for Domino project on WebSphere ICS. The basic steps to setup the Integration Component Library and User Project are presented in this section. For more detailed installation and configuration information, refer to the Installation Guide and System Implementation Guide for WebSphere BI Adapters and the User Guide of WebSphere BI Adapter for Lotus Domino.
2. Setup the Virtual Test Connector (VTC). We use the VTC to set up a test environment in the WebSphere BI system to test the WebSphere BIA for Domino connector. The detailed information about the VTC can be found in the Implementation Guide for WebSphere InterChange Server in the WebSphere ICS InfoCenter.
3. Create a collaboration template and a collaboration object for WebSphere BIA for Domino. The detailed information can be found in the Collaboration Development Guide in the WebSphere ICS InfoCenter.
4. Deploy the WebSphere BIA for Domino project to WebSphere ICS. We complete the whole development process and can deploy our project to WebSphere ICS for testing.
5. Run the WebSphere BIA for Domino test in a WebSphere ICS test environment. We complete setup in a WebSphere BI system test environment and can test our Domino application integration solution.

Before you work on the preceding tasks, ensure that you have all the necessary prerequisites. The following list gives you a brief overview of what you need to do to meet the prerequisites:

• Follow the installation and implementation guides in the WebSphere ICS InfoCenter to install and setup WebSphere ICS and the WebSphere BI toolset.
• After installing WebSphere ICS and the WebSphere BI toolset, install WebSphere BIA for Domino.
• Follow the WebSphere BI Adapter for Lotus Domino User Guide to configure WebSphere BIA for Domino and the Domino server. Save the WebSphere BIA for Domino connector configuration as a configuration file (CFG).
• Download the WebSphere Business Integration Adapters and look for the Lotus Domino Adapter user guide.

Install and Configure WebSphere BIA for Lotus Domino Project on WebSphere ICS

In order to run WebSphere BIA for Domino on WebSphere ICS, you need to create a user project of WebSphere BIA for Domino and install it on the WebSphere ICS. The tool to create the user project is System Manager. To create and install the WebSphere BIA for Domino user project, complete the following tasks:

1. Create a server instance for WebSphere ICS.
2. Create an Integration Component Library and a user project for WebSphere BIA for Domino.
3. Modify the WebSphere BIA for Domino connector configuration.

Create a server instance for WebSphere ICS

After you install WebSphere ICS, start the server. You should see the following message from your WebSphere ICS InterchangeSystem.log to indicate your server is started:

[Time: 2003/08/20 15:48:10.483] [System: Server] [Thread: main (#2718475)] [Type: Info] [MsgID: 20] [Mesg: InterChange Server "thinker_wics421" is ready.]

Start the System Manager, and then open the System Manager Perspective from WebSphere Studio to register your WebSphere ICS server. In Figure 1, you can browse your WebSphere ICS server from the network or type the name of the server into the Server Name field, provide the user name and password, and then click Finish.

After you finish the server registration, the WebSphere ICS server name appears in the InterChange Servers pane on the left corner of your System Manager. You can change the server mode to Design from the default Production mode, so you can load your WebSphere ICS repository.

Create an Integration Component Library and user project for WebSphere BIA for Domino

Load the repository file websphere_ics.in to populate your WebSphere ICS database tables, so you can import the integration components into your Integration Component Library (ICL). Create a new ICL for WebSphere BIA for Domino. Select File - New - Integration Component Library in System Manager to open the New Integration Component Library dialog box. Enter the project name and select your WebSphere ICS server from the drop-down list in the Import components from server field.

In the next dialog box, select the Business Objects of WebSphere BIA for Domino: DominoDocument, DominoEmbeddedObject, DominoItem and DominoItemValue, and Connectors: DominoConnector. Click Finish. Afterward, you should see that WBIALD_ICL is created under Integration Component Libraries in System Manager.

Create a new user project. Select File - New - User Project in System Manager. In the New User Project dialog box, enter the project name and select WBIALD_ICL in Available Integration Component Libraries, and then click Finish.

Modify WebSphere BIA for Domino connector configuration

Click the DominoConnector to open the WebSphere BIA for Domino connector configuration. Modify this connector configuration according to the User Guide for WebSphere BI Adapter for Domino. Figure 4 shows the connector configuration we use in this article.

Save the changes you made to both the project and the configuration file. You will use this configuration file later when you run WebSphere BIA for Domino. You need to update the project after you update the connector configuration by selecting the project and choosing Update project.

Setup Virtual Test Connector

Using Virtual Test Connector (VTC), you can set up a test environment in WebSphere BI to test the integration components. VTC is used to emulate a source connector in the WebSphere BI system. In the production environment, you can replace the VTC with an enterprise adapter, such as SAP connector to set up the real business integration environment. To create a VTC from System Manager, select WebSphere BIA for Domino ICL-Connectors, and then create a new connector called TestConnector. In the TestConnector configuration, specify ICS as Broker Type and make sure DominoDocument is selected on the Supported Business Objects tab. Save the configuration to your Integration Component Library project. Refer to the Implementation Guide for WebSphere ICS for more detailed VTC implementation information.

Back to top

Create the WebSphere BIA for Domino collaboration template and object

As we described in Part one of this article series, WebSphere ICS collaboration begins as a collaboration template. Developing collaboration involves the following steps:

1. Specify the collaboration for WebSphere BIA for Domino.
2. Create the collaboration template for WebSphere BIA for Domino.
3. Build the Action Nodes for WebSphere BIA for Domino collaboration.
4. Compile the collaboration template and create the collaboration object.

Refer to the Collaboration Development Guide in the WebSphere ICS InfoCenter for more information about collaboration development.

Specify the collaboration for WebSphere BIA for Domino

In this step, we design a collaboration of request/response interaction for WebSphere BIA for Domino as shown in the following table.

In Figure 5, you can view the logic of this WebSphere BIA for Domino collaboration. We use Virtual Test Connector (VTC), which ships with the WebSphere ICS toolset, to simulate an adapter that communicates with an enterprise application. The collaboration is triggered by receipt of a triggering Domino document Business Object (BO). When a collaboration is triggered, it receives or sends the BO to both connectors through In and Out ports.

Create the collaboration template for WebSphere BIA for Domino

Open Process Designer to create a new collaboration template for WebSphere BIA for Domino, name the template, and save the template to your ICL project. Select the collaboration template name and open the collaboration template definition. The template definition has the following tabs: General, Declarations, Properties, and Ports and Triggering Events. In this article, we only need to provide the port property information through which the collaboration interacts with connectors. The collaboration ports specify the interfaces with the outside collaboration. When the collaboration sends a request or receives a response, it does so via a port.

In Figure 6, In and Out ports are created in Process Designer to handle the calls from both ports.

You also need to create the scenarios for this collaboration template. A scenario is a process of actions derived from a certain verb and port. Because our collaboration contains multiple scenarios, we name each scenario based on the event verb, for instance, if the scenario handles creating Domino documents, we call it Create. There are a total of four scenarios in WebSphere BIA for Domino collaboration.

Build the action nodes for WebSphere BIA for Domino collaboration

After you create the scenarios, build the action nodes using Activity Diagram. An action node represents a step in a collaboration scenario. Refer to your collaboration design to determine how many steps you need to take for a certain scenario. In Figure 7, we build a simple activity diagram for the CreateOnWBIALD scenario in Process Designer. Refer to the Collaboration Development Guide in the WebSphere ICS InfoCenter for how to use Process Designer to build the activity diagram. Save the collaboration template.

Compile the collaboration template and create the object

Select the collaboration template and right-click to choose Compile Template. A message indicates whether the compilation succeeded or failed. If you need to debug your collaboration template code, you can find the source code generated by Process Designer in your Tools\WSWB203\Workspace\WBIALD_ICL\Templates\Src directory.

Back to System Manager: Select the collaboration objects under your WebSphere BIA for Domino ICL and choose Create New Collaboration Object to name the collaboration object. In our test case, we create two collaboration objects: WBIALDTestCollabObj_VTCToDomino and WBIALDTestCollabObj_DominoToVTC. In the Select collaboration template dialog box, bind In port to TestConnector and Out port to DominoConnector for WBIALDTestCollabObj_VTCToDomino collaboration.

After you finish the creation of collaboration objects, you see a diagram to illustrate relationships between the collaboration components in System Manager. Figure 8 shows the components relationship for collaboration WBIALDTestCollabObj_DominoToVTC.

Back to top

Deploy the WebSphere BIA for Domino project to WebSphere ICS

After you complete the integration component development, update your WebSphere BIA for Domino user project in System Manager. Then, you are ready to deploy your user project for WebSphere BIA for Domino to your ICS server. Make sure to add your user project to your WebSphere ICS server before the deployment.

Deploy the user project to the server by selecting your server name again and choosing Deploy Project(s). Make sure you stop all components in your user project in System Monitor before you deploy the user project. Every time you update your project, you have to redeploy it to the server. After you successfully deploy the WebSphere BIA for Domino user project to WebSphere ICS, you should see the green lights on for DominoConnector, TestConnector, and the collaboration objects in the System Monitor.

You can start or stop your collaboration objects and connectors at any time.

Back to top

Run WebSphere BIA for Domino in a WebSphere ICS test environment

After you deploy your user project, it's time to test it. In this section, we demonstrate how to run the WebSphere BIA for Domino in a WebSphere ICS test environment. We use WebSphere ICS as an integration server to mediate integration between the Domino server and an enterprise application. WebSphere BIA for Domino is used as a connecter between the Domino server and WebSphere ICS. VTC acts as a virtual connector to link WebSphere ICS to an enterprise application in this test.

Before you run the test, ensure that you have followed the WebSphere BIA for Lotus Domino User Guide to configure the WebSphere BIA for Domino connector and to create the connector configuration file. If you did not complete this step during the WebSphere BIA for Domino configuration and setup, you need to do it now. From System Manager of WebSphere BIA, open the DominoConnector configuration and save this configuration to DominoConnector.cfg in your connectors\Domino directory, along with other WebSphere BIA for Domino files that are installed by the WebSphere BIA installer.

Start your test to monitor the events on your Domino server and to exchange business objects between VTC and the Domino server.

Start the WebSphere BIA for Domino

Make sure you modify the start_Domino.bat based on the location of the Domino Java API JAR file (NCSO.jar). Typically, it resides at your data\domino\java directory. You can start the WebSphere BIA for Domino connector from a command line or Start menu. To start it from a command line, type the following command from your connectors\Domino directory:

start_Domino Domino IntegrationServerName -cDominoConnector.cfg

where IntegrationServerName is your WebSphere ICS name. After you start WebSphere BIA for Domino, you should see the following message in the WebSphere BIA for Domino log file or from the command line to indicate that WebSphere BIA for Domino is active:

[Time: 2003/08/27 15:58:44.182] [System: ConnectorAgent] [SS: DominoConnector] 
	[Thread: main (#2704014)] [Type: Info] [MsgID: 17066] [Mesg: Application state is connected] 
[Time: 2003/08/27 15:58:55.799] [System: ConnectorAgent] [SS: DominoConnector] 
	[Thread: main (#2704014)] [Type: Info] [MsgID: 17053] 
	[Mesg: Publishing messages on queue AP/DominoConnector/thinker_wics421.] 
[Time: 2003/08/27 15:58:56.440] [System: ConnectorAgent] [SS: DominoConnector] 
	[Thread: VBJ ThreadPool Worker (#4578761)] [Type: Info] [MsgID: 17064] 
	[Mesg: Connector Agent state is active.]

Run the test on WebSphere BIA for Domino

Open the VTC, and create a profile for TestConnector. In the New Profile dialog box, enter TestConnector in the Connector Name field and select ICS as the broker type. Then enter your server user name and password.

After you connect to the WebSphere ICS server from TestConnector, a message tells you the TestConnector is ready from your TestConnector console. You can create the business object or load the business object that you pre-created in VTC. Click Send BO to send the BO to the Domino server. You should see the following message in your trace file to indicate WebSphere BIA for Domino has received the BO sent from VTC:

[Time: 2003/09/03 18:17:56.841] [System: ConnectorAgent] [SS: DominoConnector] 
	[Thread: VBJ ThreadPool Worker (#7597170)] [Type: Trace] [Mesg: :[Type: Trace] 
	[MsgID: 4002] [Mesg: Entering method: DominoBOHandler.doVerbFor()] ] 
[Time: 2003/09/03 18:17:56.861] [System: ConnectorAgent] [SS: DominoConnector] 
	[Thread: VBJ ThreadPool Worker (#7597170)] [Type: Trace] [Mesg: :[Type: Trace] [MsgID: 5505] 
	[Mesg: DominoBOHandler.doVerbFor(): Received Business Object: <StartHeader>
<Version = 3.0>
<EndHeader>
<StartBO:DominoDocument>

...

ObjectEventId = TestConnector_1062627460878_2
<EndBO:DominoDocument>] ]

When you create, update, or delete a Notes document in the Notes client, WebSphere BIA for Domino catches those events and sends the business objects to VTC. For instance, suppose you create a purchase order document in a Domino application. After you save the document the WebSphere BIA for Domino event listener catches this create event, and the event shows up in the WebSphere BIA for Domino event table to indicate this event status is READY_FOR_POLL. The WebSphere BIA for Domino connector performs the event poll when it reads the event from the event table and sends the Domino document business object to the VTC. From VTC, you see the arrival BO as illustrated in Figure 11.

Click the arrival BO to check its fields and values to make sure that is the document you created in your Domino application. In this step, we complete the tests in both directions via WebSphere ICS and WebSphere BIA for Domino from a simulation adapter (VTC) to Domino server and from the Domino server to the VTC.

Back to top

Conclusion

This article describes some of what WebSphere Business Integration offers and how to integrate Domino business applications with other enterprise applications via WebSphere InterChange Server and WebSphere BI Adapters. We also demonstrate how to achieve the bidirectional access from the Domino server to back-end relational databases, ERP systems, and all other enterprise applications through WebSphere BI. The approach introduced in this article makes use of WebSphere ICS, WebSphere BI Adapters, and WebSphere BIA for Domino technologies to provide a solution for Domino business integration. Future articles in this series will explore how WebSphere Application Server can help enable business integration with Domino applications.

Resources

• Read part one of this series, "Integrating Domino business applications with WebSphere Business Integration."
  
  
• The following links provide more information, which will help you to further understand WebSphere Business Integration:
  • WebSphere Developer Domain Business Integration Zone
  • WebSphere Business Integration Adapters
  • WebSphere BI Adapters 2.3.1 Information Center
  
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Install and Configure WebSphere BIA for Lotus Domino Project on WebSphere ICS
• Create the WebSphere BIA for Domino collaboration template and object
• Deploy the WebSphere BIA for Domino project to WebSphere ICS
• Run WebSphere BIA for Domino in a WebSphere ICS test environment
• Conclusion
• Resources
• About the author
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

Dig deeper into Lotus on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers