Using simple identity relationships

An identity relationship establishes an association between business objects or other data on a one-to-one basis. A simple identity relationship relates two business objects through a single key attribute. The following sections describe the steps for working with simple identity relationships:

Creating simple identity relationship definitions

Identity relationship definitions differ from lookup relationship definitions in that the participant types are business objects, not of the type Data (the first selection in the participant types list). For a simple identity relationship, the relationship consists of the generic business object and at least one application-specific business object. The participant type for a simple identity relationship is a business object for all participants. The participant attribute for every participant is a single key attribute of the business object. (For more information on how to create a relationship definition for a simple identity relationship, see "Defining identity relationships".)

Accessing identity relationship tables

To reference a simple identity relationship, define a Cross-Reference transformation rule between the application-specific business object and the generic business object. For more information, see "Cross-referencing identity relationships".

For example, the CustIden relationship (see Figure 82) transforms a SiteID key attribute in a Clarify customer to an RefID key attribute in an SAP customer. It includes maps between the following objects:

Figure 102 shows how to use the CustIden relationship tables to transform a SiteID value of A100 to a RefID value of 806.

Figure 102. Using relationship tables to transform a SiteID to a RefID


The maintainSimpleIdentityRelationship() method must manage the relationship tables to ensure that related application-specific keys remain associated to a single relationship instance ID. At a high level, the Cross-Reference transformation rule generates code to do the following:

  1. Perform validations on the arguments that are passed in. If an argument is invalid, the method throws the RelationshipRuntimeException exception. For a list of validations that the Java code generated by the Cross-Reference transformation performs, see the maintainSimpleIdentityRelationship() API in IdentityRelationship class.
  2. Takes the appropriate actions to maintain the relationship tables based on the calling context, which includes the following factors:

This transformation deals with the calling contexts shown in Table 73..

Table 73. Calling contexts with maintainSimpleIdentityRelationship()
Calling context Description
EVENT_DELIVERY A connector has sent an event from the application to InterChange Server Express (event-triggered flow).
ACCESS_REQUEST An access client has sent an access request from an external application to InterChange Server Express.
SERVICE_CALL_REQUEST A collaboration is sending a business object down to the application through a service call request.
SERVICE_CALL_RESPONSE A business object was received from the application as a result of a successful response to a collaboration service call request.
SERVICE_CALL_FAILURE A collaboration's service call request has failed. As such, corrective action might need to be performed.
ACCESS_RESPONSE The source business object is sent back to the source access client in response to a subscription delivery request.

The following sections discuss the behavior of the Cross-Reference transformation with each of the calling contexts in Table 73..

EVENT_DELIVERY and ACCESS_REQUEST calling contexts

When the calling context is EVENT_DELIVERY or ACCESS_REQUEST, the map is being called is an inbound map; that is, it transforms an application-specific business object to a generic business object. A connector sends the EVENT_DELIVERY calling context; an access client sends an ACCESS_REQUEST calling context. In either case, the inbound map receives an application-specific business object as input and returns a generic business object as output. Therefore, the task for the Cross-Reference transformation is to obtain from the relationship table a relationship instance ID for a given application-specific key value.

For the EVENT_DELIVERY and ACCESS_REQUEST calling contexts, the Java code generated by the Cross-Reference transformation takes the following actions:

  1. Locate the relationship instance in the relationship table that matches the given application-specific business object's key value. Table 74 shows the actions that the Java code generated by the Cross-Reference transformation takes on the relationship table based on the verb of the application-specific business object.
  2. Obtain the instance ID from the retrieved relationship instance.
  3. Copy the instance ID into the generic business object.

    Table 74. Actions for the EVENT_DELIVERY and ACCESS_REQUEST Calling Contexts
    Verb of application-specific business object Action Performed by maintainSimpleIdentityRelationship()
    Create Insert a new entry into the relationship table for the application-specific business object's key value.

    If an entry for this key value already exists, retrieve the existing one; do not add another one to the table.
    Update Retrieve the relationship entry from the relationship table for the given application-specific business object's key value.

    If an entry for this key value does not exist, add one to the table.
    Delete
    1. Retrieve the relationship entry from the relationship table for the given application-specific business object's key value.
    2. Mark the relationship entry as "deactive".


    Retrieve Retrieve the relationship entry from the relationship table for the given application-specific business object's key value. If an entry for this key value does not exist, throw a RelationshipRuntimeException exception.

For an identity relationship that supports the transformation of an AppA application-specific business object to AppB application-specific business object, Figure 103 shows how the Java code generated by the Cross-Reference transformation accesses a relationship table associated with the AppA participant when a calling context is EVENT_DELIVERY (or ACCESS_REQUEST) and the AppA application-specific business object's verb is either Create or Update.

Figure 103. EVENT_DELIVERY and ACCESS_REQUEST with a create or update verb


For a calling context of EVENT_DELIVERY (or ACCESS_REQUEST) and an application-specific verb of either a Create or Update, Figure 104 shows the write that the Java code generated by the Cross-Reference transformation makes to the relationship table when no entry exists that matches the AppA application-specific key value.

Figure 104. The Write to the relationship table for a new relationship entry


For a calling context of EVENT_DELIVERY (or ACCESS_REQUEST) and an application-specific verb of Delete, Figure 105 shows the write that the Java code generated by the Cross-Reference transformation performs on the AppA relationship table.

Figure 105. The write to the relationship table for a delete verb


SERVICE_CALL_REQUEST calling context

When the calling context is SERVICE_CALL_REQUEST, the map is being called is an outbound map; that is, it transforms a generic business object to an application-specific business object. The outbound map receives a generic business object as input and returns an application-specific business object as output. Therefore, the task for the Cross-Reference transformation is to obtain from the relationship table an application-specific business object's key value for a given a relationship instance ID only if the verb is Update, Delete, or Retrieve. The Cross-Reference transformation does not obtain the application-specific key value for a Create verb.

Table 75 shows the action that the Cross-Reference transformation takes on the relationship table based on the verb of the generic business object.

Table 75. Actions for the SERVICE_CALL_REQUEST calling context
Verb of generic business object Action performed by the Cross-Reference transformation
Create Take no action.

When the calling context is SERVICE_CALL_RESPONSE, the method actually writes a new entry to the relationship table. For more information, see "SERVICE_CALL_RESPONSE calling context".

Update Delete Retrieve
  1. Obtain the generic business object's key value (the relationship instance ID) from the original-request business object in the map execution context.
  2. Retrieve the entry from the relationship table for the given generic business object's key value. If an entry for this key value does not exist, throw a RelationshipRuntimeException exception. If no participants are found when the verb is Retrieve, throw a CxMissingIDException exception.
  3. Obtain the application-specific key value from the retrieved relationship entry.
  4. Copy the application-specific key value into the application-specific business object.

As Table 75 shows, when the verb is Create, the Java code generated by the Cross-Reference transformation does not write a new entry to the relationship table. It does not perform this write operation because it does not yet have the application-specific key value that corresponds to the relationship instance ID. When the connector processes the application-specific business object, it notifies the application of the need to insert a new row (or rows). If this insert is successful, the application notifies the connector, which creates the appropriate application-specific business object with a Create verb and the application's key value.

For the remaining verbs (Update, Delete, and Retrieve), the Java code generated by the Cross-Reference transformation performs a read operation on the relationship table. For an identity relationship that supports the transformation of an AppA application-specific business object to AppB application-specific business object, as Figure 106 shows how the Cross-Reference transformation accesses a relationship table associated with the AppB participant when a calling context is SERVICE_CALL_REQUEST and the generic business object's verb is Update, Delete, or Retrieve.

Figure 106. SERVICE_CALL_REQUEST with an update, delete, or retrieve verb


SERVICE_CALL_RESPONSE calling context

When the calling context is SERVICE_CALL_RESPONSE, the map is being called is an inbound map; that is, it transforms an application-specific business object to a generic business object. The inbound map receives an application-specific business object as input and returns a generic business object as output. The SERVICE_CALL_RESPONSE calling context is important for the Create verb, to indicate that the destination application was able to create a unique value for the new entity and the connector has returned an application-specific business object.

