Understanding business object structure

The TPI-RNIF data handler places specific requirements on the top-level strucure of any business object it processes. It requires that the top level business object acts as a wrapper, and that the wrapper object contains multiple child objects that represent the MCD and the various RNIF parts contained within the MCD.

Example of a wrapper object structure:

Wrapper BO
      |MessageControlDocument BO 
      |Preamble BO 
      |ServiceHeader BO 
      |ServiceContent BO 
 

Naming the wrapper business object

The data handler requires specific naming conventions in order for it to identify the appropriate business object definitions to use when converting an inbound MCD to a business object instance. The wrapper object must be named according to the following convention:

<TopBOPrefix_>Version_ServiceContentDoctype
 

where

TopBOPrefix
 

is optional. The TPI-RNIF data handler prepends the value of

TopBOPrefix
 

to the doctype to determine the appropriate wrapper. The doctype used to derive the object name is always that of the RNIF service content part contained within the MCD, such as OrderCreate, ReceiptAcknowledgement, etc.

The

Version
 

part of the name is determined by the value provided in the packaging protocol description of the MCD.

Example of the packaging protocol description:

<MessageControlDocument>
      <PackagingProtocol> 
           <Standard>CIDX</Standard> 
           <Version>2.0</Version>
      </PackagingProtocol> 
 </MessageControlDocument>
 
Note:
If the version name contains periods, they are replaced with underscores when the business object name is resolved.

Example of resolving a business object name:

  1. Set

    TopBOPrefix=CIDXOBJ
     

    in the TPI-RNIF data handler.

  2. Pass an MCD containing a RNIF 2.0-structured OrderCreate request to the data handler.

The data handler maps the MCD to

CIDXOBJ_2_0_OrderCreate
 

.

Naming child business objects

Child business objects must also conform to naming conventions so that the data handler can process them correctly. The child object that represents the MCD envelope must match the following structure:

BOPrefix_Doctype
 

An example of a child object that represents the MCD envelope:

CIDX_MessageControlDocument 
 

Child objects that represent RNIF message parts, including preamble, service header, and service content must also be properly named and match the following structure:

BOPrefix_Version_Doctype
 

where

DocType
 

represents the RNIF message part. An example of a child object that represents part of the RNIF message:

CIDX_2_0_Preamble
 

Defining child object attributes

The data handler requires that you define at least the following four child object attributes in the wrapper:

The following example shows the required attributes matched to a RosettaNet business object definition that adheres to the RNIF 2.0 specification.

RNETOBJ_2_0_OrderCreate
 

is the wrapper object.

TopBOPrefix=RNETOBJ 
 

BOPrefix=RNET
 

Table 8. Required attributes matched to type
Attribute Name Attribute Type
MessageControlDocument RNET_MessageControlDocument
Preamble RNET_2_0_Preamble
ServiceHeader RNET_2_0_ServiceHeader
ServiceContent RRNET_2_0_OrderCreate

Note:
When defining attributes, do not change the default values for fields that are not shown in the example. These fields include cardinality, application-specific information, etc.

Using PIP-specific signals

You can configure the data handler to include the PIP identifier in the top-level object wrapper. This is optional, but it can be useful when RosettaNet signal messages are being exchanged. If you want to include PIP-specific signals, you must select the

PIPSpecificSignals
 

option within the data handler meta object, and then specify all doctypes. Doctypes must be delimited with semicolons and without spaces. Whenthe data handler receives an MCD document, it checks to see if the service content doctype is of a type specified in the option PIPSpecificSignals. If it is, the data handler extracts the PIP identifier from the MCD and seeks the wrapper object name based on the following syntax:

<TopBOPrefix_>Version_PIPType_ServiceContentDoctype
 

When RosettaNet signal messages are being exchanged, and the data handler is configured to use the included PIP identifier, the data handler can convert the generic signal message to a distinct business object depending on the PIP for which the signal was generated. This means that processes can subscribe to only those signals of interest.

Without PIP-specific signals, the data handler might convert a receipt acknowledgement signal to a generic wrapper object, such as the following:

CIDXOBJ_1_1_ReceiptAcknowledgement 
 

WithPIP-specific signals, the data handler can map the receipt acknowledgement signal to a specific wrapper object, such as the following:

CIDXOBJ_1_1_2A1_ReceiptAcknowledgement 
 

The following example shows the required attributes matched to a RosettaNet business object definition that adheres to the RNIF 1.1 specification, and uses PIP-specific identifiers. The example assumes that

PIPSpecificSignals
 

contains the doctype

OrderCreate
 

.

RNETOBJ_1_1_E41_OrderCreate
 

is the wrapper object.

TopBOPrefix=RNETOBJ 
 

BOPrefix=RNET
 

Table 9. Required attributes matched to type, using PIP-specific identifiers
Attribute Name Attribute Type
MessageControlDocument RNET_MessageControlDocument
Preamble RNET_1_1_Preamble
ServiceHeader RNET_1_1_ServiceHeader
ServiceContent RNET_1_1_E41_OrderCreate

Note:
RosettaNet standards specify that OrderCreate documents fall under PIP E41.

Using delivery header

You can define delivery header, a fifth attribute, in the wrapper object. It is optional.

During request processing, if the data handler finds and populates an existing child attribute with this name, the data handler serializes the child object and adds it to the outbound MCD.

During event notification, if the MCD contains a delivery header structure, the data handler checks to see if the wrapper object contains a delivery header attribute. If it does, the data handler maps the delivery header structure to this attribute.

If the data handler cannot find a delivery header attribute within the wrapper object, it generates a warning. However, if the MCD does not contain a delivery header structure, the data handler does not generate a warning even if the wrapper object contains a delivery header attribute.

The following example shows the required attributes matched to a RosettaNet business object definition that adheres to the RNIF 2.0 specification. This wrapper object uses PIP-specific signals and the DeliveryHeader attribute.

RNETOBJ_2_0_E41_OrderCreate
 

is the wrapper object.

TopBOPrefix=RNETOBJ 
 

BOPrefix=RNET
 


Table 10. Required attributes matched to type, using delivery header
Attribute Name Attribute Type
MessageControlDocument RNET_MessageControlDocument
Preamble RNET_2_0_Preamble
ServiceHeader RNET_2_0_ServiceHeader
ServiceContent RNET_2_0_E41_OrderCreate
DeliveryHeader RNET_2_0_ServiceHeader

Using key link attributes

It can be useful to include meaningful keys in a top-level business object. You can do this with the TPI-RNIF data handler by using key links. Key links are defined and supported only in the wrapper, and they instruct the data handler to copy key information from within one of the child business objects to the wrapper object.

When the data handler receives and MCD and constructs the corresponding wrapper object, it populates any key link attributes it finds in the wrapper with nested attributes in the child objects.

To define a key link, do the following:

  1. Create an attribute in the wrapper business object.

    You can use any name except those reserved for the four required attributes described earlier.

  2. Specify application-specific text according to the syntax
    type=key;ref=someInnerAttribute
     

    where

    someInnerAttribute
     

    defines the path to an attribute, relative to the wrapper object.

The following example shows how the TPI-RNIF data handler processes key links.

Key link attribute name:

InstanceId
 

Application-specific information:

type=key;ref=MessageControlDocument.TLO.ProcessInfo.PIPInstanceID
 

The data handler resolves this by copying the value of the child attribute

PIPInstanceID
 

to the wrapper attribute

InstanceId
 

.

Copyright IBM Corp. 1997, 2004