This section describes the following aspects of processing a business
object's verbs:
An afterimage 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 afterimages, 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 9 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 9. State of data prior to update

Figure 10 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 10. Data represented by an update request

To process the update, the connector applies the following changes to the
Component Interface:
- Updates the simple attributes in the PSFT_EmergencyContact and
the PSFT_EmergencyPhone business objects.
- Creates the PSFT_SingleData business object.
- Updates the simple attributes in the child business objects A, B, F and
G.
- Deletes the child business objects C, D and E.
- Creates the child business objects H, I and J.
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".
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.
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:
- The type of the business objects being compared must be the same.
For example, a PSFT_Customer business object is never considered
identical to a PSFT_Contact business object even if all of their
attributes are exactly the same.
- All corresponding key attributes in the two business objects must contain
identical values. If a key attribute is set to CxIgnore in
both business objects, the connector considers them identical. However,
if a key attribute is set to CxIgnore in one business object but
not in the other, the business objects are not identical.
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:
- Creates a new instance of a Component Interface for the top-level business
object.
- Uses PeopleSoft's
SetFieldName(value)
method to populate properties in the Component Interface with values from
attributes in the business object.
- Important:
- If the UID parameter of a key attribute's application-specific
information evaluates to false, the business process that creates
the business object must provide a new unique ID value for the
attribute. If the business object does not have the required value, the
connector logs an error.
If the UID parameter of a key attribute's
application-specific information evaluates to true, the application
is responsible for generating a unique ID. In this case, the
attribute's value or the Default Value property must contain
the string NEXT. In other words, if the business process
that creates the business object does not populate its value as
NEXT, this value must be specified in the attribute's
Default Value property. If the business object uses the
Default Value property to provide the String NEXT, the
connector's UseDefaults property must evaluate to
true. For more information, see "UseDefaults".
If a unique identifier is not provided for the attribute's value, and
the string NEXT is not specified in the Default Value
property, the application logs a duplicate-key error.
- Verifies that all Required attributes contain a value, and throws an error
if such a value is missing. For more information on Required
attributes, see "Required property".
- 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.
- The connector calls the Save() method, which writes and commits the
data.
- If the connector is generating the unique ID, the generation occurs as
this method executes.
- If the application is generating the unique ID, the connector retrieves
the key values set by the application after this method executes.
- Note:
- If InterChange Server (ICS) is the integration broker, the ID must be
delivered synchronously because ICS requires the ID to cross-reference the
business object.
- If setInteractiveMode is defined as false in the
business object's application-specific information, all PeopleCode
editing occurs at this point. Any PeopleCode errors are published to
the PSMessage collection queue.
- If an instance of the Component Interface already exists with the same key
values, the application returns a duplicate-key error, and the connector sends
the FAIL return code.
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".
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:
- Removes all child business objects from the top-level business object that
it received from the integration broker.
- 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:
- If it finds a Component Interface instance, the connector continues
processing.
- If it does not find a Component Interface instance, indicating that the
top-level business object does not have a corresponding Component Interface in
the application, the connector returns BO_DOES_NOT_EXIST.
- If it finds multiple Component Interface instances, the connector returns
MULTIPLE_HITS.
- 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.
- 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:
- Creates a new individual business object of the correct type.
- Sets all of the current business object's attributes based on the
values in the returned row.
- Recursively retrieves all of the current business object's
children.
- 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.
- 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:
- 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.
- Recursively retrieves the Collections for all children contained by the
child business object.
- Inserts the business object with all of its children into the appropriate
attribute in the parent business object.
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:
- 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.
- If the retrieval fails, indicating that the top-level business object does
not exist in the application, the connector returns
BO_DOES_NOT_EXIST.
- If the retrieval succeeds, the connector compares the retrieved Component
Interface to the source business object to determine which child business
objects require changes in the Component Interface. The connector does
not, however, compare values in the source business object's simple
attributes to those in the retrieved Component Interface; the connector
updates the value of all simple attributes.
- 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:
- If the child is present in both the source business object and the
retrieved Component Interface, the connector recursively updates it in the
Component Interface.
- Note:
- The source business object and the retrieved Component Interface must
match. If the two hierarchical objects contain the same
single-cardinality ownership children in different order, the connector
returns an error and stops processing.
- If the child is present in the source business object but not in the
retrieved Component Interface, the connector recursively creates it in the
Component Interface.
- Important:
- If the UID parameter of a key attribute's application-specific
information evaluates to false, the business process that creates
the business object must provide a new unique ID value for the
attribute. If the business object does not have the required value, the
connector logs an error.
If the UID parameter of a key attribute's
application-specific information evaluates to true, the application
is responsible for generating a unique ID. In this case, the
attribute's value or the Default Value property must contain
the string NEXT. In other words, if the business process
that creates the business object does not populate its value as
NEXT, this value must be specified in the attribute's
Default Value property. If the business object uses the
Default Value property to provide the String NEXT, the
connector's UseDefaults property must evaluate to
true. For more information, see "UseDefaults".
If a unique identifier is not provided for the attribute's value, and
the string NEXT is not specified in the Default Value
property, the application logs a duplicate-key error.
- If the child is present in the retrieved Component Interface but not in
the source business object, the connector recursively deletes it from the
Component Interface. However, if the KeepRelationship
parameter of the parent's application-specific information evaluates to
true, the connector preserves the child business object.
When deleting child business objects during an Update operation, the
connector uses PeopleSoft's deleteItem() method to delete the
corresponding Collection from the Component Interface instance. The
connector physically or logically deletes only Collections that are at level 1
or higher.
For more information on specifying application-specific information, see "Application-specific information at the attribute level".
- Updates all simple attributes of the retrieved Component Interface except
those whose corresponding attribute in the source business object contain the
value CxIgnore.
- Processes all arrays of the retrieved Component Interface in one of the
following ways:
- If a child exists in both the source business object's array and the
retrieved Component Interface's array, the connector recursively updates
it in the Component Interface.
- If a child exists in the source array but not in the retrieved Component
Interface's array, the connector recursively creates it in the Component
Interface.
- If the child exists in the retrieved Component Interface's array but
not in the source array, the connector recursively deletes it from the
Component Interface.
- 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.
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".
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.