The task for the Cross-Reference transformation rule is to maintain an application-specific business object's key value in the relationship table for an existing relationship instance ID. For the SERVICE_CALL_RESPONSE calling context, the Java code generated by the Cross-Reference transformation takes the following actions:

  1. Determines whether the generic business object is null:
  2. Locates the entry in the relationship table that matches the given application-specific business object's key value. Table 76 shows the action that the Java code generated by the Cross-Reference transformation takes on the relationship table based on the verb of the application-specific business object.

Table 76. Actions for the SERVICE_CALL_RESPONSE calling context
Verb of application-specific business object Action performed by maintainSimpleIdentityRelationship()
Create For the given application-specific key, insert into the relationship table the new relationship entry containing the application-specific business object's key value and its associated relationship instance ID. The method obtains the relationship instance ID from the original-request business object in the map execution context (cwExecCtx).

If an entry for this key value already exists, retrieve the existing one; do not add another one to the table.

Delete
  1. Retrieve the relationship entry from the relationship table for the given application-specific business object's key value.
  2. Mark the relationship entry as "deactive."

Update Retrieve the relationship entry from the relationship table for the given application-specific business object's key value.
Retrieve Retrieve the relationship entry from the relationship table for the given application-specific business object's key value.

For an identity relationship that supports the transformation of an AppA application-specific business object to AppB application-specific business object, Figure 107 shows how the Java code generated by the Cross-Reference transformation accesses a relationship table associated with the AppB participant when a calling context is SERVICE_CALL_RESPONSE and the AppB application-specific business object's verb is Create.

Figure 107. SERVICE_CALL_RESPONSE with the create verb


When the calling context is SERVICE_CALL_RESPONSE and the verb is Create, the inbound map has been invoked by the connector controller in response to the following actions:

For a calling context of SERVICE_CALL_RESPONSE and an application-specific verb of Create, Figure 108 shows the write that the Java code generated by the Cross-Reference transformation makes to the relationship table.

Figure 108. The write to the relationship table for a create verb


The Cross-Reference transformation must associate the new AppB application-specific key with its equivalent value in the AppA application. For the EVENT_DELIVERY or ACCESS_REQUEST calling context, the Cross-Reference transformation could just generate a new relationship instance ID. However, for SERVICE_CALL_RESPONSE, the Cross-Reference transformation cannot just generate a new instance ID. Instead, it must assign the same relationship instance ID to the AppB key value as it has already assigned to the AppA key value. The method obtains the instance ID associated with the AppA key value from the original-request business object, which is part of the map execution context.

In Figure 108, the Java code generated by the Cross-Reference transformation takes the following steps for the SERVICE_CALL_RESPONSE calling context and the Create verb:

When the map executions with both the EVENT_DELIVERY (or ACCESS_REQUEST) and SERVICE_CALL_RESPONSE calling contexts (and a Create verb) are complete, the relationship tables for AppA and AppB use common relationship instance IDs to associate their keys, as Figure 109 shows.

Figure 109. Creating the relationship instance


For the Update and Delete verbs (and Retrieve, if the instance ID already exists in the relationship table), the Cross-Reference transformation just retrieves the relationship instance ID from the relationship table. For a calling context of SERVICE_CALL_RESPONSE and an application-specific verb of Delete, the Cross-Reference transformation must take an additional step to deactivate the relationship instance, as Figure 110 shows.

Figure 110. The write to the relationship table for SERVICE_CALL_RESPONSE and a delete verb


SERVICE_CALL_FAILURE calling context

When the calling context is SERVICE_CALL_FAILURE, the map is being called is an inbound map; that is it transforms an application-specific business object to a generic business object. For SERVICE_CALL_FAILURE, the inbound map receives an null application-specific business object as input and returns a generic business object as output. The SERVICE_CALL_FAILURE calling context is important for the Create verb; it indicates that the destination application was unable to create a unique value for the new entity and therefore the connector was unable to return an application-specific business object. The task for the Cross-Reference transformation is the same for all verbs, as Table 77 shows.

