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
FAIL.
- 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 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:
- 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 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:
- 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
FAIL.
- 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.
