Static and dynamic relationships in WebSphere Process Server and WebSphere ESB V7

Using the relationship service in WebSphere ESB without custom coding

Learn how to build mediation flows containing static and dynamic relationships using IBM® WebSphere® Integration Developer without the need for any custom Java™ code, and then deploy and run them from the unit test environment.

Brian Venn (vennb@uk.ibm.com), Software Tester, IBM

Photo of Brian VennBrian Venn is the System Verification Test Team Lead for WebSphere Process Server and Enterprise Service Bus on z/OS, working at IBM in Hursley, United Kingdom, since October 2000. He has 15 years of experience in the software industry. He is an IBM Certified Solution Designer for SOA Solutions, an IBM Certified Deployment Professional, and has participated in the authoring of four WebSphere Process Server and Enterprise Service Bus examinations. Brian holds a Bachelor’s degree in Astrophysics from Southampton University, United Kingdom.



15 September 2010

Also available in Spanish

Introduction

The relationship service is an integrated part of both IBM WebSphere Process Server (hereafter called Process Server) and IBM WebSphere Enterprise Service Bus (hereafter called WebSphere ESB). The service enables developers to associate business data with different values in different systems, but represent the same information. Figure 1 shows an example where the system is working with three different Enterprise Information Systems. The same customer exists on each system, but the data for the town that the customer lives in is stored in a different fashion on each of the systems.

Figure 1. Example scenario
Example scenario

The relationship service has two distinct relationship types: static and dynamic. Static relationships are used to map between non-primary key values, where the data does not change frequently (such as zip codes). Dynamic relationships are used to define correlations on the key attributes that uniquely identify the business objects.

Using the relationship service in a WebSphere ESB mediation flow via a Business Object Mapper Mediation primitive allows you to take advantage of the service without the need for custom code.


WebSphere ESB static relationship development walkthrough

In this scenario, there are two enterprise systems, each with its own representation of data that needs to be associated through the relationship service.

For simplicity sake, this scenario comprises of a single relationship lookup between a DB2® system that uses three letter representations of town names, and a Process Server application that needs the full town name. The solution uses the relationship service to seamlessly map the data between the systems.

  1. Start WebSphere Integration Developer (hereafter called Integration Developer) and create a new workspace.
  2. Choose File > New Mediation Module.
  3. Name the module RelationshipServiceExample.

Next, create the business objects that will be used to represent each of the systems. In this example, there are two business objects, one for the external DB2 representation and one for the Process Server system. The details for each system are shown in Table 1.

Table 1. Business object details
SystemNamespaceBOName
DB2 http://www.ibm.com/bo/db2 DB2Customer
WPS http://www.ibm.com/bo/wps WPSCustomer
  1. In Integration Developer, select DataTypes > New > Business Object.
  2. Enter the details for the Namespace and the Name as shown in Figure 2.
    Figure 2. New Business Object panel
    New Business Object panel
  3. Click Finish.
  4. The Business Object editor opens. For the DB2Customer Business Object, add four string fields called:
    • fName
    • lName
    • Town
    • id
  5. Click File > Save.
  6. Repeat Steps 1 to 5, this time using the details for the Process Server system from Table 1.

Next, create a business graph for each of the business objects:

  1. In the Project Explorer, right-click the DB2Customer Business Object and from the menu, select Create Business Graph.
  2. Repeat the step for the WPSCustomer Business Object.

Once completed, you have four items listed under Datatypes in the Project Explorer, the DB2Customer, the WPSCustomer business objects, and their respective business graphs.

Create the interfaces

  1. Return to the assembly diagram.
  2. Click the RelationshipServiceSample mediation and click Add interface.
  3. In the “Add interface” dialog box, select New.
  4. In the “New interface” dialog box, enter a namespace of http://www.ibm.com/interfaces/db2 and a name of DB2Event as shown in Figure 3.
    Figure 3. New Interface Editor
    New Interface Editor
  5. Click Finish.
  6. The Interface editor opens. Click the Add One Way Operation icon.
  7. Set the operation name as incomingMessage, the input name as customerIn, and the type as DB2CustomerBG.
  8. Select File > Save.

Add the reference

  1. Return to the assembly diagram.
  2. Click the RelationshipServiceSample Mediation and click Add reference.
  3. In the Add reference dialog box, select New.
  4. In the New interface dialog box, enter a namespace of http://www.ibm.com/interfaces/wps and a name of WPSEvent.
  5. The Interface editor opens. Click the Add One Way Operation icon.
  6. Set the operation name as receiveMessage, the input name as customerOut, and the type as WPSCustomerBG.
  7. Select File > Save.

Add the map

  1. Return to the assembly diagram and double-click on RelationshipServiceSample.
  2. A message displays indicating that the selected component is not implemented. Click Yes.
  3. In the “Generate Implementation” dialog box, click OK.
  4. The Operations Overview is now displayed. Click on incomingMessage Operation under DB2Event.
  5. A dialog box now appears asking to select a Mediation Flow Template. Select Operation Map.
  6. In the “Select Reference Operation” dialog box, click OK.
  7. The Mediation Flow editor l now opens. A default XSLT transform primitive called “input_map” is generated. Select this primitive and delete it.
  8. From the primitives pallet, select Transformations > Business Object Map and drag the primitive onto the flow.
  9. Wire up the Business Object map terminals to the input and callout terminals as shown in Figure 4.
    Figure 4. Meditation Flow editor
    Meditation Flow editor
  10. Add a fail primitive to the flow. Wire the fail terminal of the BOMapper primitive to the fail terminal.
  11. Double-click the Business Object Map primitive.
  12. In the “New Business Object Map” dialog, enter a namespace of http://www.ibm.com/bo/customerMap and a name of customerMapper.
  13. Click Finish.

Create the Business Object Map

  1. The Business Object Map editor now opens.
  2. Click the + symbols to expand out both business objects.
  3. Drag a wire between customerIn DB2CustomerBG and customerOut WPSCustomerBG.
  4. This map has a default value of “Submap”. Select the submap and in the Properties Pane, select the Details tab.
  5. In the Details tab, for the Business Object Map, select New.
  6. In the “New Business Object Map” dialog, enter a namespace of http://www.ibm.com/bo/customerMap and a name of RelationshipMapper and click Finish.
  7. Click the + symbols to expand out both business objects.
  8. Drag a connection from the Name field on the left business object to the fName field on the right business object. Repeat this for the lName field.
  9. Perform this one more time for the town field. Once completed, click on the Move operation currently showing as the operation between the town fields (as shown in Figure 7). A dialog window is displayed with the various transformation operations available. From the list, select Relationship Lookup.
    Figure 5. Mapping the relationship
    Mapping the relationship
  10. Click the Relationship Lookup transformation and select Show in Properties.
  11. In the Properties tab, select Details.
  12. For the Relationship lookup definition, click New.

Create the relationship

  1. In the “New Relationship Dialog” box, enter a namespace of http://www.ibm.com/relationships/customerTown and a name of customerTown.
  2. Click Next. Select Static Relationship and click Next.
  3. Select Identity relationship and click Finish.
  4. The relationship editor now opens. Click the icon for Add Role.
  5. In the dialog box, select DB2Customer and click OK.
  6. Repeat this for the WPSCustomer.
  7. Select the DB2 Customer and click the Add Key Attribute icon.
  8. In the “Select Key Attributes” dialog, select town and click OK.
  9. Repeat this for the WPS Customer.
  10. Next, click the CustomerTown relationship icon (located just above the Add Role icon), and select the Show in properties view.
  11. In the Properties view, select the Instance Data tab (Figure 6).
  12. You can now populate the relationship with the data that the service will use to map the data. In this scenario, you will be mapping between a DB2 system that uses three letter versions of town names to a Process Server system that uses the full town name. Some sample data is provided in Table 2.
Table 2. Sample static relationship data
DB2 valueWPS value
SOU Southampton
POR Portsmouth
CAR Cardiff
ABR Abertillery
  1. Use the Add button to enter the instance data into the relationship. Note: Be careful not to leave any blank rows as this causes an error in Integration Developer.
    Figure 6. Entering relationship instance data
    Entering relationship instance data
  2. Return to the customer mapper as shown in Figure 7. In the Properties view, for the input role name, select customerTown_DB2Customer and for the output role name, select customerTown_WPSCustomer.
    Figure 7. Business Object Editor with relationship details
    Business Object Editor with relationship details
  3. Select File > Save All. All problems and red crosses have disappeared.

