Handling the Create verb

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:

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.

Standard processing for a Create verb

The following steps outline the standard processing for a Create verb:

  1. Create the application entity corresponding to the top-level business object.
  2. Handle the primary key or keys for the application entity:
  3. Set foreign key attributes in any first-level child business objects to the value of the top-level primary key.
  4. 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


Implementation of a Create verb operation

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:

  1. Retrieve any primary keys for the entity from the application.
  2. Use the keys to set the foreign key attributes in the first-level child business objects to the value of the parent primary keys.
  3. 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:

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.

Outcome status for Create verb processing

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.

Copyright IBM Corp. 1997, 2003