Business object application-specific information

Application-specific information in business object definitions provides the connector with application-dependent instructions on how to process business objects. This meta-data is used with a business object's attribute properties and structure. When you create Portal Infranet application-specific business objects, you must make sure that the application-specific information in the business object definition matches the syntax that the connector expects.

This section provides information on the object, attribute, and verb application-specific information format for business objects for Portal.

Business object application-specific information

At the business object level, application-specific information describes the Infranet entity as follows:

For example, the Portal_Account business object specifies the CN=/account storable class for the object level application-specific information, and the Portal_BillInfo child business object specifies the FN=PIN_FLD_BILLINFO field for the object level application-specific information.

Attribute-level application-specific information

At the attribute level, application-specific information is used to prepare the flist structure that is used for executing a particular opcode. The application-specific information is a name-value pair list. This structure allows you to remove constraints previously imposed by the use of utility business objects, which are no longer required to define the structure of an flist for an opcode. The format of the application-specific information for an attribute is as follows:

FN=FIN_FLD_POID;Create=true;Update=false;Delete=true; Retrieve=true;CreateT=;UpdateT=PIN_FL_NAMEINFO; DeleteT=;RetrieveT=;O=false;CreateO=false;UpdateO=true; DeleteO=false;RetrieveO=false;ParentAtt=;Alone=false

Converting old business objects to new business objects

The above format for attribute-level application-specific information is supported for backward compatibility in connector version 4.0.x. However, in future releases, backward compatibility will not be supported, and you must use PortalODA to convert old business object definitions to new business object definitions.

To use PortalODA to convert old business object definitions to new business object definitions, do the following:

  1. Mark the foreign key fields in the child business objects which link the child business object to the parent business object. The application-specific information contains a tag called ParentAtt. Set the value for this tag to the name of the attribute from the parent business object which has to be used for the foreign key.
  2. If necessary, mark attributes of type "object" with a specific verb tag. Refer to Table 3 for CreatT, UpdateT, DeleteT, and RetrieveT.

Table 3 describes the format of the application-specific information for an attribute:

Table 6. Application-specific information for an attribute

Name Description Possible value Default value
FN Field name representing the field name in Infranet

Create Identifies whether the attribute is part of the flist for the Create verb true or false false
Update Identifies whether the attribute is part of the flist for the Update verb true or false false
Delete Identifies whether the attribute is part of the flist for the Delete verb true or false false
Retrieve Identifies whether the attribute is part of the flist for the Retrieve verb true or false false
CreateT Infranet field name that acts as a container for the attribute in the preparation of the flist for the Create verb
null
UpdateT Infranet field name that acts as a container for the attribute in the preparation of the flist for the Update verb
null
DeleteT Infranet field name that acts as a container for the attribute in the preparation of the flist for the Delete verb
null
RetrieveT Infranet field name that acts as a container for the attribute in the preparation of the flist for the Retrieve verb
null
O Identifies whether the attribute has to be updated in the response business object true or false false
CreateO Identifies the Infranet field name that has the field representing the value for the attribute used to update the response business object for Create verb processing. For example, if the FN=PIN_FLD_POID and CreateO=PIN_FLD_NAMEINFO, then the connector looks for the field PIN_FLD_POID, and the value for this field is populated in the response business object for this attribute.

UpdateO Identifies the Infranet field name that has the field representing the value for the attribute used to update the response business object for Update verb processing.

DeleteO Identifies the Infranet field name that has the field representing the value for the attribute used to delete the response business object for Delete verb processing.

RetrieveO Identifies the Infranet field name that has the field representing the value for the attribute used to retrieve the response business object for Retrieve verb processing.

ParentAtt This field is used by a child business object to define the attribute in the parent business object that is used to populate the keys fields. These fields have to be marked as Foreign Key fields in the child business object.
NULL
Alone This field is used by a child business object to represent that the child business object should be executed separately and not as part of the parent business object. true or false false

Figure 10 shows the Portal_Account business object and illustrates application-specific information for the business objects and attributes.
Application-specific information for business object and attributes

Figure 10. Application-specific information for business object and attributes

Verb application-specific information format

The verb level application-specific information for business objects for Portal Infranet must specify a unique Infranet opcode for the action that the business object and verb will perform.

