Business object verb processing

This section describes the following aspects of processing a business object's verbs:

After-images and deltas

An after-image is the state of a business object after all changes have been made to it. A delta is a business object used in an update operation that contains only key values and the data to be changed. This connector supports only after-images, not business object deltas. When the connector receives a request business object for update, it assumes that the business object represents the desired state of the data after update.

Therefore, when the connector receives a request business object with the Update verb, it changes the current representation of the business object in the Component Interface so that it exactly matches the source business object. To do this, the connector changes simple attribute values and adds or removes child business objects.

For an example of how the connector modifies child business objects, assume that the PSFT_EmergencyContact business object has two additional attributes, one of which represents a single-cardinality child and the other of which represents an array of child business objects. Each child of the array can contain its own array of child business objects.

Figure 8 illustrates the current state of PSFT_EmergencyContact for an employee whose ID is 2345. The ArrayData attribute represents three Records (A, B, and C). The array attribute in two of these records represents two additional Records.

Figure 8. State of data prior to update

Figure 9 illustrates a business object request. This business object contains a new single-cardinality child business object and contains different business objects in its arrays.

Figure 9. Data represented by an update request

To process the update, the connector applies the following changes to the Component Interface:

Because the connector assumes that each request business object it receives represents an afterimage, it is important that each business object sent to the connector for updating contains all valid existing child business objects. Even if none of a child business object's simple attributes have changed, the child business object must be included in the source business object.

There is a way, however, that you can prevent the connector from deleting missing child business objects during an update operation. To instruct the connector to keep child business objects that are not included in the source business object, use the application-specific information for the attribute that represents the child or array of children. To do so, set KeepRelationship to true. For more information, see Application-specific information at the attribute level.

Verb Processing for business object requests

This section outlines the steps the connector takes when creating, retrieving, updating, or deleting a business object that it receives as a request. The connector processes hierarchical business objects recursively; that is, it performs the same steps for each child business object until it has processed all individual business objects.

Business object comparison

At various points in the processing outlined below, the connector compares two business objects to see if they are the same. For example, during an update operation, the connector determines whether a particular business object exists in an array of business objects. To perform the check, the connector compares the business object to each business object within the array. For two business objects to be identical, the following two conditions must be satisfied:

Create operations

When creating a business object, the connector returns a status of either VALCHANGE if the operation was successful (regardless of whether the operation caused changes to the business object), or FAIL if the operation failed.

The connector performs the following steps when creating a hierarchical business object:

  1. Creates a new instance of a Component Interface for the top-level business object.
  2. Recursively inserts each child business object and each array of child business objects into the Component Interface. In other words, the connector creates the child and all child business objects that the child and its children contain.
    Note:
    If the business object definition for an attribute that represents a single-cardinality child business object specifies that the child is required (that is, its Required property evaluates to true), the retrieval must return a row. If it does not return a row, the connector returns an error and stops processing. However, if the child is not required and the attribute is empty, the connector ignores the attribute.
  3. The connector calls the Save() method, which writes and commits the data.

For more information on attribute properties, see Business object attribute properties. For more information on specifying application-specific information, see Application-specific information at the attribute level.

Retrieve operations

When retrieving a business object, the connector returns a status either of VALCHANGE if the operation was successful (regardless of whether the operation caused changes to the business object), or FAIL if the operation failed.

The connector performs the following steps when retrieving a hierarchical business object:

  1. Removes all child business objects from the top-level business object that it received from the integration broker.
  2. Retrieves the Component Interface that corresponds to the top-level business object.

    The connector uses the key values in the source business object to instantiate the Component Interface. The result of the retrieval causes one of the following actions:

    Note:
    A business object can contain attributes that do not correspond to any Component Interface property. During retrieval, the connector does not change such attributes in the top-level business object; they remain set to the values it received. For child business objects, the connector sets such attributes to their default values during retrieval.
  3. Recursively retrieves all Collections of the Component Interface that correspond to business object arrays.

    The connector uses the keys in each parent business object and the unique key of each child to select a data row from the Component Interface instance or Component Interface Collection. For each row returned, the connector performs the following actions:

    1. Creates a new individual business object of the correct type.
    2. Sets all of the current business object's attributes based on the values in the returned row.
    3. Recursively retrieves all of the current business object's children.
    4. Inserts the current business object with all of its children into the appropriate array of the parent.
    Note:
    The connector does not enforce uniqueness when populating an array of business objects. It is the application's responsibility to ensure uniqueness. If the application returns duplicate child business objects, the connector returns duplicate children to the integration broker.
  4. Recursively retrieves the Collections for each of the top-level business object's single-cardinality children. The connector uses the keys in each parent business object and the unique key of each child to select a data row from the Component Interface instance or Component Interface Collection. The connector performs the following:
    1. If the business object's definition specifies that the child is required, the retrieval must return a row. If the child is not required and the retrieval returns no rows, indicating that the child does not exist in the Component Interface, the connector leaves the parent's single-cardinality attribute empty. If the retrieval returns more than one row, the retrieval fails.
    2. Recursively retrieves the Collections for all children contained by the child business object.
    3. Inserts the business object with all of its children into the appropriate attribute in the parent business object.

