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 CWConnectorUtil 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 Java 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 28,, 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 28. 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 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
35..
Table 35. Possible outcome
status for Java Create verb processing
Create
condition |
Java 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
|
VALCHANGE
|
If the Create
operation is successful and the application does not
generate new key values, the connector can simply return
"Success". |
SUCCEED
|
If the
application entity already exists, the connector can either
of the following actions: |
|
- Fail the Create operation.
|
FAIL
|
- Return an outcome status that indicates the application entity
already exists.
|
VALDUPES
|
If the Create
operation fails, the verb operation:
- fills a return-status descriptor with information on the
failure
- returns the "Fail" outcome status
|
FAIL
|
- Note:
- When the connector framework receives the VALCHANGE outcome
status, it includes a business object in its response to
InterChange Server. For more information, see Sending the verb-processing
response."Sending the verb-processing response" on page
179.
