Developing integration solutions with WebSphere Process Server relationships

Cross-referencing with the Relationship Service

The Relationship Service in IBM WebSphere Process Server is an infrastructure service that is well integrated with other transformation components to support the development of complex integration solutions. It frees integration developers from needing to custom-build cross-referencing logic within their business logic. Relationships are extensible and manageable; therefore, using relationships in your applications can increase the overall agility of your integration solution.

This article introduces the capabilities of the WebSphere Process Server Relationship Service, including those new in V6.1, and explains when and how to use these capabilities. Prior knowledge of Process Server is helpful, but not required. This content is part of the IBM WebSphere Developer Technical Journal.


Benjamin Busjaeger (, Software Engineer, IBM

Benjamin Busjaeger photoBenjamin Busjaeger is a Software Engineer in the WebSphere Process Server development team at the IBM Bay Area Lab. His current technical focus is on transformation technologies in service oriented architectures. Benjamin holds a Masters degree in Information Systems from the University of Hamburg, Germany.

Hong Sun (, Software Engineer, IBM

Hong Sun photoHong Sun is a Software Engineer at IBM Bay Area Lab. Previously, she was a senior software engineer at Crossworlds Software. She has been working in the business integration and business process management space for the past 8 years. Hong holds a Masters degree in Computer Science.

Yuntao Zhou (, Software Engineer, IBM

Yuntao Zhou photoYuntao Zhou is a Software Engineer at IBM Bay Area Lab in Foster City, California. He joined IBM in 2007 after graduating from UC Berkeley with a BS degree in Electrical Engineering and Computer Science. Yuntao currently works on the WebSphere Process Server development team.

03 April 2008 (First published 27 February 2008)


This article is structured in a question/answer format to give you a quick and easy introduction to using IBM® WebSphere® Process Server (hereafter Process Server) relationships. The goal is to enable you to recognize when to use relationships and to provide you with a comprehensive overview so you can easily apply relationships for your specific solution. The following questions are answered in this article:

What are relationships?

A relationship in Process Server is used in business integration solutions to capture cross-references between objects residing in different domains. The most common type of relationship is an identity relationship, which captures cross-references between business objects or business object properties that are semantically equivalent, but which are identified differently within different applications. This type of relationship fits into these two patterns supported by Process Server, which are the focus of this article:

  • Lookup of static property values
  • Dynamic identity correlation

Lookup relationships

A lookup relationship defines a manually populated mapping between business object property values.

Example 1. A lookup releationship

Suppose one application represents the state property of an Address business object as full names, for example "California", while another application represents a corresponding state property in its Address business object using two-letter codes, for example "CA." You can create a StateCode lookup relationship to establish a static mapping between the state full names and codes. Then, when an application transforms one address into another address, it can transform state names into state codes, and vice versa, by querying the StateCode relationship.

Figure 1. Conceptual view of look relationship
Figure 1. Conceptual view of look relationship

As illustrated in Example 1, lookup relationships are commonly used during business object transformations to translate property values that would otherwise have to be transformed using long, hard-coded if-else or switch statements. This is often the case for domain-specific codes or status indicators. Encapsulating the mapping in a lookup relationship makes it reusable and increases flexibility by enabling modification of the mapping data at runtime.

Dynamic relationships

A dynamic relationship defines correlations between business objects according to the key attributes that uniquely identify them. You use these relationships when the same business object exists in different applications, that object has application-specific identifiers, and you need to exchange instances of this object between the applications. The key attribute mappings are not manually populated; instead, the Relationship Service creates and removes them dynamically when the data in the connected application changes.

Example 2. A dynamic relationship

Suppose two applications each define Customer business objects and generate their own internal keys to uniquely identify instances of this business object. When integrating the customer data managed by the two applications, the same customer can exist in both applications with identifiers that do not match. Thus, to exchange information about the customer between the applications, a correlation mapping between the identifier used for the customer in one application and the identifier used for the same customer in the other application must be maintained. A dynamic CustomerRelationship can be created to define such a mapping. As customers are created or deleted, the Relationship Service dynamically adds or removes identifier mappings to the relationships.

Figure 2.Conceptual view of dynamic relationship
Figure 2.Conceptual view of dynamic relationship

How do relationships work?

The Relationship Service stores the correlation data in tables in the relationship database. An instance of the relationship connects the two properties using an instance id. Figure 3 shows a conceptual view of the base tables for the address relationship described in Example 1.

Figure 3. Relationship tables
Figure 3. Relationship tables

For lookup relationships the instance data is manually populated at design-time. When a transformation looks up an output for a given input, the Relationship Service uses the instance id to find the matching row.

Dynamic relationships use a similar table structure to associate key attributes with each other; however, automating the creation and deletion of instances requires additional context information. To provide the Relationship Service with this context information, dynamic relationships must be used within an synchronization integration pattern. Let's walk through an example application of the pattern for synchronizing customer information stored in separate applications which, in this case, are used by the sales and marketing departments.

Example 3. Synchronization integration pattern

Two applications are connected to Process Server, for example, by means of an application-specific adapter. Initially, no customer instances exist in either application and the relationship tables are empty.

The Sales application creates a customer object and stores it using a generated identifier. The application (or an adapter) publishes the customer object marked as "created" to a synchronization module running in Process Server.

Figure 4. Incoming event delivery
Figure 4. Incoming event delivery

Next, the customer object is transformed into a generic customer representation that serves as a common denominator for the different customer objects. As part of the transformation, the Relationship Service is invoked to maintain the customer relationship. The Relationship Service marks the business object as created, generates a new instance id, and creates a new table entry to associate it with the application-specific id. It sets the instance id as the key attribute of the generic customer object.

Figure 5. Generic transformation
Figure 5. Generic transformation

The generic customer object is then transformed into the customer business object used within the Marketing application. The Relationship Service is invoked again; however, because no application-specific identifier has been generated yet, no action is taken.

When the Marketing application receives the created customer, it generates a new identifier and stores the customer object. It returns the customer object containing the generated identifier.

Figure 6. Outgoing request
Figure 6. Outgoing request

The received customer object is transformed back into the generic customer object. During the transformation the Relationship Service is invoked again. It detects that the created business object is sent as a response to the request originating from the generic customer with the instance id 1. It creates a new table entry to assoociate the instance id with the application-specific identifier.

Figure 7. Outgoing response
Figure 7. Outgoing response

After this initial creation of the relationship instance, updates to customer information can be processed using similar steps. The Relationship Service simply uses the relationship instance to convert identifiers, without changing the instance. When a deleted business object is received and transformed, the identifiers are converted, and then the instance is deactivated.

This example illustrates the set of rules you must follow to enable the Relationship Service to automatically maintain cross-references for your dynamic relationships.

  1. Each application is responsible for notifying Process Server when a change occurs. To indicate the type of change, the application must mark the business objects as "created", "updated", or "deleted". See the next section, How can I use relationships?, to learn how to associate these markers with business objects in Process Server.

  2. You must define a generic business object to unify the different business object representations. Your transformation logic must transform incoming business objects into this generic representation, before being transformed into the application-specific business objects that are sent out for synchronization.

  3. You must define the operations that are invoked to send newly created business objects to target applications as request/response operations. Then, Relationship Service can correlate the newly generated identifier with the relationship instance on the response path.

  4. No restrictions apply for operations other than those described in rule 3.

You might wonder why application-specific business objects need to first be converted into generic business objects before being converted into the target format. The intent behind this rule is to guide users toward the best practice of minimizing connections that need to be maintained. Example 3 involves integrating only two; however, you could conceivably later need to integrate other applications that need to store customer information as well. If you do not define a generic customer object and you add more applications, then you must also add additional transformation connections to all other applications, quickly leading to a complex mesh of dependencies. Developing the core business logic based on a generic data representation decouples it from the specifics of each application.

How can I use relationships?

Using relationships involves:

  1. Defining relationships.
  2. Adding relationships to transformations.
  3. Manually invoking relationships.

This article describes these aspects at a conceptual level and illustrates the tooling you can use to work with relationships. For more detailed step-by-step instructions for putting together an integration solution, see the Resources section for links to related articles and other information.

Defining relationships

You define relationships using IBM WebSphere Integration Developer (hereafter Integration Developer). You first define the type of relationship by selecting or deselecting the checkbox Use to transform data attributes according to a static mapping (see Figure 8) in the New relationship wizard. Selecting the checkbox creates a lookup relationship; deselecting it creates a dynamic relationship.

Figure 8. New relationship wizard
Figure 8. New relationship wizard

You use the radio buttons on this page of the wizard to specify the cardinality of the relationship. Selecting one-to-one creates an identity relationship, in which each instance id can be associated with at most one value per table. Use this option for most lookup and dynamic relationships. You can use one-to-many or many-to-many relationships for lookup relationships that map one value to multiple other values. For example, a zip code lookup relationship might map the phone area code "650" to the zip codes "94010," "94305," and so on.

After creating the relationship definition, you can add roles to the relationship. A role stands for what we have been calling a connected application up to this point. When adding a role, you need to name it and select the type of object to be maintained by the relationship for this role.

For dynamic relationship roles, you select the business object that is semantically equivalent to the business objects selected for the other roles, and you specify the key attribute used to identify that object. Dynamic relationships also require one managed role that represents the generic domain. The managed role is typed with the generic business object and points to the key attribute that will hold the relationship instance id at run time. Figure 9 shows the relationship definition for the CustomerRelationship; the managed role is highlighted in blue by the relationship editor.

Figure 9. CustomerRelationship relationship definition
Figure 9. CustomerRelationship relationship definition

A business object could be identified by more than one of its properties, which is called a composite key. A special case of a composite role is where a business object can only be uniquely identified when combining its key attribute with its parent’s key attribute. In this case you select the parent business object and define two key attributes: one pointing to the parent key and one pointing to the child key. Figure 10 shows a relationship between line items in which one of the roles is defined for a line item that is unique only within the Order that contains it.

Figure 10. Composite line item role
Figure 10. Composite line item role

For roles in lookup relationships, you can either select a business object and point the key attribute to the property used in the static mapping, or you can select the simple type of the values you are intending to map. The latter approach is recommended because it makes the relationship more reusable.

For example, you could define the roles in the StateCode lookup relationship on the Address business objects with key attributes pointing to the State fields, or you could just use simple string types for each role. Using string types enables you to reuse the relationship in any mapping between business objects that need a state name to state code mapping between string-typed properties. Using Address business objects in the roles restricts the use of the relationship to mappings between addresses. Our relationship definition for the StateCode relationship is shown in Figure 11.

Creating lookup relationships requires one more step which is pre-populating the instance data. Figure 11 shows the instance data window for the StateCode relationship. Instances are listed by instance id and you can add or remove them. To specify a value, select a role name within an instance and enter a specific value.

Figure 11.StateCode relationship definition
Figure 11.StateCode relationship definition

Adding relationships to transformations

You can add relationships to transformations when using business object maps.

Lookup relationships are applied by drawing a Relationship Lookup transformation between a source and target property. This transformation type is new in Process Server V6.1; you can use it for identity lookup relationships only. To configure the transformation, you select the names of the relationship, source role, and target role in the details pane. Figure 12 shows a map definition containing a relationship lookup transformation for the StateCode relationship.

Figure 12. Relationship lookup transformation in business object map
Figure 12. Relationship lookup transformation in business object map

In earlier versions of Process Server and for many-to-many lookups, you need to use the Relationship Service APIs to manually lookup property values from custom transformations. See Manually invoking relationships for information on how to do this.

To apply dynamic relationships in business object maps, you draw a Relationship transformation between the two business objects whose identifiers are to be correlated. You configure the transformation with the names of the relationship and the application-specific role. Because either the source or the target must be the generic business object and only one managed role exists per relationship, the managed role name is not needed. Figure 9 shows an example relationship transformation using CustomerRelationship.

Figure 13. Relationship Transformation in business object map
Figure 13. Relationship Transformation in business object map

As previously discussed, dynamic relationships do not work in isolation; they must be used within the end-to-end integration pattern. Consequently, business object maps invoking dynamic relationships must be properly embedded in a context built around the rules discussed previously. You can implement the pattern in Process Server as shown in Figure 14.

Figure 14. Data sync in Process Server
Figure 14. Data sync in Process Server

The business object maps (), using the relationship () to perform data transformation, are called from interface maps () that mediate between application-specific and generic interfaces (). The services imported and exported by the interface maps send and receive business objects to and from the applications and the central dispatching logic.

The dispatching logic simply publishes business objects to all applications interested in the change (in this case, only one application).

When the interface maps invoke the business object maps, they pass the information that is necessary for the Relationship Service to determine the context in which it is invoked.

Tip: Starting with V6.1, you can use business object maps and relationships in mediation flow components. Therefore, you could also directly implement the flow described above in WebSphere Enterprise Service Bus by replacing the interface maps with mediation flow components.

Another aspect of the pattern is how markers are associated with business objects to indicate whether an object has been created, updated, or deleted. Process Server wraps a business object with a business graph, which is a container for associating additional metadata with business objects. To generate the graph, use Integration Developer; you right-click on a business object and select Create a Business Graph.

The business graph has two facilities that can be used to represent markers (see Figure 15): the verb and the change summary.

  • The verb is a string, usually Create, Update, or Delete, that indicates the action to take for a graph of objects. When the verb is Update, it is up to the receiver of the graph to figure out what was modified in the graph; the verb applies to the whole graph.
  • The change summary records all changes applied to objects and properties in the graph from the point it is turned on. Markers for any object or property in the graph can then be derived directly from the change summary.
Figure 15. Verb and change summary in business graphs
Figure 15. Verb and change summary in business graphs

Business objects maintained by dynamic relationships must always be wrapped in a business graph containing either verb or change summary information so that the Relationships Service can determine what action to take.

Manually invoking relationships

You can also use relationships programmatically through the Relationship Service APIs within or outside of business object maps. The primary API elements of interest are:

Create, retrieve, deactivate, or remove a participant. A participant is the value of a role within a given instance, which can be either a simple value or a business object.
Check if exists, deactivate, or delete a participant by instance id (as opposed to by its value).
Add a new participant to a given instance (used for many-to-many relationships only)
Return an array of instance ids for a participant of a given role. For identity relationships the array can contain at most one instance id.
Look up the value of a property in the output business object for the value of a property in the input business object (new in 6.1)
Automatically maintain the correlation between two business objects of a dynamic relationship (new in 6.1; previously maintainIdentity)
Associate properties, such as time of creation, with role or relationship instances

Listing 1 shows a code sample for programmatically retrieving, adding, and deleting instance data.

Listing 1. Using the CRUD API elements for relationship instance data
//locate the Relationship Service
RelationshipService relService = (RelationshipService)ServiceManager.INSTANCE.

//The names of our relationship and its roles
String relationshipName = "http://CRMLib/StateCode";
String roleName_full = "http://CRMLib/FullStateName";
String roleName_code = "http://CRMLib/StateCode";

//programmatically query a lookup relationship 
String fullName = "California";
String code = null;
int[] ids = 
  relService.retrieveInstanceIDsByString(relationshipName, roleName_full, fullName);
if( ids.length > 0 ){
   List codes = relService.retrieveParticipants(relationshipName, roleName_code, ids[0]);
   if( !codes.isEmpty() )
      code = (String)codes.get(0);

//add a new relationship instance
String newFullName = "Alabama";
String newCode = "AL";
int genId =  
  relService.addParticipantString(relationshipName, roleName_full, newFullName);
relService.addParticipantStringWithID(relationshipName, roleName_code, genId, newCode);

//remove relationship instance
relService.deleteParticipantString( relationshipName, roleName_full, newFullName);
relService.deleteParticipantString(relationshipName, roleName_code, newCode);

Listing 2 shows how to programmatically perform a lookup for the StateCode relationship using staticLookup, which is new in V6.1.

Listing 2. Lookup transformation
//locate the Relationship and BOFactory Service
RelationshipService relService = (RelationshipService)ServiceManager.INSTANCE.
BOFactory boFactory = 

//The names of our relationship and its roles
String relationshipName = "http://CRMLib/StateCode";
String roleName_full = "http://CRMLib/FullStateName";
String roleName_code = "http://CRMLib/StateCode";

//name space and BO names
String tns_app1 = "http://CRMLib";
String addressName_app1 = "Address_App1";
String stateProp_app1 = "state";
String tns = "http://CRMLib";
String addressName = "Address";
String stateProp = "state";

//create input and output address with input state set
DataObject address_app1 = boFactory.create(tns_app1, addressName_app1);
address_app1.setString(stateProp_app1, "California");
DataObject address = boFactory.create(tns, addressName);

//Have the Relationship Service set the state code into the output
			new String[]{stateProp_app1},
			new String[]{stateProp});

To use the correlate API element for maintaining dynamic relationships, you have to manually pass the context information that would otherwise be provided by the interface maps. Process Server comes with a relationship sample project that illustrates how to do this. You can find the sample along with its source code in your Process Server directory under samples/lib/RelSample.

How do I manage relationships?

Process Server provides an administrative interface for managing relationships, called Relationship Manager, which is integrated into the administrative console. You can use this interface to query and manipulate relationship instances at run time for both lookup and dynamic relationships. Relationship Manager invokes the JMX API exposed by the Relationship Service, which you can also use to build your own customized administration capabilities.

Figure 16. Relationship Manager
Figure 16. Relationship Manager

Relationships can also be used in Network Deployment (ND) environments without any extra configuration. In an ND environment, relationships are installed in an application cluster. The relationship is then visible within the cluster, and all servers in the cluster have access to the instance data stored in the relationship database. The ability to run the Relationship Service in an ND environment makes it scalable and highly available.

To manage relationships in an ND environment, the Relationship Manager is connected to a server in a cluster by selecting its relationship MBean. Therefore, relationships can be managed across different clusters through a centralized administrative interface.

Where can I find more information on relationships?

Now that you understand the concepts and ideas behind relationships, you are probably eager to try them out or to dig deeper into how they work. Here are some resources we recommend, which, unless otherwise specified, are listed in the Resources section.

  • The section on relationships in IBM’s Education Assistant for Process Server covers more of the underlying technical details of the Relationship Service and includes some useful labs and demos.

  • A previous developerWorks article series on relationships, WebSphere Process Server Relationship Service, provides some basic how-to information including examples for invoking lookup relationships from custom code.

  • The relationship sample that comes with Process Server succinctly illustrates the use of the correlate API for programmatically maintaining dynamic relationships. This sample is in your Process Server directory under samples/lib/RelSample.

  • The WebSphere Business Process Management information center is a good source for reference information on the authoring and administrative tools.

  • Finally, watch developerWorks WebSphere for a follow-on tutorial that will walk through the steps of creating an end-to-end integration solution for the example use cases described in this article.


Business Objects are containers for application data that represent business functions or elements, such as a customer or an invoice.

Business graphs are wrappers that are added around a business object, or around a hierarchy of business objects, to provide additional capabilities. For example, you could carry Change Summary and Event Summary information related to the business object in the business graph.

Business object maps support mappings between the source and target business objects. They are supporting service components in WebSphere Process Server that assign values to the target business objects based on the values in the source business objects.

Interface maps are created in the interface mapping editor to resolve and reconcile differences between the interfaces of interacting components.


This article showed how relationships can be leveraged in complex integration solutions to provide cross-referencing capability. We focused on two relationship patterns supported by Process Server, lookup of static property values and dynamic identity correlation. You should now be equipped with the necessary information to put relationships to work and apply them to your specific solutions.



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

ArticleTitle=Developing integration solutions with WebSphere Process Server relationships