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