Setting the verb

This section contains the following information on how to set the verb of a business object participating in a map:

Note:
For general information about how to set the verb of the destination business object, see "Setting the destination business object verb".

Conditionally setting the destination verb

Usually, you just set the destination verb to the value of the source verb by defining a Move transformation. (For more information on this action, see "Setting the destination business object verb".) However, sometimes the source application sets the business object verb in an unusual manner; for example, the verb is set to Update even though the event is new. As another example, the verb is always set to Retrieve. In the situations like these, the map must resets the destination verb to the one that corresponds to the actual event.

If the source business object's key participates in a relationship, the map can perform a static lookup in the relationship table to determine if the source business object exists. The map can then set the destination verb to either Update or Create based on whether the corresponding entry is found in the table. You perform this static lookup in much the same way as accessing a lookup relationship. Table 82 shows the function block to use for each kind of static lookup.

Table 82. Checking for Existence of the source business object
Type of source business object Map type Function block
Application-specific Inbound General/APIs/Relationship/
Retrieve Instances
Generic Outbound General/APIs/Relationship/
Retrieve Participants

Example of customizing the inbound map

Here is an example of how an inbound map can conditionally set the destination verb based on the result of a lookup:

  1. In the map, define a Custom transformation between the source business object and the destination verb.
  2. In the Activity of this Custom Transformation, perform the following steps. The goal of this activity is to identify the number of instances in the participant of the relationship. If there are no participant instances in the relationship, the destination business object verb should be Create; otherwise, the verb should be Update.
    1. Define the activity, as shown in Figure 114, to identify the number of instances in the relationship participant.

      Figure 114. Identifying the number of instances in the relationship participant

    2. Double-click the Condition function block in the canvas to open it. Select True Action to define the action to take when the condition is true. Define the True Action as shown in Figure 115.

      Figure 115. Defining the True Action

    3. Select the False Action to define the action to take when the number of participant instances is not zero. Define the False Action as shown in Figure 116.

      Figure 116. Defining the False Action

Example of customizing the outbound map

You can use similar steps in the outbound map to perform a static lookup based on the primary key of the generic object. To do that, you need to replace the function block General/APIs Relationship/Retrieve Instances with the function block General/APIs Relationship/Retrieve Participants. Here are the steps:

  1. In the map, define a Custom transformation between the key attribute of the source business object and the destination verb.
  2. In the activity of this Custom transformation, perform the following steps. The goal of this activity is to identify the number of participants of the relationship. If there are no participant instances in the relationship the destination business object verb should be Create; otherwise, the verb should be Update.
    1. Define the activity, as shown in Figure 117, to identify the number of participants in the relationship.

      Figure 117. Identifying the number of participants in the relationship

    2. Follow steps 2b and 2c, described in Example of customizing the inbound map.

Setting the source child verb

When a parent source business object has child business objects, the value of the source child verb is usually the same as that of the parent verb. Therefore, you set the source child object's verb by defining a Move transformation from the parent verb to the child verb. However, if the parent object's verb is Update, the update could be a result of any of the modifications shown in Table 83.

Table 83. Updating a parent business object
Update task Verb in child object
Modifying some non-child attribute i the parent object Update
Modifying some attribute in a child object Update
Adding more child objects Create
Deleting existing child objects Delete

All of the modifications Table 83 are represented by a verb of Update in the parent object. However, not all of these modifications represent an Update to the child object. The value of the source child verb depends on what action was taken on the parent verb. When the child object's key participates in an identity relationship (composite or simple), the source child verb value depends not just on the parent verb but also on the calling context. In such cases, use the Maintain Child Verb function block to handle the setting of the verb of the source child object.

This section provides the following information about using the Maintain Child Verb function block to maintain a source child object verb:

Determining the child verb setting

The Maintain Child Verb function block must ensure that the verb settings of the child objects in the source business object are appropriate given the verb in the parent source object and the calling context. The actions that this method takes are based on the verb in the parent source object and the calling context.

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. The inbound map receives an application-specific business object as input and returns a generic business object as output. For EVENT_DELIEVERY (or ACCESS_REQUEST), there are no special cases to handle when setting the child verbs. Therefore, the maintainChildVerb() method just copies the parent verb to the child verb for all verb values, as Table 84 shows.

Table 84. Actions for the EVENT_DELIVERY and ACCESS_REQUEST calling contexts
Verb of generic business object Action performed by the Maintain Child Verb function block
Create

Delete

Update Retrieve

Set the verbs of all child objects in the source object to the verb in the parent source object. This action overwrites any existing verb in the child object.

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. For SERVICE_CALL_REQUEST, the Java code generated by the Maintain Child Verb function block handles the special case for an Update verb: If the change to the parent object is the creation of new child objects, the Maintain Child Verb function block changes the verb to Create for any child objects that do not currently exist in the relationship tables, as Table 85 shows.

Table 85. Actions for SERVICE_CALL_REQUEST calling context
Verb of generic business object Action performed by the Maintain Child Verb function block
Create Delete Retrieve Set the verbs of all child objects in the source object to the verb in the parent source object. This action overwrites any existing verb in the child object.
Update
  1. Retrieve the relationship instance from the child relationship table for the given generic business object's key value.
  2. Set the verb of the child object based on the success of the table lookup:
    • If a relationship instance for this child object exists, set the verb of the child object to Update.
    • If a relationship instance for this child object does not exist, set the verb of the child object to Create.

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 behavior of the Maintain Child Verb function block is determined by the second-to-last parameter of the method. This parameter is the boolean to_Retrieve flag, whose value indicates whether the application resets or preserves child objects' verbs when processing a collaboration request, as Table 86 shows.

Table 86. Connector behavior
Value of to_Retrieve flag Connector behavior
true Connector sets child object verbs to different value from what they had coming into the application.

For example, if a business object comes to the connector with a parent verb of Update and a child verb of Create, the connector might reset all child object verbs to their parent value after the application completes the operation. In this case, the child verb would be changed to Update.

false Connector preserves child object verbs.

For example, if a business object comes to the connector with a parent verb of Update and a child verb of Create, the connector preserves all child object verbs. In this case, the child verb would still be Create.

Note:
The Java code generated by the Maintain Child Verb function block uses the value of the to_Retrieve parameter only when it processes the SERVICE_CALL_RESPONSE calling context.

If the to_Retrieve argument is true, the Maintain Child Verb function block performs the tasks in Table 87..

Table 87. Actions for the SERVICE_CALL_RESPONSE calling context
Verb of generic business object Action performed by the Maintain Child Verb function block
Create Delete Retrieve Update Set the verbs of all child objects in the source object to the verb in the parent source object. This action overwrites any existing verb in the child object.
  1. Lookup each child object in the child relationship table.
  2. Set the verb of the child object based on the success of the table lookup:
    • If a relationship instance for this child object exists, set the verb of the child object to Update.
    • If a relationship instance for this child object does not exist, set the verb of the child object to Create.

Note:
If you are unsure of the behavior of your application, set the to_Retrieve argument to true. With a true flag value, performance might be affected because the Java code generated by the Maintain Child Verb function block might perform an unnecessary lookup. However, it is usually safer to have an unnecessary lookup than to have an incorrect verb setting in the child object.

Tips for using the Maintain Child Verb function block

The Maintain Child Verb function block maintains the verb of the child objects in the source business object. It can handle child objects that are part of a simple or a composite identity relationship. This function block must ensure that the verb settings are appropriate given the verb in the parent source object and the calling context.

Keep the following tips in mind when using the Maintain Child Verb function block:

Copyright IBM Corp. 1997, 2003