You can now deploy the flow to the system and test it:

  1. Return to the Assembly diagram.
  2. Click the mediation and select Test Component.
  3. In the Test Client, enter some data into the fields (Figure 8). In the town field, enter one of the three letter town names that were entered into the relationship instance data earlier.
    Figure 8. Test Client with sample data
    Test Client with sample data
  4. Click Continue.
  5. After a few seconds, the flow will run. Click receiveMessage: WPSEventPartner in the test client output to see the message content.
  6. Looking at the message content in the right-hand window, you can see that the town field of the business object now contains the full town name value, indicating that the relationship has been invoked and has correctly mapped the value.
  7. Try repeating the testcase for a town value that is not in the relationship service, such as “XXX”. You will see that this causes the mediation flow to go to the fail terminal, indicating that no relationship data is found for that data. You can use this to implement relationship data error handling in your mediation flows.

Creating the dynamic relationship

The mediation flow now contains a static relationship. The next stage is to add a dynamic relationship into the Business Object map.

  1. Open the customer mapper data map again.
  2. In the map editor, drag a wire between customerIn DB2Customer and customerOut WPSCustomer.
  3. The default value of this transform will be “Submap”. Click on this and from the list, select relationship. The map editor now looks similar to Figure 9.
  4. In the Properties pane, click the Details tab.
  5. For Relationship definition, select New.
  6. The “Create relationship dialog” box is now shown. Enter a namespace of http://www.ibm.com/relationships/customerId and a name of DynamicCustomerId.
  7. Click Next.
  8. Select the Relationship Type as a Dynamic Relationship and click Next.
  9. Select an Identity Relationship and click Finish.
  10. The Relationship editor is now open. Click Add Role and select DB2Customer from the dialog box.
  11. Repeat and add the WPS Customer.
  12. Select a role and click Add Key Attribute.
  13. In the “Select Key Attribute” dialog box, select id, and click OK.
  14. Repeat for the other role.
  15. Select the DynamicCustomerId_WPSCustomer role and click the Details tab in the Properties box.
  16. Ensure that the managed box is selected.
  17. Save and close the relationship editor.
  18. Click the relationship map created in Step 2 and click Details in the Properties tab.
  19. Select DynamicCustomerId_DB2Customer as the role name.
    Figure 9. Adding the dynamic relationship
    Adding the dynamic relationship
  20. Select File > Save All. All the red crosses have disappeared.

The updated mediation flow that containings both a static and a dynamic relationships are now ready to be deployed and run.

  1. Return to the Assembly diagram.
  2. Click the mediation and select Test Component.

In the Test Client, enter some data into the fields (Figure 10). In the town field, enter one of the three letter town names that were entered into the relationship instance data earlier. Also at this time, enter some arbitrary value into the Id field.

Figure 10. Test Client sample data
Test Client sample data

This time both the static and dynamic relationships are invoked (Figure 11).

Figure 11. Test client with successful static and dynamic relationship invocation
Test client with successful static and dynamic relationship invocation

When the mediation flow map is invoked with the business object graph DB2Customer, a call is made to the Business Object map primitive in the flow, which contains the submap. The submap calls the relationship with the DynamicCustomerId_WPSCustomer role. Because the verb in the Business Graph has the value “create”, the invocation causes the relationship service to generate a unique ID for the WPSCustomer role. In the the above example, the ID is "3". The relationship service now saves the information of DB2Customer with an ID of “12345” corresponds to WPSCustomer with an ID of “3”.

You can also invoke the operation with retrieve, update, or any other of the permitted operations by changing the verb parameter in the test client. Try changing the verb in the test client and performing a retrieve, update, or delete of a dynamic relationship.


Conclusion

This article showed how you can create and call both a static and dynamic relationships from a WebSphere ESB mediation flow, without the need for any custom Java coding.


Download

DescriptionNameSize
Project interchange fileRelationshipServiceWESBExample.zip30KB

Resources

Learn

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 WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=521373
ArticleTitle=Static and dynamic relationships in WebSphere Process Server and WebSphere ESB V7
publish-date=09152010