A foreign key is an attribute within one business object that contains the key value of another business object. This key value is considered "foreign" to the source business object because it identifies some other business object. To transform a foreign key in a source business object, you must access the relationship table associated with the business object that the foreign key references (the foreign relationship table). From this foreign relationship table, you can obtain the associated key value for the foreign key of the destination business object.
The Mapping API provides the methods in Table 88 to perform foreign key lookups.
Table 88. Function blocks for foreign key lookups
Function block | Description |
---|---|
General/APIs/Identity Relationship/Foreign Key Lookup | Performs a foreign key lookup, failing to find a relationship instance if the foreign key does not exist in the foreign relationship table. |
General/APIs/Identity Relationship/Foreign Key Cross-Reference | Performs a foreign key lookup, adding a new relationship instance in the foreign relationship table if the foreign key does not exist. |
The Java code generated by the Foreign Key Lookup function block performs a lookup in a foreign relationship table for the foreign key of the source business object. This function block takes the following actions:
Determines the participant type of the application-specific participant, which is the application-specific business object. In this business object, verifies that only one key attribute exists. If more than one key attribute exists, the Foreign Key Lookup function block does not know which application-specific key attribute to populate with the application-specific equivalent of the generic business object's foreign key. Therefore, it throws the RelationshipRuntimeException exception.
The Java code generated by the Foreign Key Lookup function block takes these actions on the foreign relationship table regardless of the verb in the source business object.
As with the Foreign Key Lookup function block, the Foreign Key Cross-Reference function block performs a lookup in a foreign relationship table based on the foreign key of the source business object. However, the Foreign Key Cross-Reference function block provides the additional functionality that it can add an entry to the foreign relationship table if the lookup fails. The following sections discuss the behavior of the Foreign Key Cross-Reference function block with each of the calling contexts.
When the calling context is EVENT_DELIVERY, ACCESS_REQUEST, or 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. Therefore, the task for the Foreign Key Cross-Reference function block is to obtain from the foreign relationship table the generic key for a given application-specific key value.
For the EVENT_DELIVERY, ACCESS_REQUEST, and SERVICE_CALL_RESPONSE calling contexts, the Foreign Key Cross-Reference function block takes the following actions:
Determines the participant type of the generic participant, which is the generic business object. In this business object, verifies that only one key attribute exists. If more than one key attribute exists, the Foreign Key Cross-Reference function block does not know which generic key attribute to populate with the generic equivalent of the application-specific business object's foreign key. Therefore, it throws the RelationshipRuntimeException exception.
Table 89. Actions for EVENT_DELIVERY, ACCESS_REQUEST, and SERVICE_CALL_RESPONSE
Verb of application-specific business object | Action performed by the Foreign Key Cross-Reference function block |
---|---|
Create | For the
EVENT_DELIVERY and ACCESS_REQUEST calling
contexts, insert a new relationship entry into the foreign
relationship table for the application-specific business object's
key value.
For the SERVICE_CALL_RESPONSE calling context, 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). For more information on the behavior of the SERVICE_CALL_RESPONSE, see "SERVICE_CALL_RESPONSE calling context". |
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 foreign relationship table for the given application-specific business object's foreign key value. |
If an entry for this foreign key value does not exist, insert a new relationship instance into the foreign relationship table for the application-specific business object's foreign key value. | |
Retrieve | Retrieve the relationship entry from the foreign relationship table for the given application-specific business object's foreign key value |
Figure 118 shows how the Foreign Key Cross-Reference function block accesses the foreign relationship table (for App Obj C) when a calling context is EVENT_DELIVERY, ACCESS_REQUEST, or SERVICE_CALL_RESPONSE and the verb for the application-specific business object (App Obj A) is either Create or Update.
Figure 118. Foreign key lookup for
a create or update 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. For the SERVICE_CALL_REQUEST calling context, the Foreign Key Cross-Reference function block takes the following actions:
Determines the participant type of the application-specific participant, which is the application-specific business object. In this business object, verifies that only one key attribute exists. If more than one key attribute exists, the Foreign Key Cross-Reference function block does not know which application-specific key attribute to populate with the application-specific equivalent of the generic business object's foreign key. Therefore, it throws the RelationshipRuntimeException exception.
The Foreign Key Cross-Reference function block obtains from the foreign 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 Foreign Key Cross-Reference function block does not obtain the application-specific key value for a Create verb.
Table 90 shows the action that the Foreign Key Cross-Reference function block takes on the foreign relationship table, based on the verb of the generic business object.
Table 90. Actions for the SERVICE_CALL_REQUEST calling context and a Foreign Key
Verb of generic business object | Action performed by the Foreign Key Cross-Reference function block |
---|---|
Create | Take no
action.
The method writes a new relationship instance to the foreign relationship table when the calling context is SERVICE_CALL_RESPONSE. For more information, see "EVENT_DELIVERY, ACCESS_REQUEST, and SERVICE_CALL_RESPONSE calling contexts". |
Update Delete Retrieve |
|
As Table 90 shows, when the verb is Create, the Foreign Key Cross-Reference function block does not write a new relationship instance to the relationship table. It does not perform this write operation because it does not yet have the application-specific foreign key value that corresponds to the 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.
When the calling context is ACCESS_RESPONSE, 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 Foreign Key Cross-Reference function block is to obtain from the foreign relationship table the application-specific key for a given generic key value.
For the ACCESS_RESPONSE calling context, the Foreign Key Cross-Reference function block takes the following actions:
Determines the participant type of the application-specific participant, which is the application-specific business object. In this business object, verifies that only one key attribute exists. If more than one key attribute exists, the Foreign Key Cross-Reference function block does not know which application-specific key attribute to populate with the application-specific equivalent of the generic business object's foreign key. Therefore, it throws the RelationshipRuntimeException exception.
The Foreign Key Cross-Reference function block takes these actions on the foreign relationship table regardless of the verb in the generic business object.
Keep the following tips in mind when using the Foreign Key Cross-Reference and Foreign Key Lookup function blocks:
You do not need this check after using the Foreign Key Cross-Reference function block because this function block automatically adds an entry to the foreign relationship table if the application-specific key value does not exist.