WebSphere Process Server relationship service, Part 1

Static relationships


IBM® WebSphere® Process Server relationship service provides capabilities that enable WebSphere Integration Developer to correlate properties that may have different values but have the same semantic meaning across a group of related business objects. There are two primary relationship types: dynamic and static. You can use dynamic relationships to correlate primary keys from a set of related business objects and static relationships to correlate non-primary key properties. This article focuses on static relationships and subsequent articles focus on dynamic relationships.

Business scenario

The business scenario assumes that the IBM Corporation has three different enterprise systems that have a representation of customer. The IBM IT organization has determined the need to integrate these three systems and provide a single composite canonical representation of the customer inside a Customer Relationship Management (CRM) Hub enabling customer relationship business processes to be developed independent of the existing enterprise information systems (EIS) sytems.

Each enterprise system, SSA Global, SAP, and a DB2™ relational database, all have a representation of customer that includes an address property named state that represents a US state (this example is not internationalized). However, each of these three systems has a different value representation for state. For example, to represent the state of California the DB2-based system uses "California", the SAP system uses "CA-03", and the SSA Global system uses "Cal". In this scenario, the canonical or generic representation of Customer uses the official two-letter acronym (for example, "CA" for California). The static relationship in this scenario correlates these four syntactically different but semantically equivalent representations.

During the execution of this business integration application, the static relationship is invoked when an incoming (or outgoing) event containing the customer business object is exchanged between the external systems and the CRM Hub. Those events are intermediated using the interface map component that results in the invocation of a business object map. The business object map transforms the system-specific representation of the customer to and from the canonical representation. During that process, the business object map transforms the source state property to the target state property. This transformation is performed using the relationship service APIs to lookup the correlated data for the pertinent source and target roles using the data that was defined at authoring time. The following diagram depicts the scenario:

Figure 1. Business scenario
Business scenario

Artifact development summary

To demonstrate how static relationships solve this business scenario, the following artifacts are developed:

  • Four business objects (SSA Global, SSA, DB2, and Canonical).
  • A static relationship containing four roles (a role for each business object).
  • Pre-population data that correlates the values for the business object property defined by the relationship.
  • A business object map that invokes the static relationship to perform a transformation on the state property.
  • An interface map with a source interface and a target interface that invokes the business object map.

This article assumes that you are familiar with creating business objects, interfaces, interface maps, and business object maps.

Create the business objects

In this step, you create the four business objects required by the subsequent steps.

  1. Start WebSphere Integration Developer.
  2. Create a new module named CRM (Choose File => New =>Project).
  3. Create a customer business object for the three enterprise systems and a fourth for the canonical representation. For simplicity sake, the example uses the same property names for each of the business objects. Use the following to create each business object:
Figure 3. Business objects
Business objects
Business objects

Create the following properties and property types for each of the four business objects:

Figure 4. SSACustomer and SAPCustomer
Figure 5. JDBCCustomer and GBOCustomer

Create the relationship

Now that you created the business objects, you can create the relationship. The relationship defines a static relationship for the non-primary key state property for each of the four business objects.

  1. Create a relationship (Choose File =>New =>Relationship).
  2. In the first panel, specify the target namespace: and name CustomerState.
  3. Click Next.
    Figure 6. Create the relationship
  4. Select the second radio button on the next panel.
  5. Select the checkbox. This indicates that the relationship will be created for a static non-primary key property.
Figure 7. Create the relationship

Add the roles

Each business object that participates in the relationship must have a role associated with it. The role represents metadata that describes which property in the business object is correlated to the properties described in the others roles that are part of the relationship. Thus, for this scenario, you create four roles, one for each of the customer business objects.
To create each of the four roles, select the Add Role icon from the relationship editor pictured below:

Figure 8. Add Role

A dialog then pops up where the business object associated with the role can be selected. Select the business object and select Ok. Repeat this until you have created a role for each of the business objects (JDBCCustomer, SSACustomer, SAPCustomer, and GBOCustomer).

Modify the role properties

Each role has its target namespace and name automatically generated. It is a good idea at this point to update the target namespace, name, and display name for each role. To do this:

  1. Select the role.
  2. Select Properties from the horizontal list of items below the roles.
  3. Select Description from the vertical list of items below the Properties tab.
  4. Update the Name, Display Name, Targetnamespace attributes using values from the following table:
    Figure 9. Role Names
  5. Repeat this for all four roles.

Add Role Keys

Each of the four roles must now have its key set to the property that correlates across the relationship (for example, state). To set the key property (alias key attribute):

  1. Select the role.
  2. Select the icon labeled Add KeyAttribute. For example:
    Figure 10. Add Role Key Attributes
  3. This pops up a dialog of all the properties in the business object associated with the role. For this scenario select state.
  4. Repeat this for all four roles.

Populate the static relationship

This step is the most important portion of the authoring step for static relationships. In this step all of the possible values for each state property are entered into WebSphere Integration Developer and correlated. This provides the business object maps (developed later in the article) the relationship data they require to properly transform the state property from one of the business objects to another. To complete this step of the development lifecycle for the static relationship, create a table capturing all of the possible values for the state property in each of the systems and how they correlate. That table might look something like the following:

Figure 11. Static values table

