Nav

RosettaNet Connector

Premium

The RosettaNet connector provides B2B functionality using the RosettaNet Information Framework (RNIF) for information exchange of Rosetta Partner Interface Process (PIP) messages.

The RosettaNet Connector supports RNIF 2.00.01.

These PIPs are supported:

PIP Version Purpose

0A1

v02.00

Notification of Failure

3A4

3A4MG1 v02.02

Request Purchase Order

3A4

3A4MG2 v02.02

Request Purchase Order

3A6

3A6MG1 v02.00, v02.02, v02.03

Distribute Order Status

3B2

3B2MG1 v01.00

Notify of Advance Shipment

3C3

3C3MG1 v01.00, v01.11

Notify of Invoice

The RosettaNet Connector always uses PIP 0A1 v02.00 for all Failure Notification messages.

Note: Example files are available for download as described in See Also.

Prerequisites

This document assumes that you are familiar with RosettaNet, Mule, Anypoint Connectors, Anypoint Studio, Mule flows, and Mule Global Elements.

See the RosettaNet Release Notes for compatibility information.

To use the RosettaNet connector in a production environment, you must have purchased a MuleSoft license for Anypoint B2B.

What’s New in this Connector

RosettaNet connector 2.x for Mule 4 makes several changes to the configuration and handling over what was implemented by RosettaNet connector 1.x:

  • Metadata supplied automatically for sources (no need for the separate metadata definition component used in 1.x)

  • Simplified flow structure, with separate flows used for each partner and message.

To Install this Connector in Anypoint Studio 7

  1. In Anypoint Studio, click the Exchange icon in the Studio task bar.

  2. Click Login in Anypoint Exchange.

  3. Search for the RosettaNet connector and click Install.

  4. Follow the prompts to install the connector.

To Create a Mule Project in Anypoint Studio 7

After you install the connector you can start using the connector. The first step is to create HTTP Listener and Request definitions for the Mule and partner endpoints used for your message exchanges.

  1. Click the Global Elements tab at the base of the canvas, and click Create.

  2. Under Connector Configuration, find and select HTTP Listener config, and click OK.

  3. In the configuration definition, enter the Host and Port to be used for receiving action and/or signal messages from the trading partner, then click OK.

  4. From the Global Elements tab, again click Create.

  5. Under Connector Configuration, find and select HTTP Request configuration, and click OK.

  6. In the configuration definition, enter the Host and Port to be used for sending action and/or signal messages to the trading partner, then click OK.

  7. Click the Global Elements tab at the base of the canvas, and click Create.

  8. Under Connector Configuration, find and select RosettaNet Config, and click OK.

  9. Fill in the references to the Global HTTP Listener and Global HTTP Request definitions you’ve created, along with the endpoint paths, self/partner identification information, and PIP role and definition path (for the standard PIP definitions provided use paths of the form /{pipId}/{version}.xml, such as /PIP3A4/V02_02.xml).

  10. If your PIP definition uses signed messages you also need to configure the Keystore path and Keystore access password values, and if you’re sending signed messages you also need the Signing key password.

  11. Click OK to save the global connector configurations.

  12. Return to the Message Flow tab in Studio.

  13. Drag and drop RosettaNet components into your flows, selecting the configuration to be used for each component.

Connector components

The RosettaNet connector provides three components for use in your application flows:

  • Action Source - Source for processing action messages received from your partner.

  • Action Sender - Sender for action messages to be transmitted to your partner.

  • Acknowledge Source - Source for processing the completions (whether successful deliveries, exceptions, or failures) of action messages you’ve sent to your partner.

Configuration Details

General tab properties

