When the business object handler obtains a Create verb from the request
business object, it must ensure that a new application entity, whose type is
indicated by the business object definition, is created, as follows:
- For a
flat business object, the Create verb indicates that the specified entity must
be created.
- For a
hierarchical business object, the Create verb indicates that one or more
application entities (to match the entire business object) must be
created.
The business object handler must set all the values in the new application
entities to the attribute values in the request business object. To
ensure that all required attributes in the request business object have values
assigned, you can call the
initAndValidateAttributes() method, which assigns the
attribute's default value to each required attribute that does not have
its value set (when the UseDefaults connector configuration
property is set to true). The
initAndValidateAttributes() method is defined in the
BusinessObject class. Call
initAndValidateAttributes() before performing the Create
operation in the application.
- Note:
- For a table-based application, the entire application entity must be created
in the
application database, usually as a new row to the database table associated
with the business object definition of the request business object.
This section provides the following information to help process a Create
verb:
- Note:
- You can modularize your business object handler so that each supported verb
is handled in a separate C++ method. If you follow this structure, a
Create method handles processing for the Create verb.
The following steps outline the standard processing for a Create
verb:
- Create the application entity corresponding to the top-level business
object.
- Handle the
primary key or keys for the application entity:
- If the application generates its own primary key (or keys), get these key
values for insertion in the top-level business object.
- If the application does not generate its own primary key (or
keys), insert the key values from the request business object into the
appropriate key column (or columns) of the application entity.
- Set
foreign key attributes in any first-level child business objects to the value
of the top-level primary key.
- Recursively create the application entities corresponding to the
first-level child business objects, and continue recursively creating all
child business objects at all subsequent levels in the business object
hierarchy.
In Figure 26, a verb method sets the foreign key attributes (FK) in child
business objects A, B, and C to the value of the top-level primary key
(PK1). The method then recursively sets the foreign key attributes in
child business objects D and E to the value of the primary key (PK3) in their
parent business object, object B.
Figure 26. Creating parent/child relationships

A typical implementation of a Create operation first traverses the
top-level business object and processes the business object's simple
attributes. It gets the values of the attributes from the business
object and generates the application-specific action (such as an API call or
SQL statement) that inserts an entity in the application to represent the
top-level business object. Once this top-level entity is created, the
verb operation takes the following steps:
- Retrieve any primary keys for the entity from the application.
- Use the keys to set the
foreign key attributes in the first-level child business objects to the value
of the parent primary keys.
- Set the verb in each child business object to Create and recursively
create application entities to represent the child business objects.
A recommended approach for creating child business objects is to design a
submethod to recursively create child entities. The submethod might
traverse the business object, looking for attributes of type
OBJECT. If the submethod finds attributes that are objects,
it calls the main Create method to create the child entities.
The way that the main method provides primary key values to the submethod
can vary. For example, the main Create method might pass the parent
business object to the submethod, and the submethod can then retrieve the
primary key from the parent business object to set the foreign key in the
child business object. Alternatively, the main method might traverse
the parent object, find first-level children, set the foreign key attributes
in the child business objects, and then call the submethod on each
child.
In either case, the main Create method and its submethod interact to set
the interdependencies between the parent business object and its first-level
children. Once the foreign keys are set, the operation can:
- Insert new rows into the application.
- Set foreign keys for the next level of child business objects.
- Create the child entities.
- Descend the business object hierarchy, recursively creating child entities
until there are no more child business objects to process.
- Note:
- For an example Create verb method, see Example: Create method for a flat business object.
- Note:
- For a table-based application, the order of the steps for setting the
relationships between a top-level object and its children may vary, depending
on the database schema for the application and on the design of the
application-specific business objects. For example, if foreign keys for
a hierarchical business object are located in the top-level business object,
the verb operation might need to process all child business objects
before processing the top-level business object. Only when
the child entities are inserted into the application database and the primary
keys for these entities are returned can the top-level business object be
processed and inserted into the application database. Therefore, be
sure to consider the structure of data in the application database when you
implement connector verb methods.
The Create operation should return one of the outcome-status values shown
in Table 28.
Table 28. Possible outcome status for C++ Create verb processing
Create condition
| C++ outcome status
|
If the Create operation is successful and the application generates new
key values, the connector:
- fills the business object with the new key values; this business
object is returned to the connector framework through the request business
object parameter.
- returns the "Value Changed" outcome status to indicate that the
connector has changed the business object
|
BON_VALCHANGE
|
If the Create operation is successful and the application does
not generate new key values, the connector can simply return
"Success".
|
BON_SUCCESS
|
If the application entity already exists, the connector can
either of the following actions:
|
|
- Fail the Create operation.
|
BON_FAIL
|
- Return an outcome status that indicates the application entity already
exists.
|
BON_VALDUPES
|
If the Create operation fails, the verb method:
- fills a return-status descriptor with information on the failure
- returns the "Fail" outcome status
|
BON_FAIL
|
- Note:
- When the connector framework receives the BON_VALCHANGE outcome status, it
includes a business object in its response to InterChange Server. For
more information, see Sending the verb-processing response.