The opcode passes data between the Infranet application and its database and performs operations on storable objects. Each action on an Infranet object has a specific opcode.

Opcodes pass Infranet storable objects in the form of flists, which are lists of field name and value pairs. Each opcode has a specific input and output flist. The connector must convert a business object request into the input flist required by the opcode. When performing a business object request, the connector follows these basic steps:

  1. Builds an input flist using the values in the business object instance and the information in the business object definition.
  2. Executes the Portal Infranet opcode with the input flist as an argument.
  3. The opcode returns an output flist, and the connector updates the business object with the information in the output flist.

The verb application-specific information and, in some cases, additional utility business objects enable the connector to generate the appropriate flists for each opcode. A utility business object enables the connector to build the correct input flist or to properly update the business object with the output flist. Utility business objects are provided as part of the business object definition for the top-level business object. The new definition of attribute-level application-specific information makes the utility business objects redundant. The feature of utility business objects is being supported in connector version 4.0.x for backward compatibility but would be removed from future releases.

Syntax of verb application-specific information

The required syntax of verb application-specific information is as follows:

<opcode>['#'<flag>][';'transaction enabled][';'<input_flist_model>][';'<output_flist_model>]

where:

opcode Any Infranet opcode without PCM_OP_ at the beginning of the name, or opcode can be the keyword ERROR. The keyword ERROR indicates an Infranet constraint. The connector raises an error if the operation occurs. This might indicate that an operation cannot occur at a child level. For example a Portal_BillInfo business object cannot be deleted alone; it must be deleted with its parent object.
flag An optional argument to an opcode. For information on opcode flags, see the Portal Infranet documentation.
transaction enabled Some of the Opcodes in Portal Infranet maintain their own transaction due to the critical nature of Opcode functionality. This flag is used to provide that information to the Portal Infranet connector. The value "true" indicates that the Opcode maintains its own transaction. The default value used by the Portal Infranet connector for this property is "false."
input_flist_model Either the name of a utility business object for the input flist and, optionally, some parameters, or a keyword. The syntax is:<input_flist_model>[#<parameter>] The possible keywords are NotNull, NORMAL or OnlyPoid. These keywords are defined as follows:
  • NORMAL indicates that the current business object is the model; in other words, the connector can convert directly from the current business object to the input flist.
  • OnlyPoid indicates that the current opcode needs only the POID from the business object. The connector can then simplify its processing.
  • NotNull indicates that this object should not be deleted by setting the array to Null.

See "Connector utility business objects" for information on utility business objects.

output_flist_model Either the name of a utility business object for the output flist and, optionally, some parameters, or a keyword. The syntax is:<output_flist_model>[#<parameter>] The possible keywords are NoRewrite and Flat. These keywords are defined as follows:
  • NoRewrite indicates that the output flist returned by the opcode must not be used to overwrite the business object.
  • Flat indicates that the connector should get the attributes for a child business object from the top-level business object.

See "Connector utility business objects" for information on utility business objects.

Rules of opcode application

One or more opcodes may exist at the storable class level for Create, Update, and Delete operations. However, the connector supports only one opcode for each verb. Therefore, for each verb, you must choose the opcode that is best suited to the business object and verb operation.

Different opcodes may be required at the parent and child levels. When an opcode exists for a child object, Portal Infranet advises using it rather than using the parent opcode. If a specific opcode is needed to update a subcomponent in Infranet, you must create a new application-specific business object for this child and specify the opcode in the verb application-specific information.

When the connector builds an input flist for a hierarchical business object, if a child business object verb has the same opcode as the parent, the connector puts the child in the same flist as the parent. Otherwise, the connector builds a separate flist for the child. Infranet uses levels in flists to specify arrays and substructures. When the connector starts building an input flist, it sets the level to zero. If the business object has children, the level is increased by an increment of one when processing a child object. If a business object needs a different opcode when executed alone rather than when executed as part of a hierarchy, then a different business object should be used with a similar structure.

For Create operations, parent opcodes are executed before child opcodes. For Delete operations, child opcodes are executed before parent opcodes. There is no mandatory order of execution for Update and Retrieve operations.

All storable classes can be retrieved using the opcode READ_OBJ and the POID of the root object.

Connector utility business objects

Each Infranet opcode requires a specific input flist and returns a specific output flist. In order for the connector to be meta-data driven, the business object must provide the connector with the fields that it needs to convert a business object instance and verb to the appropriate flist. Because opcode flists differ, you may not be able to build a single business object for Portal Infranet that provides all the information that the connector requires for every input and output flist. Instead, you may need to define special utility business object definitions that supplement the application-specific business object definition.

Note:
The definition of attribute-level application-specific information for connector version 4.0.x does not require utility business objects. Connector version 4.0.x also supports backward compatibility for attribute-level application-specific information, but for future releases, you will need to use PortalODA to convert old business object definitions into new business object definitions. See Converting old business objects to new business objectsfor instructions.

Utility business object definitions do not become business object instances that are sent through the integration broker. The connector simply uses them to construct required input and output flists for specific opcodes. You must design and build utility business object definitions during the design of the application-specific business object, and you must define the connector to support all utility business objects as well as all application-specific business objects. For an example of a utility business object, see Utility business object example: Create verb.

To determine whether you need utility business objects, examine the Infranet storable class, and the input and output flists of the opcodes used to perform the verb operations.

Portal Infranet utility business objects use application-specific information that differs in format from that of business objects for Portal. This format is described in the next section.

Application-specific information for utility business objects

The attribute application-specific information in utility business objects specifies the fields to be added to an flist and contains the values to use for the flist fields. In utility business objects, you must define attribute application-specific information for simple attributes and for container attributes as follows.

The verb description is not used for utility objects.

The following sections provide examples of application-specific information for Create, Update, Retrieve, and Delete verbs. The examples use the Portal_Account hierarchical business object to illustrate aspects of verb application-specific information.

Utility business object example: Create verb

As an example, consider the verb application-specific information for the Create verb in the Portal_Account top-level business object.
Verb application-specific information for the Create verb in the Portal_Account top-level business object

CUST_COMMIT_CUSTOMER is the opcode the connector uses to create a new customer account (an /account storable object). The opcode has its own transaction, so "Transaction Enabled" has been set to "true." The keyword NORMAL in the input_flist_model field indicates that the connector will correspond directly from the business object to the input flist. In other words, the business object provides all the fields required by the input flist, and the connector does not need supplemental information to create the input flist.

The CUST_COMMIT_CUSTOMER opcode for the Create Account operation returns an output flist containing the ID for the new customer in the PIN_FLD_ACCOUNT_OBJ field. The value of this ID must be returned to the WebSphere Business Integration Adapter system. To enable the connector to obtain the new ID, the business object designer created the Portal_C[reate]A[ccount]Output_Model utility business object definition. The output_flist_model field in the application-specific information specifies the Portal_CAOutput_Model as utility business object that the connector will use to read the output flist returned by the opcode.

The Portal_CAOutput_Model utility object contains one attribute, Poid, whose application-specific information tells the connector to extract the value of PIN_FLD_ACCOUNT_OBJ from the return flist to get the Portal Infranet object ID for the new customer. The connector inserts this value in the business object that it returns to the integration broker. The utility business object is shown in Figure 11.

Figure 11. Portal_CAOutput_Model utility business object definition

Portal_CAOutput_Model utility business object definition

Building flists for create operations

The Portal_Account business object is a hierarchical business object that looks like Figure 12.

Figure 12. Diagram of the Portal_Account hierarchical business object

Diagram of the Portal_Account hierarchical business object

On a Create operation, the connector examines the verb application-specific information for the child business objects to determine if the opcode is the same as that used by the parent business object. For a Portal_Account business object, the opcode is the same for parent and child business objects, and the connector can build a single flist for the entire business object Create operation. Figure 13 illustrates the single opcode and flist that the connector uses to make the Create call to Infranet.

Figure 13. Flist for create operation for Portal_Account hierarchical business object

Flist for create operation for Portal_Account hierarchical business object

Note, however, that the connector must create the flist with arrays for the child business objects. Therefore, verb application-specific information must include fields that indicate the level in the flist that the array should occur. For example, the Create verb application-specific information for the Portal_Contact child business object is:

CUST_COMMIT_CUSTOMER

The Create verb application-specific information for the Portal_Phone child business object is:

CUST_COMMIT_CUSTOMER

Utility business object example: Update verb

This example shows the verb application-specific information for the Update verb in the Portal_Account top-level business object:

CUST_SET_STATUS;false;Portal_Array_Model#PIN_FLD_STATUSES;NoRewrite

CUST_SET_STATUS is the opcode required to update an account object. The opcode does not have its own transaction, so "Transaction Enabled" has been set to "false." For this verb operation, the connector cannot correspond directly from the business object instance to the flist because the Portal_Account business object does not provide all the information required by the input flist. Because the connector needs additional information to create the flist, the input_flist_model field specifies the utility business object definition that the connector uses to construct the input flist. This utility object is named Portal_Array_Model.

The output_flist_model field contains the keyword NoRewrite, which indicates that the output flist returned by the opcode must not be used to overwrite the business object.

Portal_Array_Model utility business object

Portal_Array_Model is a hierarchical business object definition illustrated in Figure 14. It contains the information that the connector needs to build the input flist for the Update operation opcode. Specifically, the input flist requires an array that the Portal_Account business object definition does not contain. The Portal_Array_Model utility object enables the connector to create the array.

Figure 14. Portal_Array_Model utility business object definition

Portal_Array_Model utility business object definition

Recall that the Portal_Account Update verb application-specific information contained this text for the input_flist_model field.

Portal_Array_Model#PIN_FLD_STATUSES

This text identifies the utility business object used to create the flist and specifies the name of the array that the connector needs to put in the input flist. At runtime, the connector uses both the utility business object definition and the Portal_Account application-specific business object definition to build the input flist.

The connector builds the input flist as follows:

  1. It begins constructing the flist with a field PIN_FLD_POID and gets the value of the POID from the business object instance.
  2. It adds a field for PIN_FLD_PROGRAM_NAME to the flist. Because the Portal_Account business object definition does not contain this attribute, there is no value for this in the business object instance. Therefore, the value is defined in the application-specific information as the string CrossWorlds.
  3. It adds an array named PIN_FLD_STATUSES to the flist. Because the flist for the opcode PCM_OP_CUST_SET_STATUS requires an array for PIN_FLD_STATUSES, the Portal_Array_Model must include a container attribute so that the connector will create an array in the flist. The connector names the array as indicated in the application-specific information for the Update verb.

    The connector uses the current business object, Portal_Account, as the model for the array. In other words, the connector will insert in the flist array the fields specified in the current business object. Because some of the fields may not be required, the application-specific information for the container attribute in the utility business object specifies which attributes to ignore. The container attribute Portal_Object_Model specifies these attributes:

    Poid:AccountNumber:AccountObj
    

    Therefore, to construct the array, the connector examines the business object definition for Portal_Account, ignores the POID, AccountNumber, and AccountObj attributes, and builds the array using only the remaining attributes in the business object definition, PIN_FLD_STATUS and PIN_FLD_STATUS_FLAGS.

As a result, the input flist for the Update verb looks like this:

PIN_FLD_POID              POID    <value from bus obj instance>
PIN_FLD_PROGRAM_NAME      STR     "CrossWorlds"
PIN_FLD_STATUSES          ARRAY 
   PIN_FLD_STATUS         ENUM    <value from bus obj instance> 
   PIN_FLD_STATUS_FLAGS     INT      <value from bus obj instance>

This flist contains the mandatory fields for the input flist for the PCM_OP_CUST_SET_STATUS opcode.

Child Business Object Processing

For an Update operation, the required Infranet opcodes are different to update an account storable object, update the customer contact information in the account storable object, and update the billing information in the account storable object.

Therefore, although the customer contact information and customer billing information are part of the same storable class, the connector must use different opcodes to update the Portal_Account top-level business object and the Portal_Contact and Portal_BillInfo child business objects. In addition, the connector must generate separate input flists for each opcode. Figure 15 shows the set of flists required to update the Portal_Account hierarchical business object.

Figure 15. Flists for update operation for Portal_Account hierarchical business object

Flists for update operation for Portal_Account hierarchical business object

Utility business object example: Retrieve verb

This example is the Retrieve verb application-specific information in the Portal_Account top-level business object:

READ_OBJ;false;Only_Poid;Flat#Portal_BillInfo

The connector uses the READ_OBJ opcode to read a storable object from the database. This opcode does not have its transaction, so "Transaction Enabled" has been set to "false." In general, this opcode can be used for all Retrieve operations.

The input_flist_model field specifies that the current opcode needs only the POID from the business object. No other fields are needed for the input flist.

The opcode returns the POID of the object. All other fields in the object, including all array elements, are added to the return flist after the POID. The output_flist_model field contains the keyword Flat with the parameter Portal_BillInfo. This indicates that the information the connector needs to build the Portal_BillInfo child business object is contained in the flat flist rather than in an array.

Utility business object example: Delete verb

The final example is the Delete verb application-specific information in the Portal_Account top-level business object:

CUST_DELETE_ACCT;false;Only_Poid;NoRewrite

The connector uses the CUST_DELETE_ACCT opcode to delete the storable object from the database. This opcode does not have its own transaction, so "Transaction Enabled" has been set to "false." The input_flist_model field specifies that the current opcode needs only the POID from the business object. No other fields are needed for the input flist. The output_flist_model field contains the keyword NoRewrite, which indicates that the output flist returned by the opcode must not be used to overwrite the business object.

Note that Infranet is a logical delete application. For some objects, a delete operation is a change in status. For example, for the Portal_Service business object, the Delete verb application-specific information is:

CUST_SET_STATUS;Portal_DSInput_Model#PIN_FLD_STATUSES#NotNull

This text specifies the opcode for the logical Delete operation as CUST_SET_STATUS, and specifies that the input_flist_model is the utility object Portal_D[elete]S[ervice]Input_Model, which defines an flist with a PIN_FLD_STATUSES array that is not set to Null.

Context-driven verb behavior

Because the connector has to be able to handle both a hierarchical business object and a single child business object (for example, a Portal_Contact business object can be sent without the parent), certain meta-data-driven decisions depend on the context of the business object and verb. Depending on the verb, you must specify one unique opcode for the whole business object hierarchy or one opcode for each business object. For this reason you have to specify the opcode used by each level in each business object.

For a verb, the global opcode (the parent opcode) is applied if both the opcode for the child level and the parent level are similar. Otherwise, the parent opcode on the parent is applied first, followed by the child opcode for each child.

For example, when you need to create a contact, if the Portal_Contact business object is sent as an individual business object, use the opcode CUST_SET_NAMEINFO for the Create verb application-specific information. However, if the contact will be created with the account business object, use the parent opcode CUST_COMMIT_CUSTOMER. This opcode must be specified in the application-specific information. To support the above functionality, two copies of the Portal_Contact business object must be created and used for two different opcodes. One business object would have the verb ASI set to CUST_SET_NAMEINFO and the other business object would have the verb ASI set to CUST_COMMIT_CUSTOMER.

A complete sample Portal Infranet business object definition

The following structure describes the properties and application specific information for Sample Account business object in Portal Infranet adapter.

[BusinessObjectDefinition]
Name = Portal_Account
Version = 1.0.0
AppSpecificInfo = CN=/account
[Attribute]
Name = Poid
Type = String
Cardinality = 1
MaxLength = 255
IsKey = true
IsForeignKey = false
IsRequired = true
AppSpecificInfo = eu
IsRequiredServerBound = false
[End]
[Attribute]
Name = AccountNumber
Type = String
Cardinality = 1
MaxLength = 255
IsKey = false
IsForeignKey = false
IsRequired = false
AppSpecificInfo = 
   UpdateO=;FN=PIN_FLD_ACCOUNT_NO;Create=true;O=true;DeleteT=;
   Update=falTse;RetrieveT=;Alone=false;CreateT=;Retrieve=false;
   DeleteO=;ParentAtt=;UpdateT=;RetrieveO=Main;Delete=false;CreateO=
IsRequiredServerBound = false
[End]
 
[Attribute]
Name = AccountObj
Type = String
Cardinality = 1
MaxLength = 255
IsKey = false
IsForeignKey = false
IsRequired = false
AppSpecificInfo = 
   UpdateO=;FN=PIN_FLD_ACCOUNT_OBJ;Create=true;O=true;DeleteT=;Update=false;
   RetrieveT=;Alone=false;CreateT=;Retrieve=false;DeleteO=;ParentAtt=;
   UpdateT=;RetrieveO=Main;Delete=false;CreateO=
IsRequiredServerBound = false
[End]
 
[Attribute]
Name = Status
Type = String
Cardinality = 1
MaxLength = 255
IsKey = false
IsForeignKey = false
IsRequired = false
AppSpecificInfo =
   UpdateO=;FN=PIN_FLD_STATUS;Create=true;O=true;DeleteT=;Update=true;
   RetrieveT=;Alone=false;CreateT=;DeleteO=;Retrieve=false;ParentAtt=;
   RetrieveO=Main;UpdateT=PIN_FLD_STATUSES;CreateO=;Delete=false
IsRequiredServerBound = false
[End]
 
[Attribute]
Name = StatusReason
Type = String
Cardinality = 1
MaxLength = 255
IsKey = false
IsForeignKey = false
IsRequired = false
AppSpecificInfo =
   UpdateO=;FN=PIN_FLD_STATUS_FLAGS;Create=true;O=true;DeleteT=;
   Update=true;RetrieveT=;Alone=false;CreateT=;DeleteO=;Retrieve=false;
   ParentAtt=;RetrieveO=Main;UpdateT=PIN_FLD_STATUSES;CreateO=;Delete=false
IsRequiredServerBound = false
[End]
 
[Attribute]
Name = Portal_Contact
Type = Portal_Contact
ContainedObjectVersion = 1.0.0
Relationship = Containment
Cardinality = n
MaxLength = 0
IsKey = false
IsForeignKey = false
IsRequired = false
AppSpecificInfo =
   UpdateO=Main;FN=PIN_FLD_NAMEINFO;Create=true;O=true;Update=true;
   Alone=false;Retrieve=false;DeleteO=Main;ParentAtt=;RetrieveO=Main;
   CreateO=Main;Delete=false
IsRequiredServerBound = false
[End]
 
[Attribute]
Name = PlaceHolder
Type = String
Cardinality = 1
MaxLength = 255
IsKey = false
IsForeignKey = false
IsRequired = false
IsRequiredServerBound = false
[End]
 
[Attribute]
Name = Portal_BillInfo
Type = Portal_BillInfo
ContainedObjectVersion = 1.0.0
Relationship = Containment
Cardinality = n
MaxLength = 0
IsKey = false
IsForeignKey = false
IsRequired = false
AppSpecificInfo =
   UpdateO=Main;FN=PIN_FLD_BILLINFO;Create=true;O=true;Update=true;
   Alone=false;Retrieve=false;DeleteO=Main;ParentAtt=;RetrieveO=Main;
   CreateO=Main;Delete=false
IsRequiredServerBound = false
[End]
 
[Attribute]
Name = ProgramName
Type = String
Cardinality = 1
MaxLength = 1
IsKey = false
IsForeignKey = false
IsRequired = false
AppSpecificInfo =
   UpdateO=Main;FN=PIN_FLD_PROGRAM_NAME;Create=false;O=true;DeleteT=;
   Update=true;RetrieveT=;Alone=false;CreateT=;DeleteO=Main;Retrieve=false;
   ParentAtt=;PAttName=;RetrieveO=Main;UpdateT=;CreateO=;Delete=true
DefaultValue = CrossWorlds
IsRequiredServerBound = false
[End]
 
[Attribute]
Name = ObjectEventId
Type = String
Cardinality = 1
MaxLength = 255
IsKey = false
IsForeignKey = false
IsRequired = false
IsRequiredServerBound = false
[End]
 
[Verb]
Name = Create
AppSpecificInfo =
   IFM=;OpCode=CUST_COMMIT_CUSTOMER;OFP=;TFlag=true;
   IFP=;IF=NORMAL;Flag=0;OF=NORMAL
[End]
 
[Verb]
Name = Delete
AppSpecificInfo =
   IFM=;OpCode=CUST_DELETE_ACCT;OFP=;TFlag=false;IFP=;
   IF=NORMAL;Flag=0;OF=NORMAL
[End]
 
[Verb]
Name = Retrieve
AppSpecificInfo =
   IFM=;OpCode=READ_OBJ;OFP=Portal_BillInfo;TFlag=false;IFP=;
   IF=NORMAL;Flag=0;OF=NORMAL
[End]
 
[Verb]
Name = Update
AppSpecificInfo =
   IFM=;OpCode=CUST_SET_STATUS;OFP=;TFlag=false;
   IFP=;IF=NORMAL;Flag=0;OF=NORMAL
[End]
 
[End]

Copyright IBM Corp. 1997, 2004