All configuration properties used by the RosettaNet Connector are on the General tab:

  • Global HTTP Listener - Name of the HTTP Listener configuration to be used for receiving messages from the partner.

  • Service Endpoint Path - Path relative to the HTTP Listener configuration (allowing the same HTTP Listener to be used with different paths for different partners, if desired).

  • Global HTTP Request - Name of the HTTP Request configuration to be used for sending messages to the partner.

  • Request Endpoint Path - Path relative to the HTTP Request configuration (allowing the same HTTP Request to be used with different paths, if desired).

  • Keystore path - Absolute file path or classpath relative to the project /src/main/resources directory for the keystore used for validating and/or signing messages (required when sending or receiving signed messages).

  • Keystore access password - Password used to protect the keystore (required when sending or receiving signed messages).

  • Signing key password - Password used to access the private signing key within the keystore (required when sending signed messages).

  • Force message signing - Optional override to force the use of signed messages even when not required by the PIP definition (NEVER means to use the PIP definition setting, ALWAYS means always signed).

  • Global usage code - Mode to run the connector, one of:

    • Production

    • Test

    • Unchecked

  • Object store reference - Optional reference to an object store definition to be used for storing messages awaiting acknowledgment. If not set, the connector always uses the default persistent object store to retain sent messages waiting for acknowledgments or retries. If set, the referenced bean must be an object store configuration to be used instead. See also: What is an object store bean?

  • Mule DUNS identifier - Dun & Bradstreet Universal Numbering System (DUNS) ID for this organization.

  • Mule location identifier - Location ID of this organization. If specified, this will be included in all messages sent and must be present in all messages received. If not specified, any value present in received messages will be accepted and ignored. Using the location ID also changes the alias used for your key pair in the keystore.

  • Partner DUNS identifier - Dun and Bradstreet Universal Numbering System (DUNS) ID for your trading partner organization.

  • Partner location identifier - Expected location ID for partner organization. If specified, this will be included in all messages sent and must be present in all messages received. If not specified, any value present in received messages will be accepted and ignored. Using the location ID also changes the alias used the partner certificate in the keystore.

  • Role in PIP - Role in Partner Interface Process (PIP) usage, one of:

    • INITIATOR

    • RESPONDER

  • PIP definition path - Absolute file path or classpath relative to the project /src/main/resources directory for the PIP definition XML file. For one of the standard PIP definitions included in the distribution this takes the form /{pipId}/{version}.xml, such as /PIP3A4/V02_02.xml.

Configuration Options in XML

All values listed in the Studio configuration can be set directly in XML:

XML Value Visual Studio Option

globalUsageCode

Global usage code

keystorePass

Keystore access password

keystorePath

Keystore path

listenerConfigName

Global HTTP Listener

objectStore

Object store reference

partnerBusinessIdentifier

Partner DUNS identifier

partnerLocationId

Partner location identifier

pipFile

PIP definition path

pipRole

Role in PIP

privatePass

Signing key password

requestPath

Request Endpoint Path

requesterConfigName

Global HTTP Request

selfBusinessIdentifier

Mule DUNS identifier

selfLocationId

Mule location identifier

servicePath

Service Endpoint Path

signingOverride

Force message signing

About Object Store

The default object store uses the Mule default persistent object store, which means that sent messages may accumulate if not acknowledged, and which may cause retransmissions when you try running again.

You can use the following to define a transient object store for testing and debugging, and reference the object store by name from your RosettaNet configuration.


         
      
1
2
3
4
5
6
7
<mule xmlns:os="http://www.mulesoft.org/schema/mule/os" ...
  http://www.mulesoft.org/schema/mule/os http://www.mulesoft.org/schema/mule/os/current/mule-os.xsd" ...>
  ...
  <os:object-store name="transientStore" persistent="false"/>
  ...
  <rosetta:config name="PO_InitiatorConfig_Buyer" ...
    objectStore="transientStore"/>

When using a persistent object store unacknowledged messages are retained across restarts of the Mule application and are automatically retransmitted when the application restarts (assuming the timeout has expired). All messages are deleted from the object store if the number of retransmissions specified in the PIP definition occurs without an acknowledgment, or after three days time. You can also force unacknowledged messages to be discarded when the Mule application is started by setting the system property:

com.mulesoft.connectors.rosettanet.extension.internal.delivery.DeliveryManager.deleteStore=true

To Customize a PIP

Customizing a PIP allows two types of changes to the PIP configuration:

  • Parameters: Change settings within a PIP version’s XML file.

  • Advanced: Create a custom DTD from which you create an XSD file.

For both paths, put the new or changed files in a directory in your Studio project’s src/main/resources folder.

You can used the supplied PIP configurations as a starting point. These are distributed inside the mule-rosettanet-extension-2.0.0-mule-plugin.jar, which is downloaded by Studio and added to your project under the /target/repository/com/mulesoft/connectors/mule-rosettanet-extension directory and can also be found in the standard MuleSoft enterprise Maven repositories (under group ID com.mulesoft.connectors). Each PIP configuration is in a separate directory (such as PIP3A4) inside the jar. You can copy a PIP directory out of this jar and edit the contents to match your specific needs.

Inside the PIP configuration directory you’ll find an XML file giving the parameters for a particular version of the PIP (such as V02_02.xml). This XML file gives all the details of retry counts, times to acknowledge, and signing requirements for the action(s) defined by the PIP. This file also references DTD and XSD definitions for the actual action messages (both are required, since the DTD is used by RosettaNet and the XSD is used to provide DataSense information inside Mule).

