RosettaNet HTTPS Connector
Usage
The RosettaNet standard serves as a basis for the exchange of data between companies operating world-wide with the focus on the area of supply chain management.
RosettaNet Consortium, refer to
Functional scope
The RosettaNet connector supports the following functionality from the RosettaNet specification:
-
RosettaNet Implementation Framework (RNIF) V2.0
RNIF describes the structure of the XML messages that are used, the procedures for packing and unpacking the messages, the protocols supported, security requirements and error handling.
-
Receiving messages asynchronously over HTTP(S)
-
Unpacking messages received, checking their syntax and converting them to the recipient’s own XML format
-
Archiving messages
-
Creating a valid RosettaNet message from the PIP produced in the workflow.
RosettaNet Partner Interface Processes (PIP) define the business processes between partners.
-
Sending messages and receipts asynchronously over HTTP(S)
-
Generation and control of the message IDs used in accordance with the RNIF
Structure and Exchange of RosettaNet Messages
Structure
The following figure illustrates the structure of a RosettaNet business message:
-
Header
XML metadata with information about the message. Each message must contain all three header portions exactly once. The header has the following structure:
-
Preamble Header
Version of the RNIF to which the message conforms. The current version is RNIF 2.0.
-
Delivery Header
Identifies the sender and receiver and contains a date-and-time stamp. All elements involved in the transmission of a business message, that is, the sender, the receiver and any intermediate stations, use this information for routing purposes.
-
Service Header
Information on the PIP as ID, on the PIP instance as ID, and the business activity involved.
-
-
Payload
The actual content is referred to as the payload and is XML-encoded.
-
Service Content
States whether the message is an action message or a signal message. The process activity of an action message is defined in the PIP. Signal messages are receipts or error messages.
-
Attachments
If the message is an action message it can contain one or more attachments.
-
All parts of a business message are compresses using the MIME/S-MIME message format.
Receipts
The reception of a RosettaNet message is signaled by a receipt or an error message. Receipts can be sent synchronously or asynchronously.
Transport protocols
The HTTP, HTTPS or SMTP protocols may be used to transport the messages.
Asynchronous exchange of messages
The RosettaNet specification defines the asynchronous exchange of messages which proceeds as follows:
-
Business partner A sends business partner B a RosettaNet message. This message contains a so called PIP-ID which is used for identifying the message.
-
B stores a copy of message, as evidence that it was received
-
B returns an acknowledgement of its receipt to A.
-
Now, there are two options:
-
A receives the acknowledgement.
-
A does not receive an acknowledgement within an agreed period of time. In this case, A re-sends the business message:
B receives message. B checks whether this message has already been received earlier, because it must be ensured that the message is only processed exactly. To this end, the PIP-ID of the incoming message is compared with all PIP-IDs of all messages already received.
-
Attachment handling
To use RosettaNet attachments with an output connector, the attachments must be described by three variables (X) numbered consecutively starting with 0.
-
RNAttachment.X
, type:base64Binary
contains the attachment data
-
RNAttachmentContent-ID.X
, type:xs:string
contains the attachment’s unique identifier that you can generate using
com.inubit.ibis.xsltext.Misc
. -
RNAttachmentContent-Type.X
, type:xs:string
MIME content type of the attachment, for example,
text/xml
.
You can write attachments into the file system using an input connector.
Example Workflow: Generating RosettaNet Messages
The workflow shown generates a RosettaNet message and hands it over to another workflow via the Workflow Connector SendRosettaNetMessage.
The data for the RosettaNet message are imported from an ERP system and converted into the RosettaNet structure via some XSLT Converters:
-
The XSLT Converter Create PIP-specific Payload creates the PIP-specific message (payload).
-
The XSLT Converter Create Headers generates the headers.
The timestamp is set using the Java method jHelper:getDateTime("yyyyMMdd’T’HHmmss.SSS’Z'")
.
The PIP ID that is stipulated for this message (e.g.: 4A5) is assigned to the GlobalProcessIndicatorCode
element.
In this mapping, the payload is added in the last line by means of a simple copy.
Example Workflow: Sending a RosettaNet Message
The depicted workflow sends the RosettaNet message and receives the acknowledgement. If the message was sent for the last time and still no acknowledgement has arrived, the error branch is accessed.
Sending a message
The Output Connector RN-Output receives the RosettaNet business message as input and processes it as follows:
-
The preamble header is added. It contains the RNIF version the message is based on.
-
The delivery header and the service header were already created by XSLT Converters. The RosettaNet Output Connector adds the missing information to these headers. The information is copied from the configuration data that was specified when the connector was created. In addition, the instance identifier is generated and added.
-
The ID generated for each message is stored in the
ListofGeneratedIds.xml
index file in the working directory.
The Output Connector then sends the message to the configured receiver and maintains the message in the workflow until the acknowledgement is received.
Sending error e-mails
The RosettaNet Output Connector’s error branch is accessed if the business message has already been sent once before and again no acknowledgement has been received for the message. A message is then sent via the mail connector module indicating that the attempt to send the business message failed.
DistributeRNOutput Demultiplexer
In addition, the message is passed to the demultiplexer, which transfers the message either to a dummy module or to the WaitUntilAcknowledge multiplexer.
-
If the XPath
/RosettaNetConnector/AcknowledgeReceived
is non-blank, the dummy module receives the input message. This means that the acknowledgement of the message has arrived at the output connector and no further action is required. -
If the XPath
/RosettaNetConnector/Retry
is blank, the WaitUntilAcknowledge multiplexer receives the input message. This means that the acknowledgement associated with this message has not yet been received.
Splitter module
The splitter module receives an acknowledgement passed on by the input connector workflow and passes it both to a mail connector and to the next demultiplexer.
WaitUntilAcknowledge Multiplexer
The multiplexer receives messages from the DistributeRNOutput demultiplexer located upstream in the workflow and the acknowledgement messages from the splitter module and evaluates them.
To do this, it compares the instance ID and the PIP number of the two messages that have come in. If they are identical, a message is passed to the output connector; this acknowledges a message sent earlier. This means that this business message need no longer be held in the output connector.
This completes the Send RosettaNet Message workflow.
Example Workflow: Receive Message and Send Acknowledgement
The depicted workflow receives RosettaNet messages and routes them based on their content.
Message receive time
At the start of the workflow, the RosettaNet input connector RN Input is configured as a listener and waits for messages. When a business partner sends a business message, the connector does the following:
-
stores the message in the specified working directory,
-
checks whether the message was already sent using the
/<PIP>/*.msg
files in the working directory (if yes, the connector creates an appropriate XML message). -
immediately sends a (synchronous) acknowledgement,
-
passes the message on to the demultiplexer module.
Receipts can be sent asynchronously as well, for example, after the waiting backend system has received the RosettaNet message. To this end, in the Input Connector (refer to Dialog Asynchronous receipt in the RosettaNet HTTPS Connector), activate sending asynchronous receipts and add an Output Connector to the workflow (refer to Dialog Receipt). The Output Connector sends the receipts and therefore should be added to the workflow in a position at which the waiting backend system has already confirmed the receipt of the RosettaNet message.
Conditional forwarding of message
Depending on its content, the demultiplexer located after the RosettaNet input connector in the workflow forwards the XML message to one of the downstream modules:
-
Process_PIP4A3
If the service header contains the code 4A3 in the
RosettaNetXML/ServiceHeader/ProcessControl/pipCode/GlobalProcessIndicatorCode
element, the message is passed on to the Workflow Connector Process_PIP_4A3 and thus to the underlying workflow which, for the e.g., passes the message to an ERP system. -
Deliver_Acknowledge
If there is an XPath
/RosettaNetConnector/AcknowledgeReceived
in the message, it must be an acknowledgement message which is then passed to the Deliver_Acknowledge Workflow Connector and thus to a workflow that contains a RosettaNet output connector.This RosettaNet output connector evaluates the message to determine to which of the messages it has sent this acknowledgement belongs. The receipt of this message indicates that this message doesn’t need to be resent.
-
Dummy
If the message contains the string `/RosettaNetConnector/MessageAlreadyProcessed `the demultiplexer passes the message to the dummy module, in which no further processing is performed.
The dummy could be replaced by another functionality such as, e.g. a mail connector that informs an administrator that a message that has already been sent has been received again. The important point here is that a message that has already been sent must not be passed on to the ERP system again for processing.
Dialog Descriptions
All name and value elements in business messages are case-sensitive. Where input for fields in the connector dialog is stipulated in the RosettaNet specifications, this must be copied over in the exact form in which it is written in the specification. |
Dialog RosettaNet Connector Properties
-
Add
Clicking on New adds another tab New PIP for the new PIP.
Refer to New PIP Tab.
-
Delete
-
Display the tab which you want to delete.
-
Click Delete.
A message is displayed. After confirming the message the PIP is deleted.
-
-
General tab
-
NoF tab
(Output Connector only)
Refer to NoF Tab.
-
PIP tab
(After clicking New)
Refer to New PIP Tab.
General Tab in the RosettaNet HTTPS Connector
All the data that remains constant in business messages between two business partners is specified in this tab.
Working directory
-
Path
Click the Choose button on the right-hand side. A dialog opens in which you can navigate to the directory in which all the received and generated messages are stored. This directory also stores the file containing all the instance identifiers that have been generated. An instance identifier is a string that uniquely identifies each message in the context of two business partners. The instance identifier is not globally unique; to achieve that the string would need to be created in a highly complex way.
The same working directory must be specified for both the RosettaNet Input and Output Connectors.
DTD configuration
The selection of the DTDs determines the syntactical structure of the message header.
The DTDs needed can be downloaded from the RosettaNet Consortium’s web pages (ZIP file of the current RNIF V2.0).
-
Preamble DTD:
Preamble_MS_V02_00.dtd
-
Delivery Header DTD:
DeliveryHeader_MS_V02_00.dtd
-
Service Header DTD:
ServiceHeader_MS_V02_00.dtd
-
Receipt Ack. DTD:
AcknowledgmentOfReceipt_MS_V02_00.dtd
-
Exception DTD:
Exception_MS_V02_00.dtd
-
NoF DTD:
0A1_MS_V02_00_FailureNotification.dtd
To update a file which is already loaded, you must load a file with a different name. If you load a file with the same name, the existing file is not replaced. |
Identification
-
Your DUNS: Enter your own DUNS number. A DUNS number uniquely identifies business partners.
You obtain DUNS numbers from the Dun & Bradstreet Corporation on https://www.dnb.com/de-de/produkte-services/dun-bradstreet/dnb-duns-nummer.
-
Business partner DUNS: Enter the DUNS number of your business partner.
-
Location ID: The location ID is a user-definable alphanumeric string in any format. It can be used e.g. to identify a special subsidiary of a business partner. The business partners agree the location ID between themselves.
Clearing message archive
-
Delete messages after (days)
Defines, after how many days the IDs of the RosettaNet messages which are already received are deleted from the file system.
The IDs are stored in an XML file. When sending a very large number of messages, this file can grow so large that the performance is affected. This is why IDs are deleted in regular intervals.
Retry delay
-
Retry delay
The connector waits actively the given waiting time in seconds before it retries to send the message, default: 30 seconds.
Always define the product of the retry delay and the retries (refer to Retries in section New PIP Tab) to be considerably smaller than the connector’s timeout (System Connector Properties tab). |
Attachment handling
-
Store attachments into file system
(Input Connector only)
When activated, attachments are stored into variables automatically after reception. For each attachment three variables are created; if there are several attachments, the variables are numbered consecutively starting by null (X):
-
RNAttachment.X
Contents of the attachment, base64-encoded and zipped
-
RNAttachmentContent-Type.X
MIME type of the attachment, e.g. application/xml
-
RNAttachmentContent-ID.X
ID of the attachment; can be used for referencing the attachment in a RosettaNet document.
-
Error handling
(Input Connector only)
-
Individual
Activate this option, if you want to carry out error handling in the workflow yourself. If this option is selected, the workflow throws an error that can be treated individually.
-
Signal (Exception)
If this option is selected, the connector sends a RosettaNet signal message containing the relevant error. The workflow is executed successfully without throwing an error.
NoF Tab
(Output Connector only)
For creating a Notification of Failure (NoF). A NoF is in fact a PIP0A1 and is sent in case of an error, e.g. if timeouts occur in the process of the data exchange or if messages cannot be processed.
The field names are self-explanatory.
New PIP Tab
All Partner Interface Processes (PIPs) are specified by RosettaNet in order to guarantee that sender and receiver exchange standardized messages.
A PIP consists of one of eight possible clusters, each cluster consists of one or more segments and each segment contains one or more PIP descriptions. For each PIP there is a specification and a DTD. There are PIPs that are defined for a request or for a response or for both functions. The structure of each action is described in a DTD or in an XML Schema.
PIP definitions (including the DTD or XML Schemas) can be downloaded on the RosettaNet website.
PIP settings
-
PIP
A PIP ID, as for example 3A2, consists of the following parts:
-
Single digit (0..7) specifying the cluster (3=Order Management)
-
Upper case alphabetic (A..D) indicating the segment (A=Quote and Order Entry)
-
One or two digits (in the range 1..20) indicating the PIP (2=Request Price and Availability)
-
-
PIP version
For the purpose of checking the validity of the message, a simple comparison of the strings is performed on these fields.
Some business partners agree not to include the last four positions in long version or release designations. If one of the business partners uses a release or version number without the last four positions while the other includes the last four positions, the message would be deemed to be invalid.
The underlying PIP version is to be found in the RosettaNet specification.
-
DTD/Schema
For loading the DTD or the XML Schema, which describes the action of the PIP. Additionally, define whether you load a DTD or an XML Schema.
-
Input connector: Choose the Request DTD/Schema for this field so that the incoming request can be checked for correctness with this DTD.
-
Output connector:
The DTD/Schema is used for checking the correctness of outgoing messages.
To update a file which is already loaded, you must load a file with a different name. If you load a file with the same name, the existing file is not replaced!
-
Non-repudiation of receipt
(Input Connector only)
When activated, a check sum of the contents of the original message is created and returned together with the acknowledgement. Thus, the sender can verify that the original message has arrived at the recipient.
-
-
Retries
-
Input connector:
For each PIP, the number of retries is defined in table 3-3 of a PIP specification in section Retry Count. For a PIP 3A2 the number of retries is 3.
-
Output connector:
The number of retries is specified for each PIP. The value is given in table 3-3 of a PIP specification, under Retry Count. For example, for PIP 3A2 the value 3 is indicated.
-
-
Role name sender/ recipient
(Output Connector only)
The role names are set out in the specification for each PIP. They are normally to be found in table 3-1 of the PIP specification. E.g., for PIP 3A2 the role name of the sender is Customer and that of the receiver is Product Supplier.
-
Service name sender/recipient
(Output Connector only)
The names are set out in the specification for each PIP. E.g., for PIP 3A2 the values can be found in table 4-1.
-
Business activity
(Output Connector only)
The designations for business activities are specified by RosettaNet and laid down for each PIP. They are normally to be found in table 3-1 of the PIP specification. For example, for PIP 3A2, it is Request Price and Availability.
-
Business action
(Output Connector only)
The designations for business actions are specified by RosettaNet and laid down for each PIP. They are normally to be found in table 4-2 of the PIP specification. For example, for PIP 3A2, depending on the action, it is either Price and Availability Request Action or Price and Availability Response Action.
-
Message usage
(Output Connector only)
Inserts a reference to the message type into the message. In a message’s service header there is an XML element
<GlobalUsageCode>
. Depending on your selection in this field, either Test or Production is inserted into this tag. RosettaNet does not specify how a business partner is to proceed with this element. If business partners evaluate the Test or Production string they can decide from the value found whether the message is to go into the production environment or into a test environment, if one is available.
Dialog Asynchronous receipt in the RosettaNet HTTPS Connector
(Input Connector only)
Sending receipt asynchronously
-
Send asynchronously
Activates sending asynchronous receipts.
Dialog S/MIME Configuration in the RosettaNet HTTPS Connector - Input Message
(Input Connector)
In this dialog you enter the information required for decrypting and verifying encrypted and signed input messages.
You need a keystore file containing your private key and your business partner’s public key. |
Keystore Configuration
Click the button to load your Keystore.
S/MIME decryption
For activating and deactivating encryption.
-
Alias: For selecting the alias under which the private key is stored in the keystore.
-
Password: Password for the selected key.
S/MIME signature check
For activating and deactivating the signature check.
-
Alias: For selecting the alias under which the public key is stored in the keystore.
Dialog Connection Data for Business Messages
(Input Connector)
Base configuration
-
Server URL
URL and port of the servlets which is waiting for RosettaNet messages.
Authentication
-
Authentication required
Activate this option if the server requires an authentication. In this case enter the account which the connector should use.
-
Login name: Username for authentication.
-
Password: Password for authentication.
HTTP header configuration
HTTP headers are used for transferring information like, for example file size, HTTP server and user agent or MIME type between client and HTTP server.
The button Header listing opens a dialog for defining headers as name/value pairs.
For information about headers refer to https://www.w3.org/Protocols/HTTP/1.1/rfc2616.pdf.
Dialog Receipt
An Output Connector for sending asynchronous receipts can be positioned anywhere in the same workflow receiving the RosettaNet messages.
The output connector fetches the required data from a variable which was filled by the RosettaNet input listener at the beginning of the workflow.
Sending the receipt
-
Send receipt
Activates sending asynchronous receipts.
Dialog S/MIME Configuration in the RosettaNet HTTPS Connector - Output Message
In this dialog you enter the information required for encrypting and the output messages.
You need a keystore file containing your private key. |
Keystore configuration
Click the button to load your keystore file.
S/MIME encryption
For activating/deactivating encryption.
-
Alias: For selecting the alias under which the private key used for encryption is stored in the keystore.
-
Encryption algorithm: For selecting an encryption algorithm.
-
Encrypt payload container/Encrypt payload
Refer to RNIF Core Specification (https://xml.coverpages.org/RNIF-Spec020000.pdf), page 43.
S/MIME signing
For activating and deactivating signing.
-
Alias
For selecting the alias under which the private key used for signing is stored in the keystore.
-
Password
Password for the private key.
-
MIC algorithm
For selecting the Message Integrity Check algorithm. The algorithm is used to generate a check sum of the output message. Using the check sum the recipient can verify whether the output message arrived unmodified.
Dialog Connection Data for Messages Disposition Notifications
(Input Connector only)
Base configuration
-
Server URL
URL and port of the servlets which is waiting for RosettaNet messages.
-
SSL
The button opens the Dialog SSL Configuration.
Authentication
-
Authentication required
Activate this option if the server requires an authentication. In this case enter the account which the connector should use.
-
Login name: Username for authentication.
-
Password: Password for authentication.
HTTP header configuration
HTTP headers are used for transferring information like, for example file size, HTTP server and user agent or MIME type between client and HTTP server.
The button Header listing opens a dialog for defining headers as name/value pairs.
For information about headers refer to the HTTP specification https://www.w3.org/Protocols/HTTP/1.1/rfc2616.pdf.
Connection test
-
Test connection
For testing whether the connection can be successfully established using your configuration.
Dialog RosettaNet Connection Data
(Output Connector only)
Base configuration
-
Server URL
Enter the URL of the servers the connector connects itself to.
-
SSL
For configuring server and client authentication. Refer to Dialog SSL Configuration.
Authentication
-
Authentication required
Activate this option if the server requires an authentication. In this case enter the account which the connector should use.
-
Login name: Username for authentication.
-
Password: Password for authentication.
HTTP header configuration
HTTP headers are used for transferring information like, for example file size, HTTP server and user agent or MIME type between client and HTTP server.
The button Header listing opens a dialog for defining headers as name/value pairs.
For information about headers refer to https://www.w3.org/Protocols/HTTP/1.1/rfc2616.pdf.