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
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>
Example of resolving a business object name:
Set
TopBOPrefix=CIDXOBJ
in the TPI-RNIF data handler.
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
.
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
The data handler requires that you define at least the following four child object attributes in the wrapper:
MessageControlDocument
Preamble
ServiceHeader
ServiceContent
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 |
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 |
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 |
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:
You can use any name except those reserved for the four required attributes described earlier.
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