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:
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"..)
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 a RefID key attribute in an SAP customer. It includes maps between the following objects:
Obtain from the ClarCust relationship table the relationship instance ID that is associated with the SiteID key value.
Obtain from the SAPCust relationship table the RefID key value that is associated with relationship instance ID.
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:
The Cross-Reference transformation obtains this verb from the source business object. For inbound maps, the source is the application-specific business object; for outbound maps, the source is the generic business object.
The Cross-Reference transformation rule obtains the calling context from the map execution context automatically.
This transformation deals with the calling contexts shown in Table 73..
Table 73. Calling contexts with maintainSimpleIdentityRelationship()
The following sections discuss the behavior of the Cross-Reference transformation with each of the calling contexts in Table 73..
When the calling context is EVENT_DELIVERY or ACCESS_REQUEST, the map that 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:
Table 74. Actions for the EVENT_DELIVERY and ACCESS_REQUEST Calling Contexts
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
When the calling context is SERVICE_CALL_REQUEST, the map that 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 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 |
|
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, 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
When the calling context is SERVICE_CALL_RESPONSE, the map that 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:
Table 76. Actions for the SERVICE_CALL_RESPONSE calling context
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:
The connector sent this insert request to the application when it received the application-specific business object with a Create verb from the outbound map. This outbound map had a calling context of SERVICE_CALL_REQUEST. When the calling context was SERVICE_CALL_REQUEST, the Cross-Reference transformation could not write a new relationship instance to the relationship table because it did not yet have the application-specific key value that corresponded to the instance ID.
The connector sends this application-specific business object to InterChange Server Express, where it is received by the connector controller.
The inbound map contains a Cross-Reference transformation to create an entry in the relationship table for the new application-specific key.
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
When the calling context is SERVICE_CALL_FAILURE, the map that 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
When the calling context is ACCESS_RESPONSE, the map that 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
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 did not exist in the primary request, the method tries to retrieve that child object's relationship instance ID. If the method cannot find the relationship instance, it just populates the keys of this child object with the CxIgnore value.
For information on defining a Cross-Reference relationship, see "Cross-referencing identity relationships".
If child business objects have a unique key attribute, you can relate these child business objects in a simple identity relationship. The following sections describe the steps for coding this simple identity relationship:
To create a relationship definition for a simple identity relationship between child business objects, perform the following steps:
Expand the child business object and select the key attribute.
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, perform the following steps to code a simple identity relationship:
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".
In the submap, perform the following steps: