Work with specific protocols and standards > RosettaNet > Configure pipdefinitions.xml file

Configure pipdefinitions.xml file

The pipdefinitions.xml file is the key for configuring Activator for RosettaNet trading, although other steps are required as well. The file defines the business messages to be traded for each PIP and the order in which each message is sent or received. Activator uses the definitions to validate RosettaNet messages and the trading order.

The file is at <install directory>\conf\rosettanet.

The following figure shows an example of the pipdefinitions.xml file. This example shows the definition for using the Asynchronous Request-Confirm test PIP. The PIP is defined between the beginning and ending Pip element tags. You can define as many PIPs as you want in this file.

See the following example of a pipdefinitions.xml file.

<?xml version="1.0" encoding="UTF-8"?> <PipDefinitions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="pipdefinition.xsd" dtdValidation="off" guidelineValidation="off"> <Pip code="0C2" name="Asynchronous Request-Confirm" version="R01.02"> <Activity name="Asynchronous Test Request" retryAttempts="3"> <Action name="Asynchronous Test Request Action" dtd="0C2_MS_R01_02_AsynchronousTestRequest.dtd" rootElement="Pip0C2AsynchronousTestRequest" fromService="Initiator Service" toService="Responder Service"> <Signal timeToAcknowledge="5"/> </Action> </Activity> <Activity name="Asynchronous Test Confirmation" retryAttempts="3"> <Action name="Asynchronous Test Confirmation Action" dtd="0C2_MS_R01_02_AsynchronousTestConfirmation.dtd" rootElement="Pip0C2AsynchronousTestConfirmation" fromService="Responder Service" toService="Initiator Service"> <Signal timeToAcknowledge="5"/> </Action> </Activity> </Pip> <Pip code="3B13" name="Shipping Order Confirmation Notification" version="V01.01"> <Activity name="Notify of Shipment Confirmation" retryAttempts="3"> <Action name="Shipping Order Confirmation Notification Action" dtd="3B13_MS_V01_01_ShippingOrderConfirmationNotification.dtd" rootElement="Pip3B13ShippingOrderConfirmationNotification" fromService="Initiator Service" toService="Responder Service"> <Signal timeToAcknowledge="15"/> </Action> </Activity> </Pip> <Pip code="3B3" name="Distribute Shipment Status" version="V11.00"> <Activity name="Shipment Status Distribution" retryAttempts="3"> <Action name="Shipment Status Distribution Action" dtd="ShipmentStatusDistribution_01_02.xsd" rootElement="ShipmentStatusDistribution" fromService="Transport Service Provider Service" toService="In-transit Information User Service" fromRole="Transport Service Provider" toRole="In-transit Information User" globalDocumentFunctionCode="Request" fromGlobalPartnerClassificationCode="Carrier" toGlobalPartnerClassificationCode="Distributor"> <Signal timeToAcknowledge="120"/> </Action> </Activity> </Pip> </PipDefinitions>

Note

Activator supports asynchronous responses, but not synchronous responses for RNIF.

The following describes the elements in the pipdefinitions.xml file.The following figure is an example of how the elements are used. Most of the information is used to build RosettaNet headers. But some elements, such as retryAttempts and timeToAcknowledge, affect performance of Activator.

