This section outlines the steps the connector takes when creating,
retrieving, updating, or deleting a business object that it receives from an
integration broker. 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.
- Note:
- A top-level business object that is a wrapper supports the create, retrieve,
update and delete verbs. The only difference in processing a wrapper
object is that the wrapper object is not processed, only the objects that it
contains are processed.
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 Customer business object is never considered identical to a
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 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 creating a hierarchical
business object:
- Recursively inserts each single-cardinality child business object
contained with ownership into the database. In other words, the
connector creates the child and all child business objects that the child and
its children contain.
If the business object definition specifies that an attribute represents a
child business object with single cardinality and that attribute is empty, the
connector ignores the attribute. However, if the business object
definition requires that attribute to represent a child and it does not, the
connector returns an error and stops processing.
- Processes each single-cardinality child business object contained without
ownership as follows:
- Recursively attempts to retrieve the child from the database using the key
values passed in by the integration broker.
- If the retrieve is unsuccessful, indicating that the child does not
currently exist in the database, the connector returns an error and stops
processing. If the retrieve is successful, the connector recursively
updates the child business object.
- Note:
- For this approach to work correctly when the child business object already
exists in the application database, ensure that primary key attributes in
child business objects are cross-referenced correctly on create
operations. If the child business object does not already exist in the
application database, set the primary key attributes to
CxBlank.
- Inserts the top-level business object in the database as follows:
- Sets each of its foreign-key values to the primary-key values of the
corresponding child business object represented with single
cardinality. Because values in child business objects can be set by
database sequences or counters or by the database itself during the creation
of the child, this step ensures that the foreign-key values in the parent are
correct before the connector inserts the parent in the database.
- Generates a new unique ID value for each attribute that is set
automatically by the database. The name of the database sequence or
counter is stored in the attribute's application-specific
information. If an attribute has an associated database sequence or
counter, the value generated by the connector overwrites any value passed in
by the integration broker. For more information on specifying a
database sequence or counter, see UID=AUTO in Application-specific information for simple attributes.
- Copies the value of an attribute to the value of another attribute as
specified by the CA (CopyAttribute) parameter of the
attribute's application-specific information. For more information
on using the CA parameter, see CA=set_attr_name in Application-specific information for simple attributes.
- Inserts the top-level business object into the database.
- Note:
- A top-level business object that is a wrapper will not be inserted into the
database.
- Processes each of its single-cardinality child business objects that
stores the parent/child relationship in the child, as follows:
- Sets the foreign-key values in the child to reference the value in the
corresponding primary-key attributes in the parent. Because the
parent's primary-key values may have been generated during the creation of
the parent, this ensures that the foreign-key values in each child are correct
before the connector inserts the child into the database.
- Inserts the child into the database.
- Processes each of its multiple-cardinality child business objects, as
follows:
- Sets the foreign-key values in each child to reference the value in the
corresponding primary-key attributes in the parent. Because the
parent's primary-key values may have been generated during the creation of
the parent, this ensures that the foreign-key values in each child are correct
before the connector inserts the child into the database.
- Inserts each of its multiple-cardinality child business objects into the
database.
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 top-level business object from the database.
- If the retrieval returns 1 row, the connector continues processing.
- If the retrieval returns no rows, indicating that the top-level business
object does not exist in the database, the connector returns
BO_DOES_NOT_EXIST.
- If the retrieval returns more than one row, the connector returns
FAIL.
- Note:
- A business object can have attributes that do not correspond to any database
column, such as placeholder attributes. During retrieval, the connector
does not change such attributes in the top-level business object; they
remain set to the values received from the integration broker. In child
business objects, the connector sets such attributes to their default values
during retrieval.
- Note:
- A top-level business object that is a wrapper must contain any attribute
values from the objects at the level immediately below the wrapper object,
which would be necessary to retrieve the objects, including keys and
placeholder attributes. The wrapper object must have all keys and
placeholder attributes populated. Simple attributes in the wrapper
object that will be used as foreign keys in the objects one level below the
wrapper should be marked as keys in the wrapper object.
- Recursively retrieves all multiple-cardinality child business
objects.
- Note:
- The connector does not enforce uniqueness when populating an array of
business objects. It is the database's responsibility to ensure
uniqueness. If the database returns duplicate child business objects,
the connector returns duplicate children.
- Recursively retrieves each of the single-cardinality children regardless
of whether the child business object is contained with or without
ownership.
- Note:
- All single cardinality child business objects are processed based on
occurrence in the business object and before the parent business object is
processed. Child object ownership and non-ownership do not determine
the processing sequence, but do determine the type of processing.
A RetrieveByContent verb is applicable only for the top-level business
object, because the connector performs a retrieval based on attributes only in
the top-level business object.
If a top-level business object uses the RetrieveByContent verb, all of the
attributes (including non-key attributes) that are not null are used as
retrieval criteria.
If more than one row is returned, the connector uses the first row as the
result row and returns MULTIPLE_HITS.
- Note:
- A RetrieveByContent verb is not applicable for a top-level business object
that is a wrapper.
When updating 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. When working with an Oracle database, the
connector locks data while retrieving it to ensure data integrity.
The connector performs the following steps when updating a hierarchical
business object:
- Uses the primary-key values of the source business object to retrieve the
corresponding entity from the database. The retrieved business object
is an accurate representation of the current state of the data in the
database.
- If the retrieval fails, indicating that the top-level business object does
not exist in the database, the connector returns BO_DOES_NOT_EXIST
and the update fails.
- Note:
- A top-level business object that is a wrapper does not have to exist in the
database. However, it must contain any attribute values from the
objects at the level immediately below the wrapper object, which would be
necessary to retrieve the objects including keys and placeholder
attributes. The wrapper object must have all keys and placeholder
attributes populated. Simple attributes in the wrapper object that will
be used as foreign keys in the objects one level below the wrapper should be
marked as keys in the wrapper object.
- If the retrieval succeeds, the connector compares the retrieved business
object to the source business object to determine which child business objects
require changes in the database. The connector does not, however,
compare values in the source business object's simple attributes to those
in the retrieved business object. The connector updates the value of
all non-key simple attributes.
If all the simple attributes in the top-level business object represent
keys, the connector cannot generate an update query for the top-level business
object. In this case, the connector logs a warning and continues to
step 2.
- Recursively updates all single-cardinality children of the top-level
business object.
If the business object definition requires that an attribute represent a
child business object, the child must exist in both the source business object
and the retrieved business object. If it does not, the update fails,
and the connector returns an error.
The connector handles single-cardinality children contained with ownership
in one of the following ways:
- If the child is present in both the source and the retrieved business
objects, instead of updating the already existing child in the database, the
connector deletes the existing child and creates the new child.
- If the child is present in the source business object but not in the
retrieved business object, the connector recursively creates it in the
database.
- If the child is present in the retrieved business object but not in the
source business object, the connector recursively deletes it from the
database. The type of delete, physical or logical, depends on the value
of its ChildUpdatePhyDelete property.
For single-cardinality children contained without ownership, the connector
attempts to retrieve every child from the database that is present in the
source business object. If it successfully retrieves the child, the
connector populates the child business object but does not update it, as
single cardinality children contained without ownership are never modified by
the connector.
- For single-cardinality child business objects that store the relationship
in the parent, sets each foreign-key value in the parent to the value of the
primary key in the corresponding single-cardinality child business
object. This step is necessary because single-cardinality children may
have been added to the database during previous steps, resulting in the
generation of new unique IDs.
- Updates all simple attributes of the retrieved business object except
those whose corresponding attribute in the source business object contain the
value CxIgnore.
Because the business object being updated must be unique, the connector
verifies that only one row is processed as a result. It returns an
error if more than one row is returned.
- Sets all foreign-key values in each child that stores the parent/child
relationship in the child (both multiple-cardinality and single-cardinality)
to the primary-key value of its corresponding parent business object.
(When InterChange Server Express is used as the integration broker, these
values have typically been cross-referenced during data mapping.)
However, this step is important to ensure that the foreign-key values of new
children that store the relationship in the child are correct before the
connector updates those children.
- Processes each multiple-cardinality child of the retrieved business object
in one of the following ways:
- If the child exists in both the source and the retrieved business
objects' arrays, the connector recursively updates it in the
database.
- If the child exists in the source array but not in the retrieved business
object's array, the connector recursively creates it in the
database.
- If the child exists in the retrieved business object's array but not
in the source array, the connector recursively deletes it from the database
unless the application-specific information for the attribute that represents
the child in the parent has KEEP_RELATIONSHIP set to
true. In this case, the connector does not delete the child
from the database. For more information, see Specifying an attribute's foreign key. The type of delete, physical or logical, depends on
the value of its ChildUpdatePhyDelete property.
- Note:
- The integration broker must ensure that business objects contained with
multiple cardinality 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.
When deleting a business object, the connector returns a status of
SUCCESS if the operation was successful or FAIL if the
operation failed. If the business object does not exist, the connector
throws a warning.
The connector supports logical and physical deletes, depending on the SCN
(Status Column Name) value in the object's application-specific
information. If the SCN value is defined, the connector performs a
logical delete. If the SCN value is not defined, the connector performs
a physical delete.
The connector performs the following steps when physically deleting a
hierarchical business object:
- Recursively deletes all single-cardinality child business objects
contained with ownership and recursively deletes all multiple-cardinality
child business objects.
- Deletes the top-level business object.
- Note:
- A top-level business object that is a wrapper does not have a corresponding
database table, hence it will not be deleted from the database. Any
simple attribute values for a wrapper will be ignored.
When an integration broker sends a hierarchical business object that uses
the Update verb for the top-level business object and the Delete verb for
child business objects, the connector assumes that the business object exactly
matches the current database representation of that data. It is the
integration broker's responsibility to ensure that this is the
case. A problem occurs if the integration broker sends a business
object that does not fully represent the business object to be deleted.
For example, if the source business object contains fewer child business
objects than the object in the database, the connector does not delete the
missing business objects from the database. Alternatively, if the
source business object contains a child business object that does not exist in
the database, a warning is displayed and the connector continues
processing.
For example, Figure 5 illustrates a delete request that the connector processes
successfully. However, the connector does not delete child D from the
database, because it does not exist in the business object it received.
This example deletion results in a dangling business object remaining in the
database.
Figure 5. Business object deletion with hanging child

Alternatively, Figure 6 illustrates a delete request in which the source has more
child objects than are present in the database. Because the source
business object contains child C and because child C does not exist in the
database, the connector displays a warning and continues processing.
Figure 6. Deletion of child business object nonexistent in application database

When logically deleting a business object, the connector performs the
following steps:
- Issues an UPDATE that sets the business object's status
attribute to the value specified by the business object's
application-specific information. The connector ensures that only one
database row is updated as a result, and it returns an error if this is not
the case.
- Recursively logically deletes all single-cardinality children contained
with ownership and all multiple-cardinality children. The connector
does not delete single-cardinality children contained without
ownership. It also does not delete any child not represented in the
source business object.