To enter this information into WebSphere Integration Developer:

  1. Select the CustomerState icon from the relationship editor.
    Figure 12. Populate the static relationship
  2. Select Properties from the horizontal list of items below the roles.
  3. Select Instance Data from the vertical list of items below the Properties tab. Here, find Instance Data and the correlation id named 1 for the first row of correlated data.
  4. Select Add to add a second correlation id for a second row of correlated data.
  5. Expand the correlation id for the row of data corresponding to 1 and 2. Beneath those correlation ids each role in the relationship is listed. Select each role for the correlation id of 1, and fill in the information using the table above as a reference. For the GBO role use CA, for the JDBC role use California, for the SAP role use CA-03, for the SSA role use Cal.
    Figure 13. Populate the static relationship
  6. Repeat the prior step for the correlation id 2 using the information in the second line of the table to correlate state values for Texas.
    Figure 14. Populate the static relationship
  7. Adding in the first two rows worth of instance data is sufficient for the purposes of this example.

Static relationship definition summary

At this point, you have defined the static relationship. This relationship defines enough information to enable the state property to be canonicalized and decanonicalized during the transformation of the EIS customer business objects to and from the canonicalized customer business object. To demonstrate each of the integration relationships between the CRM Hub and the external systems three interface maps and three corresponding sets of business object maps would need to be developed to handle these integration scenarios:

  • SSA Global to and from the CRM Hub
  • SAP to and from the CRM Hub
  • DB2 to and from the CRM Hub

To keep this example simple, the interface map for SSA Global to/from the CRM Hub will be created using a simple set of source/target interfaces. A single business object map is then created to handle the inbound scenario where an SSA Global customer business object is transformed to a canonical customer business object. You can create the remaining two interface maps and five business object maps for extra credit.

Create the business object map

In this step, you create a business object map to transform a SSA Global business object to a canonical business object. In the process, the relationship service APIs transform the source business object's state property to the target business object's state property.

  1. Create a business object map (Choose File => New => Business Object Map).
  2. On the first panel, name the Business Object Map SSACustomerToGBOCustomer and specify the target namespace
  3. Click Next.
  4. On the second panel select SSACustomer as the input and GBOCustomer as the output.
  5. Click Finish.
  6. Create a Move transformation between every property of SSACustomer to the same property in GBOCustomer with the exception of state.
  7. Since there is no first class tooling in the Business Object Map editor for static relationships, you need to write a snippet. To write the snippet drag a link from SSACustomer to GBOCustomer. Initially this results in a Submap transformation. Select the Submap box between the two business objects and select Custom from the drop down list.
    Figure 15. SSACustomerToGBOCustomer Map
  8. Select the Custom transform located between SSACustomer and GBOCustomer and select the Properties tab from the horizontal area below the business objects.
  9. Select Java™ Imports and enter the following imports that are required by the static relationship snippet you will write:
    Listing 1. Java Imports
        import java.util.List;
        import commonj.sdo.DataObject;
  10. Select the Details tab.
  11. Select the Java radio button.
  12. Enter the following code into the Details snippet area.
    Listing 2. Static Relationship Code Snippet
        try {
    	    ServiceManager serviceManager = new ServiceManager();
            RelationshipService relationshipService = (RelationshipService) 
            int[] correlationID = relationshipService.
                "", SSACustomer);
            List participants =	relationshipService.
                "", correlationID[0]);
            DataObject gboCustomer = (DataObject) participants.get(0);
            String state = (String) gboCustomer.get("state");
            GBOCustomer.set("state", state);
        } catch (RuntimeException e) {

Create the interfaces

Prior to creating an interface map that invokes the SSACustomerToGBOCustomer map, create a source and target interface for the interface map.

  1. Create a source interface (Choose File => New => Interface).
  2. Name the interface SSAEvent and give it the target namespace
  3. Add a request/response operation named processEvent.
  4. Add an input message named ssaCustomer of type SSACustomer.
    Figure 16. Interface SSAEvent
  5. Create a target interface (File => New => Interface).
  6. Name the interface CRMHubEvent and give it the target namespace
  7. Add a request/response operation named processEvent.
  8. Add an input message named gboCustomer of type GBOCustomer.
    Figure 17. Interface GBOEvent

Create the interface map

Create the interface map for the SSA Global to and from the CRM Hub.

  1. Create a source interface (Choose File => New => Interface Map).
  2. Name it SSACustomerToFromGBOCustomer and give it the target namespace
  3. Click Next.
  4. Select the Source interface as the SSAEvent interface.
  5. Select the Target interface as the GBOEvent interface.
  6. Click Finish.
  7. Connect the processEvent operations.
  8. Select the line that connects the processEvent operations to view the Parameter mappings.
  9. Connect ssaCustomer to gboCustomer.
  10. Select move and then select Properties from the horizontal tab below the Parameter mappings.
  11. Select Description.
  12. Change move to map.
    Figure 18. Create the interface map
  13. Select Details.
  14. Select SSACustomerToGBOCustomer for the business object map.

Assembly editor

Now, set up the assembly diagram to test the relationship via the interface map component.

  1. Open up the assembly diagram.
  2. Drag the interface map SSACustomerToFromGBOCustomer onto the assembly diagram surface.
  3. Test the component with your test server.


This article shows how you can create a static relationship, create pre-population data for the static relationship, call the relationship from a map and finally create an interface map that calls the map so that the relationship can be tested on the server.

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

ArticleTitle=WebSphere Process Server relationship service, Part 1: Static relationships