PipDefinitions – The PIP definitions are placed between the beginning and ending PipDefinitions elements.
xsi:noNamespaceSchemaLocation – The default schema is pipdefinition.xsd. The file is at <install directory>\conf\rosettanet\schemas.
dtdValidation – Indicates (on or off) whether Activator validates the document against a DTD or schema. If on, copy the DTD to <install directory>\conf\rosettanet\dtds or the schema to <install directory>\conf\rosettanet\schemas. If off, you still must copy to the dtds or schemas directory, but Activator does not perform validation.
A third option, noload, turns off validation regardless whether you have copied a DTD to the dtds directory or a schema to the schemas directory. The noload option allows trading of documents with a DOCTYPE declaration, but the DTD or schema does not have to be in the dtds or schemas directory. The DTD name still must be configured within each DTD Action element. The DTD name is used for document recognition. If an outbound document includes a DOCTYPE declaration and there is no matching DTD attribute, the message is rejected.
guidelineValidation – For DTD-based PIPs only, indicates (on or off) whether Activator validates the document against a guidelines XML file. If on, copy the file to <install directory>\conf\rosettanet\guidelines.
Pip – Each PIP is defined between beginning and ending Pip elements.
code – An attribute of the Pip element, this code identifies the PIP. The code is available in the RosettaNet PIP specification document. For example, for the Asynchronous Request-Confirm PIP, the code is 0C2. This is required to build the RosettaNet headers. It is not specified by the service content. Activator determines the PIP code and PIP version based on the document type of the service content.
name – An attribute of the Pip element, this is the name of the PIP. The name is available in the RosettaNet PIP specification document.
version – An attribute of the Pip element, this is the version of the PIP. The version is available in the RosettaNet PIP specification document. For example, for the Asynchronous Request-Confirm PIP, the version is R01.02.This is required to build the RosettaNet headers. It is not specified by the service content. You can have multiple versions of a PIP, but the document types need to be different. RosettaNet usually gives service contents a different document type based on the version.
Activity – The activity as defined in the RosettaNet PIP specification document. A PIP can have multiple activities. Each activity must be listed in the pipdefinitions.xml file in parallel with the specification.
name – An attribute of the Activity element, this is the activity name as defined in the RosettaNet PIP specification document.
retryAttempts – An attribute of the Activity element, this specifies how many times to resend a message when a signal is not received within the time specified in the timeToAcknowledge attribute. This value is specified in the RosettaNet PIP specification document.
Action – The action for the parallel activity as specified in the RosettaNet PIP specification document
name – An attribute of the Action element, this is the name of the action. This is the business message payload. The name is available in the RosettaNet PIP specification document.
dtd – This is an attribute of the Action element. For DTD-based PIPs, if dtdValidation=“on”, the value is the name of the DTD to validate against. The name is available in the RosettaNet PIP specification document. The DTD must be copied to <install directory>\conf\rosettanet\dtds. For schema-based PIPs, if dtdValidation=”on”, the value is the name of the schema to validate against. The name is available in <install directory>\conf\rosettanet\schemas. Look in the XML\Interchange directory for the desired PIP. If validation is off, this attribute is not used.
rootElement – An attribute of the Action element, the rootElement is used to identify the action when there is no DOCTYPE definition. The value of rootElement is in the service content. This handles the case where there is no DOCTYPE definition and provides for a means to validate the XML (given the dtd attribute). If there is a DOCTYPE definition, the DOCTYPE is used to validate the XML, otherwise the dtd attribute is used. The document is rejected if there is no DOCTYPE, DTD validation is on and the dtd attribute is missing or blank.
fromService – An attribute of the Action element, this is the service from which the message is being sent. This value is specified in the RosettaNet PIP specification document. This is required to build the RosettaNet headers. It is not specified by the service content.
toService – An attribute of the Action element, this is the service to which the message is being sent. This value is specified in the RosettaNet PIP specification document. This is required to build the RosettaNet headers. It is not specified by the service content.
fromRole – An attribute of the Action element, this is the role the trading partner who sends the message plays in the PIP. This value is specified in the RosettaNet PIP specification document. This is required to build the RosettaNet headers. The value is parsed from the service content for DTD-based PIPs. However, the value in pipdefinitions.xml is used only when the value is not found in the service content. The value is required for schema-based PIPS. It is not specified in the service content of schema-based PIPs.
fromRoutingIdXpath – This is an optional attribute of the Action element. If the location of fromRoutingId changes from the usual location (fromRole/PartnerRoleDescription/PartnerDescription/
BusinessDescription/GlobalBusinessIdentifier)
then mention the new path inside this attribute. For example:

fromRoutingIdXpath=”fromRole/PartnerRoleDescription/

PartnerDescription/BusinessDescription/

BusinessIdentification/GlobalBusinessIdentifier”

toRole – An attribute of the Action element, this is the role the trading partner who receives the message plays in the PIP. This value is specified in the RosettaNet PIP specification document. This is required to build the RosettaNet headers. The value is parsed from the service content for DTD-based PIPs. However, the value in pipdefinitions.xml is used only when the value is not found in the service content. The value is required for schema-based PIPS. It is not specified in the service content of schema-based PIPs.
toRoutingIdXpath – This is an optional attribute of the Action element. If the location of toRoutingId changes from the usual location (toRole/PartnerRoleDescription/PartnerDescription/
BusinessDescription/GlobalBusinessIdentifier)
then mention the new path inside this attribute. For example:

toRoutingIdXpath=”toRole/PartnerRoleDescription/

PartnerDescription/BusinessDescription/

BusinessIdentification/GlobalBusinessIdentifier”

globalDocumentFunctionCode – This is an attribute of the Action element. The possible values are:
- Request. The business document is a request for a business action to be performed by a partner.
- Response. The business document is a response to a requesting partner.
This is required to build RNIF 1.1 headers. The value is ignored when packaging RNIF 2.0 messages. This attribute is ignored for DTD-based PIPs. The value is required for schema-based PIPS when using RNIF 1.1 packaging.
fromGlobalPartnerClassificationCode – An attribute of the Action element, this is a classification of the role the trading partner who sends the message plays in this PIP. The valid values are specified in the RosettaNet Service Header Message Guidelines for RNIF 1.1 and RNIF 2.0. This is required to build the RosettaNet headers. The value is parsed from the service content for DTD-based PIPs. However, the value in pipdefinitions.xml is used only when the value is not found in the service content. The value is required for schema-based PIPS. It is not specified in the service content of schema-based PIPs.
toGlobalPartnerClassificationCode – An attribute of the Action element, this is a classification of the role that the trading partner receiving the message plays in this PIP. The valid values are specified in the RosettaNet Service Header Message Guidelines for RNIF 1.1 and RNIF 2.0. This is required to build the RosettaNet headers. The value is parsed from the service content for DTD-based PIPS. However, the value in pipdefinitions.xml is used only when the value is not found in the service content. The value is required for schema-based PIPS. It is not specified in the service content of schema-based PIPs.
PipInstanceId – Used to specify when special handling of RosettaNet metadata within the service content is enabled. This functionality aids in the trading of dual-action PIPs when MMDs are not used.
parseFromServiceContent – Enables or disables parsing and writing pipInstanceId, ReplyToTrackingId and Global Usage Code from or to service content. Defaults to false.
separator – This attribute is used to specify the separator character to delineate pipInstanceId, ReplyToTrackingId and Global Usage Code when reading from or writing to the service content. The default separator character is a colon ( : ).
xpath – This attributes specifies the XPath expression to parse or write pipInstanceId, ReplyToTrackingId and Global Usage Code from or to.
For DTD-based service content, defaults to:
/*/thisDocumentIdentifier/ProprietaryDocumentIdentifier for DTD based service contents.
For schema-based service content, defaults to:
/*/ssdh:DocumentHeader[1]/ssdh:DocumentInformation[1]/
ssdh:DocumentIdentification[1]/ssdh:Identifier[1]
The XPath must include namespace prefixes for schema-based service contents.
Signal – This element specifies the conditions for the response to the message action.
timeToAcknowledge – An attribute of the Signal element, this specifies the time in minutes within which the message acknowledgment must be received. If not received within the specified time, the message is to be resent up to the limit in the retryAttempts attribute. After each resend, the timeToAcknowledge interval must elapse before another resend is attempted. This value is specified in the RosettaNet PIP specification document.