Table 77. Actions for the SERVICE_CALL_FAILURE calling context
Verb of Application-Specific business object Action Performed by maintainSimpleIdentityRelationship()
Create Delete Update Retrieve
  1. Obtain the key value (relationship instance ID) from the generic business object. This generic business object is in the map execution context.
  2. Copy the retrieved instance ID into the generic business object.

ACCESS_RESPONSE calling context

When the calling context is ACCESS_RESPONSE, the map is being called is an outbound map as a result of a call-triggered flow. It transforms a generic business object to an application-specific business object. The outbound map receives a generic business object as input and returns an application-specific business object as output. Therefore, the task for the Cross-Reference transformation is the same for all verbs, as Table 78 shows.

Table 78. Actions for the ACCESS_RESPONSE calling context
Verb of generic business object Action Performed by maintainSimpleIdentityRelationship()
Create Delete Update Retrieve
  1. Obtain the key value (relationship instance ID) from the generic business object. This generic business object is in the map execution context.
  2. Convert the relationship instance ID to an integer value. If this conversion fails, throw an exception.
  3. Copy the key values from the original-request business object into the application-specific business object.

Because the original-request business object for ACCESS_RESPONSE is the application-specific business object, the Cross-Reference transformation automatically obtains this key value from the original-request business object in the map execution context (cwExecCtx).

The Cross-Reference transformation can perform the tasks in Table 78 as long as it has access to the original-request business object. However, in some cases, it might not have access to this business object. For example, if the Cross-Reference transformation is processing a child object that didn't exist in the primary request, the method tries to retrieve that child object's relationship instance ID. If the method can't find the relationship instance, it just populates the keys of this child object with the CxIgnore value.

Defining transformation rules for a simple identity relationship

For information on defining a Cross-Reference relationship, see "Cross-referencing identity relationships".

Coding a child-level simple identity relationship

If child business objects have a unique key attribute, you can relate these child business objects in a simple identity relationship. Coding this simple identity relationship involves the following steps:

Creating the child relationship definition

To create a relationship definition for a simple identity relationship between child business objects, take the following steps:

  1. Create a participant definition whose participant type is the child business object.
  2. Set the participant attribute to the key attribute of the child business object.

    Expand the child business object and select the key attribute.

  3. Repeat steps 1 and 2 for each of the participants. As with all simple identity relationships, this relationship contains one participant for the generic business object and at least one participant for an application-specific business object. Each participant contains a single attribute: the key of the business object.

Customizing the parent map

In the map for the parent business object (the main map), add the mapping code to the attribute that contains the child business object. In the Activity Editor for this attribute, take the following steps to code a simple identity relationship:

  1. If you created a submap for the child object, call this submap from the child attribute of the main map. Usually mapping transformations for a child object are done within a submap, especially if the child object has multiple cardinality.
  2. Use the General/APIs/Identity Relationship/Maintain Child Verb function block to set the source child objects' verbs for you.

    The last parameter of the General/APIs/Identity Relationship/Maintain Child Verb function block is a boolean flag to indicate whether the child objects are participating in a composite relationship. Make sure you pass a value of false as the last argument to the General/APIs/Identity Relationship/Maintain Child Verb function block because this child object participates in a simple, not a composite identity relationship. If the child object has a submap, call the General/APIs/Identity Relationship/Maintain Child Verb function block before the call to the submap. For more information, see "Setting the source child verb".

Note:
If the key attribute of the parent business object also participates in a simple identity relationship, define a Cross-Reference transformation in the main map, as described in "Cross-referencing identity relationships".

Customizing the submap

In the submap, perform the following steps:

  1. Define a More or Set Value transformation for the child business object.
  2. Define a Cross-Reference transformation for the child business object and specify the relationship name and participant. For more information, see "Cross-referencing identity relationships".

Copyright IBM Corp. 1997, 2003