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:
- For a flat
business object, the Update verb indicates that the data in the
specified entity must be modified as necessary until the application
entity exactly matches the request business object.
- For a hierarchical
business object, the Update verb indicates that updates the application
entity must be updated to match the entire business object hierarchy.
To do this, the connector might need to create, update, and delete
application entities:
- If child entities exist in the application, they are modified
as needed.
- Any child business objects contained in the hierarchical business
object that do not have corresponding entities
in the application are added to the application.
- Any child entities that exist in the application but are not contained
in the business object are deleted from the application.
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:
- 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.
-
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:
- For a flat business object, retrieve the single application
entity.
- For a hierarchical business object, use the Retrieve operation
to descend into the application business object, expanding all paths
in the business object hierarchy.
- 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.
- Update the simple attributes in the application entity to correspond
to the top-level source business object.
- 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:
- If a child business object is present in both the response
business object and the request business object, recursively update the
child by performing the Update operation.
- If a child business object is present in the request business
object but not in the response business
object, recursively create the child by performing the Create operation.
- If a child business object is not present
in the request business object but is present in the response business
object, recursively delete the child using either the Delete operation
(physical) or a logical delete, depending on the functionality of
the connector and the application. For more information on logical
deletes, see Implications of business objects representing logical Delete
events.
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:
- Update any columns in Customer table that have updated values in the corresponding simple
attributes of the Customer business object.
- Update the rows in the Address table that correspond to Address objects A and B. Update
the columns in each of these rows with any new values from the corresponding
simple attributes in the appropriate Address object. In this case,
the Street column has changed for the Denver and Altos offices.
- Delete the row in the Address table that corresponds to the Akron address.
- Update the Contact column of the CustomerProfile table to the value of the corresponding simple attribute
in the CustProfile object A business object.
- Create a row in the Phone table with column values from the simple attributes of the
Phone object A business object. Make sure that the CustID column of this new row is created with the foreign-key value
that identifies the appropriate Customer row (22).
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:
- Events that represent the deletion of data in the source application should
be sent as application-specific business objects with the Delete
verb. Similarly, maps on the source application side should set
the verb of generic business objects to Delete.
- On the destination side, maps for connectors supporting logical
delete applications can transform Delete verbs in generic business
objects to Update verbs in application-specific business objects.
Business object attributes representing entity status values can
be set to the inactive status.
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:
- Implement mapping to examine the status of child business objects.
If the status of a particular child business object is inactive,
the business object can be removed in mapping.
- Implement the Update operation to determine whether an update
operation is actually a delete operation. In a logical delete source
application, an entity may be marked as active or inactive by a
status value. In the source's application-specific business
objects, the status value is usually an attribute. Although entities in
an application that supports physical delete might not include status information,
you can extend your application-specific business objects to include status
information.
- Extend a business object by adding an additional status attribute
or by overloading an existing attribute with a status value. When
the Update operation receives a request, it can check the status
attribute. If it is set to the inactive value, the operation is
really a delete. The Update operation can then set the business object
verb to Delete and call the Delete operation to handle deleted child business
objects.
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
