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 C++ method. If you follow this structure, an
Update method handles processing for the 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
BON_FAIL. 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 32 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 32. 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 33..
Figure 33. Customer request business object for an Update

This request business object indicates that the Acme Construction customer
has undergone the changes listed in Table 31..
Table 31. 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 34 shows the set of associated application entities that
represent a customer after the Update operation has completed.
Figure 34. Customer entities after Update request

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 35.. Components in the source application entity
have been updated, created, and deleted.
Figure 35. Updated entity in the source application

If the source application connector has implemented event notification as
recommended in Event notification, 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 36.. 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 36. 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 37,, where updates that are delete operations are identified by
"[D]".
Figure 37. 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.
The Update operation should return one of the outcome-status values shown
in Table 32.
Table 32. Possible outcome status for C++ Update verb processing
Update condition
| C++ outcome status
|
If the application entity exists, the Update operation:
- modifies the data in the application entity
- returns a "Success" outcome status
|
BON_SUCCESS
|
If a row or entity does not exist, the Update operation:
- creates the application entity
- returns the "Value Changed" outcome status to indicate that the
connector has changed the business object
|
BON_VALCHANGE
|
If the Update operation is unable to create the application entity,
it:
- fills a return-status descriptor with information about the cause of the
update error
- returns a "Fail" outcome status
|
BON_FAIL
|
If any object identified as a foreign key is missing from the
application, the Update operation:
- fills a return-status descriptor with information about the cause of the
update error
- returns a "Fail" outcome status
|
BON_FAIL
|
- Note:
- When the connector framework receives the BON_VALCHANGE outcome status, it
includes a business object in its response to InterChange Server. For
more information, see Sending the verb-processing response.