Copy the base PIP definition directory out of the jar and into your Studio project’s src/main/resources folder, changing the name of the copied directory to indicate your customization (such as PIP3A4-custom). Then make your desired changes and use the modified PIP directory name in your RosettaNet Connector configuration (as the pipFile value).

About an Example Use Case

In the following example, a buyer sends a purchase order request. The seller receives the request and sends a purchase order confirmation.

Workflow:

  1. Configure the RosettaNet Connectors properly for the purchase order request and the purchase order confirmation.

  2. Test that the applications work as intended.

About Keystores

RosettaNet uses X.509 certificates to authenticate messages. RosettaNet connector currently only supports storing certificates (and the private keys used for signing) in JKS-format keystores. You can use various tools such as Portecle for working with keystores and creating keys and certificates.

You can download these two example files for use in your application:

For example, partner1.jks, used in the Buyer App example, includes a certificate for partner2 and the private key for partner1 which is used for signing. Keystore aliases have the form: {Partner/Self Business Identifier}[:{Partner/Self Location ID}]

The curly braces surround values and the square brackets show the optional part only used when the Location ID is defined.

In the example that follows, the keystore aliases are:

  • 123456788:partner2

  • 123456789:partner1

About the Purchase Order Example

In this example, you build two Mule applications to mimic the following diagram. You can download the rosettanet-buyer.jar - buyer application and the rosettanet-seller.jar - seller application.

You can run these two applications in a shared domain in Studio, but to show the logged messages clearly, the example uses two Studio applications, one for the buyer app and the other for the seller app.

The following shows the relationships between the buyer and seller applications:

rosettanet-state-diagram

Buyer Application Flows

The buyer application uses three flows to perform these actions:

  1. Receives an input purchase order request document via HTTP POST and sends this as an action message to the seller.

  2. Handles completion of send processing. There are three different types of signals:

    • ACKNOWLEDGE: This signal means the purchase order was successfully received by the seller.

    • EXCEPTION: This signal means the purchase order is sent to the seller, but the seller sent an exception. Among the many reasons, one is an invalid purchase order.

    • FAILURE: This signal means the RosettaNet connector failed to send the purchase order. Each PIP action message has a specified number of retries, and the connector tries to resend the action up to the specified number. If it fails, the connector generates the FAILURE signal.

  3. Receives a purchase order confirmation from the seller.

Topics:

About the Buyer Application Configuration

In the Buyer Application, the following global elements are defined:

  • HTTP Listener for input purchase order request document:

    • Name: HTTP_InputListener

    • Host: localhost

    • Port: 8801

  • HTTP Listener for purchase order confirmation action messages from seller:

    • Name: HTTP_Listener_config

    • Host: localhost

    • Port: 8081

  • HTTP Request for sending purchase order request action messages to seller:

    • Name: HTTP_Request_configuration

    • Host: localhost

    • Port: 8082

  • RosettaNet Connector Configuration

    • Identifiers and PIP information

    • Keystore (partner1.jks) which includes partner1 (buyer) private key and certificate and partner2 (seller) certificate. The keystore is located in the project under src/main/resources

Buyer Application Visual Studio Editor

Configuration in Anypoint Studio using the visual editor:

rosettanet-buyer-visual-flow

Configuration settings for the buyer application:

rosettanet-buyer-config

Buyer Application XML Studio Editor or Standalone

Create your flow using this code:


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:ee="http://www.mulesoft.org/schema/mule/ee/core"
        xmlns:http="http://www.mulesoft.org/schema/mule/http"
        xmlns:rosetta="http://www.mulesoft.org/schema/mule/rosetta"
        xmlns="http://www.mulesoft.org/schema/mule/core"
        xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="
http://www.mulesoft.org/schema/mule/core
http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/rosetta
http://www.mulesoft.org/schema/mule/rosetta/current/mule-rosetta.xsd
http://www.mulesoft.org/schema/mule/http
http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/ee/core
http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.xsd">
        <http:listener-config name="HTTP_Listener_config"
        doc:name="HTTP Listener config" >
                <http:listener-connection host="localhost" port="8081" />
        </http:listener-config>
        <http:request-config name="HTTP_Request_configuration"
        doc:name="HTTP Request configuration">
                <http:request-connection host="localhost" port="8082" />
        </http:request-config>
        <rosetta:config name="PO_InitiatorConfig_Buyer"
        pipRole="INITIATOR" doc:name="RosettaNet Config" listenerConfigName="HTTP_Listener_config"
        servicePath="/partner1"
        requesterConfigName="HTTP_Request_configuration"
        requestPath="/partner2"
        keystorePath="/partner1.jks"
        keystorePass="nosecret"
        privatePass="partner1"
        globalUsageCode="Test"
        selfBusinessIdentifier="123456789"
        selfLocationId="partner1"
        partnerBusinessIdentifier="123456788"
        partnerLocationId="partner2"
        pipFile="/PIP3A4/V02_02.xml"/>
        <http:listener-config name="HTTP_InputListener"
        doc:name="HTTP Listener config" >
                <http:listener-connection host="localhost" port="8801" />
        </http:listener-config>
        <flow name="Send-Purchase-Order-Request" >
                <http:listener doc:name="Listener" config-ref="HTTP_InputListener"
                path="/"
                allowedMethods="POST"/>
                <rosetta:send-action doc:name="Send action"
                 config-ref="PO_InitiatorConfig_Buyer"/>
                <ee:transform doc:name="Transform Message"  >
                        <ee:message >
                                <ee:set-payload ><![CDATA[%dw 2.0
output text/plain
---
"Buyer sent action message " ++ attributes.messageId ++ "\n"]]></ee:set-payload>
                        </ee:message>
                </ee:transform>
        </flow>
        <flow name="Receive-Purchase-Order-Confirmation"  >
                <rosetta:action-source doc:name="Action source"
                config-ref="PO_InitiatorConfig_Buyer"/>
                <logger level="INFO" doc:name="Logger"
                message="Buyer received action message #[attributes.messageId]"/>
        </flow>
        <flow name="Send-Purchase-Order-Completion" >
                <rosetta:completion-source doc:name="Completion"
                config-ref="PO_InitiatorConfig_Buyer"/>
                <logger level="INFO" doc:name="Logger"
                message="Buyer action message #[attributes.replyAttributes.messageId] completed as #[payload.completionCode]"/>
        </flow>
</mule>

To Configure the Seller Application

The seller app performs these actions:

  1. Receives a purchase order request action message from the buyer.

  2. Receives an input purchase order confirmation document via HTTP POST and sends this as an action message to the seller.

  3. Handles completion of send processing. This is the same as for the buyer application, with possible outcomes:

    • ACKNOWLEDGE successfully received by the seller.

    • EXCEPTION

    • FAILURE

Topics:

About the Seller Application Configuration

In the Seller Application, the following global elements are defined:

  • HTTP Listener for input purchase order confirmation document:

    • Name: HTTP_InputListener

    • Host: localhost

    • Port: 8802

  • HTTP Listener for purchase order request action messages from buyer:

    • Name: HTTP_Listener_config

    • Host: localhost

    • Port: 8082

  • HTTP Request for sending purchase order confirmation action messages to seller:

    • Name: HTTP_Request_configuration

    • Host: localhost

    • Port: 8081

  • RosettaNet Connector Configuration

    • Identifiers and PIP information

    • Keystore (partner2.jks) which includes partner2 (seller) private key and certificate and partner2 (buyer) certificate. The keystore is located in the project under src/main/resources

Seller Application Visual Studio Editor

Configuration in Studio:

rosettanet-seller-visual-flow

Configuration settings for the seller application:

rosettanet-seller-config

Seller Application XML Studio Editor or Standalone

Create your flow using this code:


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:ee="http://www.mulesoft.org/schema/mule/ee/core"
        xmlns:http="http://www.mulesoft.org/schema/mule/http"
        xmlns:rosetta="http://www.mulesoft.org/schema/mule/rosetta"
        xmlns="http://www.mulesoft.org/schema/mule/core"
        xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="
http://www.mulesoft.org/schema/mule/core
http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/rosetta
http://www.mulesoft.org/schema/mule/rosetta/current/mule-rosetta.xsd
http://www.mulesoft.org/schema/mule/http
http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/ee/core
http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.xsd">
        <http:listener-config name="HTTP_Listener_config"
        doc:name="HTTP Listener config" >
                <http:listener-connection host="localhost" port="8082" />
        </http:listener-config>
        <http:request-config name="HTTP_Request_configuration"
        doc:name="HTTP Request configuration" >
                <http:request-connection host="localhost" port="8081" />
        </http:request-config>
        <rosetta:config name="PO_ResponderConfig_Seller"
        pipRole="RESPONDER"
        doc:name="RosettaNet Config"
        listenerConfigName="HTTP_Listener_config"
        servicePath="/partner2"
        requesterConfigName="HTTP_Request_configuration"
        requestPath="/partner1"
        keystorePath="/partner2.jks"
        keystorePass="nosecret"
        privatePass="partner2"
        globalUsageCode="Test"
        partnerBusinessIdentifier="123456789"
        partnerLocationId="partner1"
        selfBusinessIdentifier="123456788"
        selfLocationId="partner2" pipFile="/PIP3A4/V02_02.xml"/>
        <http:listener-config name="HTTP_InputListener"
        doc:name="HTTP Listener config" >
                <http:listener-connection host="localhost" port="8802" />
        </http:listener-config>
        <flow name="Send-Purchase-Order-Confirmation">
                <http:listener doc:name="Listener"
                config-ref="HTTP_InputListener"
                path="/" allowedMethods="POST"/>
                <rosetta:send-action doc:name="Send action"
                 config-ref="PO_ResponderConfig_Seller"/>
                <ee:transform doc:name="Transform Message">
                        <ee:message >
                                <ee:set-payload ><![CDATA[%dw 2.0
output text/plain
---
"Seller sent action message " ++ attributes.messageId ++ "\n"]]></ee:set-payload>
                        </ee:message>
                </ee:transform>
        </flow>
        <flow name="Receive-Purchase-Order-Request">
                <rosetta:action-source doc:name="Action source"
                config-ref="PO_ResponderConfig_Seller"/>
                <logger level="INFO" doc:name="Logger"
                 message="Seller received action message #[attributes.messageId]"/>
        </flow>
        <flow name="Send-Purchase-Order-Completion">
                <rosetta:completion-source doc:name="Completion"
                config-ref="PO_ResponderConfig_Seller"/>
                <logger level="INFO" doc:name="Logger"
                message="Seller action message #[attributes.replyAttributes.messageId] completed as #[payload.completionCode]"/>
        </flow>
</mule>

To Send a Purchase Order Request

After you run the Buyer and Seller applications, you need to use an HTTP POST to the HTTP_InputListener endpoint to provide the purchase order request document to be sent to the seller.

You can download a sample purchase order request. You can then use any HTTP tool (such as a browser plugin, standalone tool such as PostMan, or a console tool such as curl to POST the data to the buyer application.

For example, here’s a curl command line to do this:

curl -v -H "Content-Type: application/text" -XPOST --data-binary @sample-purchase-order-request-content.xml http://localhost:8801

The RosettaNet Connector generates a RosettaNet message based on the purchase order request document and sends it to the seller, responding to the HTTP POST operation with a message identifier. In your console you should output like:


          
       
1
2
INFO  ... Seller received action message pMAIhTBMsGzAf/NFx83KBO9nt+T+DV2RNLhwlpNqnXM=0
INFO  ... Buyer action message pMAIhTBMsGzAf/NFx83KBO9nt+T+DV2RNLhwlpNqnXM=0 completed as SUCCESS

To Send a Purchase Order Confirmation

Just as with the buyer application and the purchase order request document, you’ll need to use an HTTP POST to the seller HTTP_InputListener endpoint to provide the purchase order confirmation document to be sent to the buyer.

You can download a sample purchase order confirmation, and again use any HTTP tool to POST the data to the seller application.

For example, here’s a curl command line to do this:

curl -v -H "Content-Type: application/text" -XPOST --data-binary @sample-purchase-order-confirmation-content.xml http://localhost:8802

The RosettaNet Connector generates a RosettaNet message based on the purchase order confirmation document and sends it to the buyer, responding to the HTTP POST operation with a message identifier. In your console you should output like:


          
       
1
2
INFO  ... Buyer received action message ng7+TalLLPTJZHok4tQSBi8RYZD8IsD9+iB85cubzM=1
INFO  ... Seller action message sng7+TalLLPTJZHok4tQSBi8RYZD8IsD9+iB85cubzM=1 completed as SUCCESS

Note that the purchase order confirmation action sent by this sample application is only an example. To send a real purchase order confirmation you’d need to configure the replyAttributes on the RosettaNet send-action operation with the information provided by when you received the corresponding purchase order request document. These replayAttributes are what allow the RosettaNet protocol to distinguish between possibly many concurrent requests.

Digging Deeper

If you’re interested in seeing the details of the RosettaNet protocol exchanges you can turn on TRACE logging in the /src/main/resources/log4j2.xml logging configuration files, adding a line like:


          
       
1
2
3
4
5
<Loggers>
    ...
    <AsyncLogger name="com.mulesoft.connectors.rosettanet.extension" level="TRACE"/>
    ...
</Loggers>

We use cookies to make interactions with our websites and services easy and meaningful, to better understand how they are used and to tailor advertising. You can read more and make your cookie choices here. By continuing to use this site you are giving us your consent to do this.

+