RetrieveByContent operations

When retrieving a business object, the connector returns a status of VALCHANGE if the operation was successful (regardless of whether the operation caused changes to the business object), FAIL if the operation failed, or MULTIPLE_HITS if the operation returned more than one row.

The connector performs the following steps when retrieving a hierarchical business object:

  1. Removes all child business objects from the top-level business object that it received from the integration broker.
  2. Retrieves the Component Interface that corresponds to the top-level business object.

    The connector uses the values of those attributes that are find keys in the source business object to instantiate the Component Interface. (For more information about specifying application-specific information for find key attributes, see Application-specific information at the attribute level.) The result of the retrieval causes one of the following actions:

    Note:
    A business object can contain attributes that do not correspond to any Component Interface property. During retrieval, the connector does not change such attributes in the top-level business object; they remain set to the values it received. For child business objects, the connector sets such attributes to their default values during retrieval.
  3. Recursively retrieves all Collections of the Component Interface that correspond to business object arrays.

    The connector uses the keys in each parent business object and the unique key of each child to select a data row from the Component Interface instance or Component Interface Collection. For each row returned, the connector performs the following actions:

    1. Creates a new individual business object of the correct type.
    2. Sets all of the current business object's attributes based on the values in the returned row.
    3. Recursively retrieves all of the current business object's children.
    4. Inserts the current business object with all of its children into the appropriate array of the parent.
    Note:
    The connector does not enforce uniqueness when populating an array of business objects. It is the application's responsibility to ensure uniqueness. If the application returns duplicate child business objects, the connector returns duplicate children to the integration broker.
  4. Recursively retrieves the Collections for each of the top-level business object's single-cardinality children. The connector uses the keys in each parent business object and the unique key of each child to select a data row from the Component Interface instance or Component Interface Collection. The connector performs the following:
    1. If the business object's definition specifies that the child is required, the retrieval must return a row. If the child is not required and the retrieval returns no rows, indicating that the child does not exist in the Component Interface, the connector leaves the parent's single-cardinality attribute empty. If the retrieval returns more than one row, the retrieval fails.
    2. Recursively retrieves the Collections for all children contained by the child business object.
    3. Inserts the business object with all of its children into the appropriate attribute in the parent business object.

Update operations

When updating a business object, the connector returns a status of either VALCHANGE if the operation was successful (regardless of whether the operation caused changes to the business object), or FAIL if the operation failed.

The connector performs the following steps when updating a hierarchical business object:

  1. Uses the key values of the source business object to retrieve the corresponding Component Interface instance. The retrieved Component Interface is an accurate representation of the current state of the data in the PeopleSoft application.
  2. Recursively updates all single-cardinality children of the top-level business object.

    If the business object definition requires that an attribute contain a child business object, the child must exist in both the source business object and the retrieved Component Interface. If it does not, the update fails, and the connector returns an error.

    The connector processes the update of single-cardinality child business objects in one of the following ways:

  3. Updates all simple attributes of the retrieved Component Interface except those whose corresponding attribute in the source business object contain the value CxIgnore.
  4. Processes all arrays of the retrieved Component Interface in one of the following ways:
    Important:
    The business process that creates the business object must ensure that multiple-cardinality business objects in the source business object are unique (that is, that an array does not contain two or more copies of the same business object). If the connector receives duplicates of a business object in a source array, it processes the business object twice, with possibly unpredictable results.

Note:
The connector locks data while retrieving it to ensure data integrity.

Delete operations

The connector does not delete a top-level business object. However, it does physically delete a child business object if its top-level business object uses the Update verb, and the child does not exist in the request business object that represents source data.

For more information, see Update operations.

Committing data

Whenever the connector receives a business object for create or update processing, it either saves all changes to the Component Interface or none. The connector never saves subset of data changes.

Copyright IBM Corp. 1997, 2004