Chapter 3. Implementing multi-product AS/2 communication with trading partners
3.5 Integration between the Interchange Server, WebSphere Data Interchange and TPI
The Interchange Server (ICS) is often used as a platform for integrating applications within an enterprise. While we cannot cover all aspects of using this technology in a single redbook, this section will describe some typical operations that allow the ICS to interact with
WebSphere Data Interchange. We will cover the use of the MQSeries Connector to send and receive data to and from products such as WebSphere Data Interchange. The use of other connectors, such as JText Connector, is very similar. One can also use the TPI Connector for a close integration between TPI and the ICS. For an example of such a setup, refer to the redbook B2B Solutions using WebSphere Business Connection, SG24-6197.
3.5.1 Creating business objects
The first step would be the creation of a business object matching the DTD that we used previously in WebSphere Data Interchange. You can use the Business Object Designer and define the fields manually. However, for a more realistic DTD representing a purchase order, there would be many more fields than what we use here. Defining the business object manually would then become an error-prone operation.
Tools are provided to make the definition of a business object easier. An optional installation component of the Interchange Server is the XMLODA, XML Object Discovery Agent. Launch the agent from the ODA\XML directory. When it is started, you should see a command window as shown in Figure 3-46 on page 151.
Figure 3-46 XML Object Discovery Agent is running
Now launch the Business Object Designer and select File -> New Using ODA from the menu, as shown in Figure 3-47.
Figure 3-47 Using the Business Object Designer
A new window will appear to guide you through the definition process. Click the button Find
Agents to populate the right pane with available agents and select the XML ODA agent from
the list. Select Next to continue (Figure 3-48 on page 152).
Figure 3-48 Business Object wizard - Step 1
Most of the fields in Step 2 are populated by default. Provide the following information:
Name of the file that contains the DTD
Root element
Top Level element
BOPrefix
Then select Next to continue (Figure 3-49).
The next step allows you to select other levels (or nodes) in the XML document for which you would like to create a business object definition. You might, for example, require an object to represent a single Detail element. For our purposes, this is not required. Therefore, we select the top node and click Next to continue (Figure 3-50).
Figure 3-50 Business Object wizard - Step 3
Step 4 summarizes your selections so far. At Step 5, you need to select a verb to go with the business objects. Figure 3-51 shows the selection of the Create verb. Click OK to continue.
Finally, in Step 6, you can choose where to save the business object. If the ICS is running and you are connected to it, the first option,
Save business objects to the server
, should be available. Alternatively, save the business object to an import file (selected option in Figure 3-52) and open the file later in the CrossWorlds System Manager by clicking File ->Open from File.
Figure 3-52 Business Object wizard - Step 6
3.5.2 Configuring the MQSeries connector
Depending on the version of ICS with which you are working, the MQSeries connector might also be called the WebSphere MQ connector, reflecting the name change of WebSphere MQ itself.
Updating the XML meta-object
Open the business object MO_DataHandler_DefaultXMLConfig and save it as
MO_DataHandler_WDIXML_Config. Make the following changes to this business object:
Set the attribute DTDPath to the directory that holds the DTD for the POResponse XML document.
Set the BOPrefix to POACK, which is the prefix used during the creation of the business object (see Figure 3-49 on page 152).
Figure 3-53 Data Handler business object
Now open the business object MO_DataHandler_Default. Update the Type field for element text_xml and set it to the XML Data Handler object MO_DataHandler_WDIXML_Config which we created before. Figure 3-54 shows the completed meta-object. Save this business object to the server.
Figure 3-54 Default Data Handler business object
Defining the meta-object MO_WDIXML_config
The connector requires a meta-object that describes how to convert the business object to an XML message in a queue. Open the Business Object Designer and create a new business
object, named MO_WDIXML_Config. When the Object Designer window appears, select the tab Attributes and make the following changes:
In the name field, add POACK_POResponse_Create In the field App Spec Info, type InputFormat=MQSTR Add another attribute. In the name field, type Default Select the check box Key for this attribute
In the field App Spec Info, type:
OutputQueue=queue://cw_studenta.queue.manager/POACKQ?targetClient=1
POACKQ is the name of the triggered queue for which WebSphere MQ will launch the WDIAdapter program, as configured in 3.4.2, “Preparing EDI documents” on page 142. Replace cw_studenta.queue.manager with the name of your queue manager. The option
targetClient=1 instructs the ICS to generate a standard WebSphere MQ message, instead of a JMS message. Figure 3-55 shows the completed meta-object.
Figure 3-55 Business object MO_WDIXML_Config
Configuring the MQSeries connector
Expand the folder Connectors in the System Manager and double-click the object MQSeries
Connector. Click the tab Connector Agent to specify the connector-specific properties, as
detailed in Table 3-1.
Table 3-1 Connector properties
Property Value
InDoubtEvents Reprocess
Channel CHANNEL1
InProgressQueue queue://cw_studenta.queue.manager/MQ-
Figure 3-56 shows the Connector Designer window where you need to specify the values listed in Table 3-1 on page 156.
Figure 3-56 Configuring the MQSeries connector
Select the tab Supported Business Objects. Click the blank cell under the heading
Business Object Name. A drop-down box will appear. Select POACK_POResponse from the list and select the check box Agent Support. Also add the meta-object
MO_DataHandler_default to this table and select the check box Agent Support again. When finished, select File -> Save to Server. During the save, you may receive warnings about the need to restart the connector. You can accept those warnings. When the save process is finished, switch to the System Manager and right-click the MQSeries connector in the folder Connectors; stop and restart the connector.
3.5.3 Developing a test collaboration
The next step is the development of a collaboration that will generate the POResponse document for processing by WebSphere Data Interchange. Open the CrossWorlds System Manager and expand the folder Collaboration Templates. Locate the template
CollaborationFoundation and copy and paste it in the folder Collaboration Templates.
DataHandlerConfigMO MO_DataHandler_Default ConfigurationMetaObject MO_WDIXML_Config DataHandlerMimeType text/xml Port 1414 Hostname studenta Property Value
Name the copied template WDI_Outbound_Template. Open the new template in the Process Designer by double-clicking it. Select Template -> Open Template Definitions to update the template. Select the tab Ports and Triggering Events. Update the BO Name for each port and set it to POACK_POResponse. Change the field Create for the From row (2) to Main (see Figure 3-57).
Apply the changes and compile the updated template.You can delete the port DestinationAppRetrieve, but that is not required.
Figure 3-57 Update the template definitions
Now that we have a template that fits our needs, we can create a collaboration object. Right-click the folder Collaborations and select New collaboration object from the context menu. Select the template WDI_Outbound_Template and name the new collaboration WDI_Outbound. Click Next. Now bind the ports to the connectors, as shown in Figure 3-58 on page 159.
Set the From port to PortConnector and the To port to MQSeriesConnector. Also set the DestinationAppRetriever port to PortConnector, if you have not deleted this port in the template.
Click Next twice, then click Finish to complete the definition of this collaboration.
Note: If your installation of the Interchange Server does not have this template, you can
find an import file for this template as part of the additional material for this redbook. Refer to Appendix B, “Additional material” on page 217.
Note: If you do not see the PortConnector as an available choice, you need to update the
list of supported business objects for the PortConnector and include the business object POACK_POResponse.
Figure 3-58 Bind the ports of the collaboration
If all steps were performed without problems, the System Manager will now show a graphical representation of the collaboration, as shown in Figure 3-59.
Figure 3-59 WDI_Outbound collaboration
Finally, start the collaboration by selecting Component -> Start WDI_Outbound. Or, select the start command from the context menu of the collaboration.
3.5.4 Using the Test Connector
The final step is to use the Test Connector tool to drive the collaboration. Before you start this tool, you should perform a number of validation tasks.
Expand the folder Connectors in the System Manager and verify that the MQSeriesConnector is started.
Verify that the PortConnector is started. Sometimes this connector is in a paused state, which is usually caused by a missing queue in WebSphere MQ. If you cannot get the PortConnector to start, verify that the queue AP/PORTCONNECTOR/CW_STUDENTA
exists. Replace CW_STUDENTA with the name of your InterChange Server. If this queue does not exist, create it with default attributes.
Start the MQSeries Connector that we configured previously by selecting Start ->
Programs -> IBM CrossWorlds -> Connectors -> MQSeries Connector. Verify in the
output that the connector has started correctly. You can also start the System Monitor (from the Tools menu in the CrossWorlds System Manager) and verify that the agent state of the MQSeries Connector is Active.
Now start the Test Connector by selecting Start -> Programs -> IBM CrossWorlds ->
Connectors -> Test Connector. When the tool is started, select File -> New Profile, which
will bring up a profile selection window. Select Add to create a new profile.
Provide the name of the server, the password of the admin user ID (usually the word null) and the name of the connector that we are going to simulate: PortConnector. You can leave the field Config File blank. The test connector should be able to locate the configuration file by itself. Alternatively, you should point to the ICS configuration file manually (usually
D:\CrossWorlds\InterchangeSystem.cfg). Click OK to close this window.
Figure 3-60 Create a new profile for the test connector
Select the new profile in the profile list window and click OK. The test connector is now loaded with the correct profile. Select File -> Connect Agent to connect to the ICS. When the connection succeeds, the test connector will list all business objects that are supported by the port connector, as shown in Figure 3-61 on page 161.
Figure 3-61 Running the test connector
Double-click the business object POACK_POResponse to bring up the next window. Select the verb Create and name the instance of the business object (for example testbo).
Right-click the element ROOT and select Add Instance. Now expand the ROOT element which will list two child elements, Header and Detail. Right-click these elements too and select Add Instance each time. The business object window should now look as in Figure 3-62.
Provide values for the six data elements of this business object and click OK.
This will bring you back to the main window of the test connector. Select the new business object in the tree structure and click Request -> Send.
Figure 3-63 Business object being sent
Open WebSphere MQ Explorer and browse the queue POACKQ, which should contain an XML message representing this business object. However, if the WebSphere MQ Trigger Monitor is still running, your message might be consumed already and you may need to inspect the output queues of WebSphere Data Interchange. And, if TPI Server is still running, your message might be gone to a trading partner.
This completes the basic integration of the InterChange Server in a solution with WebSphere Data Interchange. The collaboration can now be extended to include ports to real back-office applications and at this time, you will probably need to develop some maps to map business objects.
3.5.5 Inbound flow
The previous sections described in detail the integration process for the outbound flow. The steps to integrate CrossWorlds in the inbound flow are quite similar.
Business object
First, we again need a business object to represent the incoming purchase order. The DTD, listed in Example 3-11 on page 135, can be imported in the InterChange Server using the XML ODA as described in 3.5.1, “Creating business objects” on page 150.
Important: Since this business object will result in a message that will be processed by
WebSphere Data Interchange, you should provide data that makes sense for WebSphere Data Interchange. Setting a random value for TargetPartnerID will likely result in an unprocessed document within WebSphere Data Interchange.
Specify the following values for the PO DTD:
Root element: PO Top Level element: PO BOPrefix: PO
The MQSeriesInbound Connector
The next step is to create an additional MQSeries Connector. Perform the following steps: 1. Copy and paste the existing MQSeriesConnector object in the folder Connectors in the
CrossWorlds System Manager. Name it MQSeriesInboundConnector.
2. Open a file browser and find the directory MQSeries in the connectors directory of the CrossWorlds installation. Copy the whole directory and name it MQSeriesInbound. 3. Open the folder Connectors in the Start menu and copy and paste the existing shortcut
MQSeries Connector as MQSeriesInbound Connector.
4. Open the properties of this new short-cut and update the field Target:
D:\CrossWorlds\connectors\MQSeriesInbound\start_MQSeries.bat MQSeriesInbound cw_studenta -cD:\CrossWorlds\connectors\MQSeriesInbound\MQSeriesAgentConfig.cfg
MQSeries has been replaced three times with MQSeriesInbound. Also update the field
Start in
to the name of the new directory:D:\CrossWorlds\connectors\MQSeriesInbound\
5. Define a new queue AP/MQSERIESINBOUNDCONNECTOR/CW_STUDENTA on the queue manager used by the ICS. Replace CW_STUDENTA with the name of your ICS. 6. Restart the ICS. After the restart, verify that the connector is running using the
CrossWorlds System Manager.
7. Start the connector agent using the shortcut in the Programs folder and verify that the Agent State in the System Monitor is Active.
Open the PortConnector object and update the supported business objects. Include business object PO_PO in the list and be sure to check the field Agent Support.
Creating meta-objects
Once you have verified that the new connector can be started, proceed with the definition of meta-objects. Open the meta-object MO_DataHandler_WDIXML_Config and save it as MO_DataHandler_CWXML_Config. Make the following changes:
Provide the path to the location of the DTD and the file name
Set the BOPrefix to PO
Define meta-object MO_CWXML_Config. You can copy the meta-object MO_WDIXML_Config. Rename the field POACK_POResponse to PO_PO. Define meta-object MO_DataHandler_Inbound_Default. You can copy it from MO_DataHandler_Default. For the MIME type text/xml, set the field type to
MO_DataHandler_CWXML_Config.
Open the connector object MQSeriesInboundConnector and switch to the tab Application Config Properties. Set the value of the property DataHandlerConfigMO to
MO_DataHandler_Inbound_Default. Set the value of the property ConfigurationMetaObject to
MO_CWXML_Config. Set the value of the property InputQueue to
queue://cw_studenta.queue.manager/purchase.orders. Save the changes and restart the connector.
Verifying the map in WebSphere Data Interchange
The ICS requires that the incoming XML message contain a DOCTYPE statement that includes the name of the DTD. To make sure that the XML document contains the DTD name, review the map 850TOXML in WebSphere Data Interchange. Open the map editor and verify that you have a SetProperty call for the property Diprolog, as shown in Figure 3-64.
Figure 3-64 Setting the property Diprolog
If this statement does not exist, right-click the name of the map 850TOXML and select
Insert -> Command -> SetProperty from the context menu. A mapping command editor
should appear, as shown in Figure 3-65. Update the template call of SetProperty to refer to the property Diprolog and set the value to what is required for your XML document.
Figure 3-65 Adding the name of the DTD to the XML document
Save and re-compile the map.
Creating the collaboration
Expand the folder Collaboration Templates in CrossWorlds System Manager. Copy and paste the template CollaborationFoundation and name the new template WDI_Inbound_Template. Open the new template and its definitions. Select the tab Ports and Triggering Events (see Figure 3-66 on page 165). Set the BOType to PO_PO for all three ports. Set the Create field for the From port to Main. Apply the changes. Compile and save the template.
Figure 3-66 Template definitions
Now create a new collaboration WDI_Inbound from the template WDI_Inbound_Template. Bind the ports as follows:
From port: MQSeriesInboundConnector To port: PortConnector
DestinationAppRetrieve port: PortConnector
Save and start the collaboration. Check the server log and verify that you see log messages, as shown in Example 3-22.
Example 3-22 ICS log
[System: Server] [Thread: VBJ ThreadPool Worker (#5244814)] [Type: Info] [MsgID: 31] [Mesg: Initializing collaboration "WDI_Inbound".]
[System: Collaboration] [SS: WDI_Inbound] [Thread: VBJ ThreadPool Worker (#4968337)] [Type: Info] [MsgID: 11009] [Mesg: Subscribed to PO_PO.Create from publisher MQSeriesInboundConnector.]
[System: Collaboration] [SS: WDI_Inbound] [Thread: VBJ ThreadPool Worker (#4968337)] [Type: Info] [MsgID: 11014] [Mesg: Collaboration is active.]
Using the test connector
Finally, start the test connector and select the profile PortConnector. Connect to the server and create a business object of type PO_PO. Select the newly created business object and select Request -> Accept Request. The PortConnector now acts as an endpoint and is ready to receive PO_PO business objects.
Write an EDI message on the queue INBOX, processed by WebSphere Data Interchange. The translated message, including a DOCTYPE, should then end up on queue
purchase.orders, which is monitored by the MQSeriesInbound Connector. The message will then be routed through the collaboration and end up at the port connector in the test
connector.
Figure 3-67 A business object has arrived
Select the business object in the right pane to inspect the details. Figure 3-68 shows the business object representation of this XML message, which was a translation of an EDI 850 document.