Handling the Update verb

When the business object handler obtains an Update verb from the request business object, it must ensure that an existing application entity, whose type is indicated by the business object definition, is updated, as follows:

Note:
For a table-based application, the entire application entity must be updated in the application database, usually as a new row to the database table associated with the business object definition of the request business object.

This section provides the following information to help process an Update verb:

Note:
You can modularize your business object handler so that each supported verb is handled in a separate method. If you follow this structure, an Update method handles processing for the Update verb.

Standard processing for an Update verb

The following steps outline the standard processing for an Update verb:

  1. Create a new business object of the same type as the request business object. This new business object is the response business object, which will hold the retrieved copy of the request business object.
  2. Retrieve a copy of the request business object from the application.

    Recursively retrieve the data for the entire entity from the application using the primary keys from the request business object:

  3. Place the retrieved data in the response business object. This response business object is now a representation of the current state of the entity in the application.

    The Update operation can now compare the two hierarchical business objects and update the application entity appropriately.

  4. Update the simple attributes in the application entity to correspond to the top-level source business object.
  5. Compare the response business object (created in step 2) with the request business object. Perform this comparison down to the lowest level of the business object hierarchy.

    Recursively update the children of the top-level business object following these rules:

    Note:
    Only the existence or non-existence of the child objects are compared, not the attributes of the child business objects.

If the connector's application supports logical delete, the connector recursively retrieves the complete business object hierarchy; then the Update operation sets status attributes and recursively updates the status of the children.

Note:
The Update operation should fail if an application entity does not exist for any foreign key (Foreign Key is set to true) referenced in the request business object. The connector should verify that the foreign key is a valid key (it references an existing application entity). If the foreign key is invalid, the Update operation should return . A foreign key is assumed to be present in the application, and the connector should never try to create an application object marked as a foreign key.

Figure 30 shows a set of associated application entities that represent a customer in the application database. The entities contain customer, address, phone, and customer profile data. Note that the sample customer, Acme Construction, has no phone number in the database.

Figure 30. Customer entities before Update request

Assume that an integration broker sends an update request that consists of the request business object as shown in Figure 31..

Figure 31. Customer request business object for an Update

This request business object indicates that the Acme Construction customer has undergone the changes listed in Table 25..

Table 25. Updates to Acme Construction in the Request business object
Update made to Acme Construction Representation in request business object
Acquired a new phone number The child business object for the PhoneArray attribute (Phone object A) has a Create verb.
Moved to new offices in Denver and Altos Two child business objects (Address objects A and B) exist in the AddressArray attribute, each with an Update verb.
Closed the office in Akron No child business object exists in the AddressArray attribute for the Akron address.
Changed the name of the contact person The child business object for the CustProfileArray attribute (CustProfile object A) has an Update verb.

Your connector's task is to keep the application database for this destination application synchronized with the source application. Therefore, to respond to this request, the connector would need to perform the following tasks as part of its Update operation:

Figure 32 shows the set of associated application entities that represent a customer after the Update operation has completed.

Figure 32. Customer entities after Update request

Implications of business objects representing logical Delete events

If your application supports physical delete, but an integration broker sends requests from a source application that supports only logical delete, you might need to handle a business object that represents a logical delete request. Connectors for applications that perform logical delete operations, where an entity is marked as deleted by updating a status value, should handle logical deletes in the Update method. A system view of this implementation is as follows:

In this way, a connector representing a logical delete application receives an application-specific business object with an Update verb and the status value marked appropriately.

For example, assume that a source application entity has been updated to look like the business object representation in Figure 33.. Components in the source application entity have been updated, created, and deleted.

Figure 33. Updated entity in the source application

If the source application connector has implemented event notification as recommended in deleted child business objects are not present in the business object hierarchy, and the business object simply contains the updated and new child business objects.

An example of a business object representing an Update request might look like Figure 34.. In this figure, the parent object is set to update, and all entities that have been deleted are no longer present in the business object hierarchy.

Figure 34. Update request business object from a physical-delete connector

In this case, the connector compares the source and destination business objects and deletes the entities that are not present in the source business object.

However, if the source application supports logical delete, the source connector might send a business object with deletes tagged as updates and status attribute values set to an inactive value. This business object might look like Figure 35,, where updates that are delete operations are identified by "[D]".

Figure 35. Update request business object from a logical-delete connector

There are several ways to handle a source business object that represents a logical delete request:

Outcome status for Update verb processing

The Update operation should return one of the outcome-status values shown in .

Note:
When the connector framework receives the outcome status, it includes a business object in its response to InterChange Server. For more information, see

Copyright IBM Corp. 1997, 2004