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.
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.
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=;UpdateO=; DeleteO=;RetrieveO=;ParentAtt=;Alone=false
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:
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. If the field has to be updated from the Main flist, then set the value to Main |
Main | |
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. If the field has to be updated from the Main flist, then set the value to Main |
Main | |
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. If the field has to be updated from the Main flist, then set the value to Main |
Main | |
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. If the field has to be updated from the Main flist, then set the value to Main |
Main | |
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.
Figure 10. Application-specific information for business object and attributes
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:
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.
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:
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:
See "Connector utility business objects" for information on utility business objects. |
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.
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.
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.
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.
<flist_fieldname>[:[<bus_object_attributename>]:<default_value>]
[< bus_object_attributename>]([:< bus_object_attributename>])*
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.
As an example, consider the 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
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
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
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
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 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
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:
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.
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
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.
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.
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.
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]