diff --git a/rosettanet/2.2/modules/ROOT/pages/index.adoc b/rosettanet/2.2/modules/ROOT/pages/index.adoc index f3d726c499..05eb50fafb 100644 --- a/rosettanet/2.2/modules/ROOT/pages/index.adoc +++ b/rosettanet/2.2/modules/ROOT/pages/index.adoc @@ -1,5 +1,4 @@ = RosettaNet Connector -:page-aliases: connectors::rosettanet/rosettanet-connector.adoc Support Category: Premium diff --git a/rosettanet/2.2/modules/ROOT/pages/rosettanet-connector-reference.adoc b/rosettanet/2.2/modules/ROOT/pages/rosettanet-connector-reference.adoc index ca639a2caa..b7f44d845d 100644 --- a/rosettanet/2.2/modules/ROOT/pages/rosettanet-connector-reference.adoc +++ b/rosettanet/2.2/modules/ROOT/pages/rosettanet-connector-reference.adoc @@ -1,5 +1,4 @@ = RosettaNet Connector 2.2 Reference -:page-aliases: connectors::rosettanet/rosettanet-connector-reference.adoc Anypoint Connector for RosettaNet (Rosettanet Connector) provides B2B functionality that uses the RosettaNet Information Framework (RNIF) for the information exchange of RosettaNet Partner Interface Process (PIP) messages. diff --git a/rosettanet/3.0/antora.yml b/rosettanet/3.0/antora.yml new file mode 100644 index 0000000000..7a8c94b373 --- /dev/null +++ b/rosettanet/3.0/antora.yml @@ -0,0 +1,18 @@ +name: rosettanet-connector +version: '3.0' +display_version: 3.0 (Mule 4) +title: RosettaNet Connector +nav: +- modules/ROOT/nav.adoc +asciidoc: + attributes: + page-component-desc: Provides B2B functionality using the RosettaNet Information Framework (RNIF) for information exchange of Rosetta Partner Interface Process (PIP) messages. + page-connector-type: Connector + page-connector-level: Premium + page-exchange-group-id: com.mulesoft.connectors + page-exchange-asset-id: mule-rosettanet-connector + page-runtime-version: 4.1.1 + page-release-notes-page: release-notes::connector/rosettanet-connector-release-notes-mule-4.adoc + page-vendor-name: rosettanet + page-vendor-title: RosettaNet + page-notice-banner-message: Standard support for Java 8 and 11 ends in August 2026 for 4.6 LTS. Plan your upgrade path for apps that are running on Java 8 or 11 accordingly. diff --git a/rosettanet/3.0/modules/ROOT/image-source-files/rosettanet-buyer-visual-flow.graffle b/rosettanet/3.0/modules/ROOT/image-source-files/rosettanet-buyer-visual-flow.graffle new file mode 100644 index 0000000000..47757584a3 Binary files /dev/null and b/rosettanet/3.0/modules/ROOT/image-source-files/rosettanet-buyer-visual-flow.graffle differ diff --git a/rosettanet/3.0/modules/ROOT/image-source-files/rosettanet-seller-visual-flow.graffle b/rosettanet/3.0/modules/ROOT/image-source-files/rosettanet-seller-visual-flow.graffle new file mode 100644 index 0000000000..e7c3287648 Binary files /dev/null and b/rosettanet/3.0/modules/ROOT/image-source-files/rosettanet-seller-visual-flow.graffle differ diff --git a/rosettanet/3.0/modules/ROOT/images/rosettanet-buyer-config.png b/rosettanet/3.0/modules/ROOT/images/rosettanet-buyer-config.png new file mode 100644 index 0000000000..6d09edae2f Binary files /dev/null and b/rosettanet/3.0/modules/ROOT/images/rosettanet-buyer-config.png differ diff --git a/rosettanet/3.0/modules/ROOT/images/rosettanet-buyer-visual-flow.png b/rosettanet/3.0/modules/ROOT/images/rosettanet-buyer-visual-flow.png new file mode 100644 index 0000000000..d4eea4476f Binary files /dev/null and b/rosettanet/3.0/modules/ROOT/images/rosettanet-buyer-visual-flow.png differ diff --git a/rosettanet/3.0/modules/ROOT/images/rosettanet-connector-upgrade-fips140-2-config.png b/rosettanet/3.0/modules/ROOT/images/rosettanet-connector-upgrade-fips140-2-config.png new file mode 100644 index 0000000000..b908bcaedc Binary files /dev/null and b/rosettanet/3.0/modules/ROOT/images/rosettanet-connector-upgrade-fips140-2-config.png differ diff --git a/rosettanet/3.0/modules/ROOT/images/rosettanet-connector-upgrade-fips140-3-config.png b/rosettanet/3.0/modules/ROOT/images/rosettanet-connector-upgrade-fips140-3-config.png new file mode 100644 index 0000000000..08ee9421e0 Binary files /dev/null and b/rosettanet/3.0/modules/ROOT/images/rosettanet-connector-upgrade-fips140-3-config.png differ diff --git a/rosettanet/3.0/modules/ROOT/images/rosettanet-connector-upgrade-global-element-config.png b/rosettanet/3.0/modules/ROOT/images/rosettanet-connector-upgrade-global-element-config.png new file mode 100644 index 0000000000..16796c1303 Binary files /dev/null and b/rosettanet/3.0/modules/ROOT/images/rosettanet-connector-upgrade-global-element-config.png differ diff --git a/rosettanet/3.0/modules/ROOT/images/rosettanet-connector-upgrade-non-fips-config.png b/rosettanet/3.0/modules/ROOT/images/rosettanet-connector-upgrade-non-fips-config.png new file mode 100644 index 0000000000..2f008b6e8c Binary files /dev/null and b/rosettanet/3.0/modules/ROOT/images/rosettanet-connector-upgrade-non-fips-config.png differ diff --git a/rosettanet/3.0/modules/ROOT/images/rosettanet-seller-visual-flow.png b/rosettanet/3.0/modules/ROOT/images/rosettanet-seller-visual-flow.png new file mode 100644 index 0000000000..b52788c396 Binary files /dev/null and b/rosettanet/3.0/modules/ROOT/images/rosettanet-seller-visual-flow.png differ diff --git a/rosettanet/3.0/modules/ROOT/images/rosettanet-state-diagram.png b/rosettanet/3.0/modules/ROOT/images/rosettanet-state-diagram.png new file mode 100644 index 0000000000..0ad44b1fa0 Binary files /dev/null and b/rosettanet/3.0/modules/ROOT/images/rosettanet-state-diagram.png differ diff --git a/rosettanet/3.0/modules/ROOT/nav.adoc b/rosettanet/3.0/modules/ROOT/nav.adoc new file mode 100644 index 0000000000..a638f1d49b --- /dev/null +++ b/rosettanet/3.0/modules/ROOT/nav.adoc @@ -0,0 +1,5 @@ +.xref:index.adoc[RosettaNet Connector] +* xref:index.adoc[RosettaNet Connector Overview] +* xref:rosettanet-connector-upgrade-migrate.adoc[RosettaNet Connector Upgrade and Migrate] +* xref:rosettanet-connector-examples.adoc[RosettaNet Connector Examples] +* xref:rosettanet-connector-reference.adoc[RosettaNet Connector Reference] diff --git a/rosettanet/3.0/modules/ROOT/pages/index.adoc b/rosettanet/3.0/modules/ROOT/pages/index.adoc new file mode 100644 index 0000000000..f3d726c499 --- /dev/null +++ b/rosettanet/3.0/modules/ROOT/pages/index.adoc @@ -0,0 +1,212 @@ += RosettaNet Connector +:page-aliases: connectors::rosettanet/rosettanet-connector.adoc + +Support Category: Premium + +The RosettaNet connector provides B2B functionality using the RosettaNet Information Framework (RNIF) for the information exchange of Rosetta Partner Interface Process (PIP) messages. + +The RosettaNet Connector supports RNIF 2.00.01. + +The following PIPs are supported: + +[%header,cols="10s,20a,70a"] +|=== +|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 <>. + +== Before You Begin + +This document assumes that you are familiar with RosettaNet, Mule, Anypoint +Connectors, Anypoint Studio, Mule flows, and Mule Global Elements. + +See the xref:release-notes::connector/rosettanet-connector-release-notes-mule-4.adoc[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. +* Additional validations are now performed on the keystore usage to address reported security vulnerabilities. + +== Install this Connector in Anypoint Studio 7 + +. In Studio, create a Mule Project. +. Click the Exchange *(X)* icon in the Studio task bar. +. In Exchange, click *Login* and supply your Anypoint Platform username and password. +. In Exchange, select *All assets* and search for "RosettaNet". +. Select RosettaNet, click *Add to project*. +. Follow the prompts to install the connector. + +== 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. + +. Click the Global Elements tab at the base of the canvas, and click *Create*. +. Under Connector Configuration, find and select HTTP Listener config, and click *OK*. +. 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*. +. From the Global Elements tab, again click *Create*. +. Under *Connector Configuration*, find and select HTTP Request configuration, and click *OK*. +. 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*. +. Click the *Global Elements* tab at the base of the canvas, and click *Create*. +. Under *Connector Configuration*, find and select *RosettaNet Config*, and click *OK*. +. 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`). +. 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`. +. Click *OK* to save the global connector configurations. +. Return to the *Message Flow* tab in Studio. +. Drag 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 app 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 + +image::rosettanet-buyer-config.png[General tab properties] + +All configuration properties used by the RosettaNet connector are in the Studio General tab: + +[%header,cols="30s,70a"] +|=== +|Configuration Property |Description +| 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. Leave this value empty to the PIP definition for signing messages, set to `NEVER` to never sign any messages, or set to `ALWAYS` to always sign messages. +| 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 connector uses the referenced object store configuration instead. +| Mule DUNS identifier |Dun & Bradstreet Universal Numbering System (DUNS) ID for this organization. +| Mule location identifier |Location ID of this organization. If specified, this is 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 is 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: + +[%header%autowidth.spread] +|=== +|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 +|=== + +== 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. + +[source,xml,linenums] +---- + + ... + + ... + +---- + +When using a persistent object store unacknowledged messages are retained across restarts of the Mule app and are automatically retransmitted when the app 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 app is started by setting the system property: + +`com.mulesoft.connectors.rosettanet.extension.internal.delivery.DeliveryManager.deleteStore=true` + +== 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). + +== 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. + +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 that is used only when the Location ID is defined. + +=== Dig 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: + +[source,xml,linenums] +---- + + ... + + ... + +---- + +== See Also + +* xref:release-notes::connector/rosettanet-connector-release-notes-mule-4.adoc[RosettaNet Connector Release Notes] +* https://trailhead.salesforce.com/trailblazer-community/neighborhoods/mulesoft[MuleSoft Trailblazer Community] + +Example Files: + +* https://s3-us-west-2.amazonaws.com/mulesoft-sites-vendorcontent/public-assets/sample-purchase-order-request-content.xml[sample-purchase-order-request-content.xml] +* https://s3-us-west-2.amazonaws.com/mulesoft-sites-vendorcontent/public-assets/sample-purchase-order-confirmation-content.xml[sample-purchase-order-confirmation-content.xml] +* https://s3-us-west-2.amazonaws.com/mulesoft-sites-vendorcontent/public-assets/partner1.jks[partner1.jks] +* https://s3-us-west-2.amazonaws.com/mulesoft-sites-vendorcontent/public-assets/partner2.jks[partner2.jks] +* https://s3-us-west-2.amazonaws.com/mulesoft-sites-vendorcontent/public-assets/rosetta-buyer.jar[rosetta-buyer.jar] +* https://s3-us-west-2.amazonaws.com/mulesoft-sites-vendorcontent/public-assets/rosetta-seller.jar[rosetta-seller.jar] diff --git a/rosettanet/3.0/modules/ROOT/pages/rosettanet-connector-examples.adoc b/rosettanet/3.0/modules/ROOT/pages/rosettanet-connector-examples.adoc new file mode 100644 index 0000000000..7c2d8bb6bb --- /dev/null +++ b/rosettanet/3.0/modules/ROOT/pages/rosettanet-connector-examples.adoc @@ -0,0 +1,510 @@ += RosettaNet Connector Examples + +Mule applications using Anypoint Connector for RosettaNet (RosettaNet Connector) must include a global configuration to add external libraries specific to the active security mode. Only one external libs configuration is permitted per application, so you must configure this element manually in the examples. + +This example consists of two apps: + +* The Buyer app sends a purchase order request message to a Seller App. +* The Seller app sends a purchase order confirmation message to the Buyer app when the order is fulfilled. + + The following section provide instructions for configuring the global element for external libraries and it needs to be done for each application. + +[[configure-external-libraries]] +== Configure a Global Element for External Libraries + +Mule applications using RosettaNet Connector must contain only one global element configuration to provide the external libraries required for the selected security mode. + +To configure the global element for RosettaNet Connector and add external libraries, follow these steps: + +. In *Package Explorer* or Anypoint Studio canvas, open your Mule flow or configuration. +. Click *Global Elements*. Or click *Create global element*, and then click the plus icon next to Global Elements. +. Click *Create*, and then search for the `RosettaNet` or `External Libs` option and select *RosettaNet External Libs - Non FIPS*. +. Name the configuration. +. Click *Configure* > *Add recommended libraries*. +. Click *OK* to include the libraries as dependencies and shared libraries in the Mule application `pom.xml` file. +. Verify that your project has the required dependencies for your security mode. ++ +Add the dependencies via Maven if they aren't added automatically. + +For configuration instructions for other security modes, see xref:rosettanet-connector::rosettanet-connector-upgrade-migrate.adoc#configure-external-libraries[Configure External Libraries]. + + +The following diagram shows the relationship between the two apps: + +image::rosettanet-state-diagram.png[Relationship between the Buyer and Seller apps] + +== Buyer App + +The Buyer app performs the following actions: + +. Receives an input purchase order request document via an `HTTP POST`. +. Uses the RosettaNet *Send action* operation to send a purchase order request message to the Seller app. +. Transforms the message ID from the purchase order request message to plain text for use in responding to the `HTTP POST`. +. Receives an acknowledgment signal from the Seller app and logs information about the signal. +. Receives a purchase order confirmation message from the seller and logs information about the confirmation message. +. Receives the completion state from the Seller app and logs information about the completion state. + +The following screenshot shows the Anypoint Studio app flows for the Buyer app: + +image::rosettanet-buyer-visual-flow.png[Studio flow for the Buyer app] + +NOTE: The keystore for the Buyer app, which includes the buyer private key, buyer certificate, and seller certificate is located in the project under `src/main/resources`. + +=== Create the First Flow of the Buyer App + +The first flow of the Buyer app receives a purchase order request document via an `HTTP POST` and sends this as a RosettaNet action message to the Seller app. Configuring this flow involves creating a new Mule project, configuring the *HTTP Listener* source, adding a *Send action* operation, and adding a *Transform* component. + +==== Configure the HTTP Listener Source + +Configure the *HTTP Listener* source to initiate a Mule flow when a call is made to the default path (`/`): + +. Create a new Mule project in Studio. +. From the *Mule Palette* view, select *HTTP* and drag the *Listener* component to the canvas. +. In the properties window, click *+* next to the *Connector configuration* field to add a global element. +. In the *Name* field, enter `HTTP_InputListener` and accept the default values. + +==== Add the PO_InitiatorConfig_Buyer Global Element + +Add the `PO_InitiatorConfig_Buyer` global element for the *Send action* operation: + +. In the properties window for the *Send action* operation, click *+* next to the *Module configuration* field to add a global element. +. In the *RosettaNet Config* window, complete the following fields: ++ +[%header%autowidth.spread] +|=== +|Global HTTP Listener|HTTP_Listener-config +|Service Endpoint Path|/partner1 +|Global HTTP Request|HTTP_Request_configuration +|Request Endpoint Path|/partner2 +|Keystore Path |/partner1.jks +|Keystore Access password |nosecret +|Signing key password |partner1 +|Global usage code |Test +|Mule DUNS identifier|123456789 +|Mule location identifier | partner1 +|Partner DUNS identifier | 123456788 +|Partner location identifier | partner2 +|role in PIP | INITIATOR +|PIP definition path | /PIP3A4/V02_02.xml +|=== ++ +. Click *OK*. + +==== Add the Send Action Operation + +Add the *Send action* operation to send the purchase order request message to the Seller app by using the configuration defined for the `PO_InitiatorConfig_Buyer` global element: + +. From the *Mule Palette* view, select *RosettaNet* and drag the *Send action* operation next to *Listener*. +. In the properties window, complete the following fields: ++ +[%header%autowidth.spread] +|=== +|Field|Value +|Display Name|Send action +|Module configuration|PO_InitiatorConfig_Buyer +|=== + +==== Add a Transform Message Component + +Add a *Transform Message* component to transform the message ID in the purchase order request message to plain text: + +. From the *Mule Palette* view, select *Core* and drag a *Transform Message* component next to *Send action*. +. In the properties window, overlay the brackets in the *Output* section with this DataWeave code: ++ +[source,dataweave,linenums] +---- +%dw 2.0 +output text/plain +--- +"Buyer sent action message " ++ attributes.messageId ++ "\n" +---- + +=== Create the Second Flow of the Buyer App + +The second flow of the Buyer app receives an acknowledgment signal from the Seller app and logs information about the signal. It also receives the purchase order confirmation message from the Seller app and logs information about the message. + +==== Configure the Action Source + +Configure the *Action source* source to initiate a Mule flow when a call is made to the `/partner2` path: + +. From the *Mule Palette* view, select *Rosettanet* and drag the *Action source* source to the canvas. +. In the *Module configuration* field, enter `PO_InitiatorConfig_Buyer`. + +==== Add a Logger Component + +Add a *Logger* component to log a message that includes information about the acknowledgment and purchase order confirmation message: + +. From the *Mule Palette* view, select *Core* and drag a *Logger* component next to *Action source* on the canvas. +. In the *Message* field, enter the following text: ++ +`"Buyer received action message #[attributes.messageId]"` + +=== Create the Third Flow of the Buyer App + +The third flow of the Buyer app receives the completion state from the Seller app and logs information about the completion state. + +==== Configure the Completion Source + +Configure the *Completion source* source to listen for a purchase order completion state message from the seller: + +. From the *Mule Palette* view, select *Rosettanet* and drag the *Completion source* source to the canvas. +. In the *Module configuration* field, enter `PO_InitiatorConfig_Buyer`. + +==== Add a Logger Component + +Add a *Logger* component to log information about the purchase order completion state: + +. From the *Mule Palette* view, select *Core* and drag a *Logger* component next to *Completion source* on the canvas. +. In the *Message* field, enter the following text: ++ +`Buyer action message #[attributes.replyAttributes.messageId] completed as #[payload.completionCode]` + +==== Save and Run the App + +To save the app, click *File > Save*. + +To run the app, click *Run > Run as > Mule Application*. + +==== XML for the Buyer App + +Paste this code into the Studio XML editor to quickly load the flow for the Buyer app into your Mule app: + +[source,xml,linenums] +---- + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +---- + +== Seller App + +The Seller app performs the following actions: + +. Receives an input purchase order request confirmation document via an `HTTP POST`. +. Uses a RosettaNet *Send action* operation to send a purchase order confirmation message to the buyer. +. Transforms the RosettaNet message ID from the purchase order confirmation message to plain text for use in responding to the `HTTP POST`. +. Receives a purchase order request message from the Buyer app and logs information about the request message. +. Receives an acknowledgment signal from the Buyer app and logs information about the signal. +. Receives a completion state message from the Buyer app and logs information about the completion state message. + +The following screenshot shows the Anypoint Studio app flows for the Seller app: + +image::rosettanet-seller-visual-flow.png[Studio flow for the Seller app] + +NOTE: The keystore in the Seller app, which includes the seller private key, seller certificate, and buyer certificate is located in the project under `src/main/resources`. + +=== Create the First Flow of the Seller App + +The first flow of the Seller app receives a purchase order request confirmation document via `HTTP POST` and sends this as a RosettaNet action message to the Buyer app. Configuring this flow involves creating a new Mule project, configuring the *HTTP Listener* source, configuring the RosettaNet *Send action* operation, and adding a *Transform* component. + +==== Configure the HTTP Listener Source + +Configure the *HTTP Listener* source to initiate a Mule flow when a call is made to the default path (`/`): + +. Create a new Mule project in Studio. +. From the *Mule Palette* view, select *HTTP* and drag the Listener component to the canvas. +. In the properties window, click *+* next to the Connector configuration field to add a global element. +. In *Name*, enter `HTTP_InputListener`. +. In *Port*, enter `8082`. +. In *Read timeout*, enter `3000`. + +==== Add a Global Element for the Send Action Operation + +Create a global element named `PO_ResponderConfig_Seller` for the *Send action* operation. + +. In the properties window for the *Send action* operation, click *+* next to the *Module configuration* field to add a global element. +. In the *RosettaNet Config* window, configure the following fields: ++ +[%header%autowidth.spread] +|=== +|Field|Value +|Global HTTP Listener|HTTP_Listener-config +|Service Endpoint Path|/partner2 +|Global HTTP Request|HTTP_Request_configuration +|Request Endpoint Path|/partner1 +|Keystore Path |/partner2.jks +|Keystore Access password |nosecret +|Signing key password |partner2 +|Global usage code |Test +|Mule DUNS identifier|123456788 +|Mule location identifier | partner2 +|Partner DUNS identifier | 123456789 +|Partner location identifier | partner1 +|role in PIP | RESPONDER +|PIP definition path | /PIP3A4/V02_02.xml +|=== +. Click *OK*. + +==== Add the Send Action Operation + +Add the *Send action* operation to send a purchase order confirmation message to the Buyer app: + +. From the *Mule Palette* view, select *RosettaNet* and drag the *Send action* operation next to *Listener*. +. In the properties window, configure the following fields: ++ +[%header%autowidth.spread] +|=== +|Field|Value +|Display Name|Send action +|Module configuration|PO_ResponderConfig_Seller +|=== ++ +. Click *OK*. + +==== Add a Transform Message Component + +Add a *Transform Message* component to transform the message ID from the purchase order confirmation message for use in responding to the `HTTP POST`. + +. From the *Mule Palette* view, select *Core* and drag a *Transform Message* component next to *Send action* on the canvas. +. In the properties window, overlay the brackets in the *Output* section with this DataWeave code: ++ +[source,dataweave,linenums] +---- +%dw 2.0 +output text/plain +--- +"Seller sent action message " ++ attributes.messageId ++ "\n" +---- + +=== Create the Second Flow of the Seller App + +The second flow of the Seller app receives an acknowledgment signal from the Buyer app and logs information about the signal. It also receives a purchase order request message from the Buyer app and logs information about the request. + +==== Configure the Action Source + +Configure the *Action* source to initiate a Mule flow when a call is made to the default path (`/`): + +. From the *Mule Palette* view, select *Rosettanet* and drag the *Action source* source to the canvas. +. In the *Module configuration* field, enter `PO_ResponderConfig_Seller`. + +==== Add a Logger Component + +Add a *Logger* component to log information about the acknowledgment signal and purchase order request message: + +. From the *Mule Palette* view, select *Core* and drag a *Logger* component next to *Completion source* on the canvas. +. In the *Message* field, enter the following text: ++ +`Seller received action message #[attributes.messageId]` + +=== Create the Third Flow of the Seller App + +The third flow of the Seller app sends a purchase order completion state message to the Buyer app and logs information about the purchase order completion state message. Configuring this flow involves configuring the *Action* source and adding a *Logger* component. + +==== Configure the Action Source + +Configure the *Action* source to receive the completion state from the Buyer app. + +==== Adding a Logger Component + +Add a *Logger* component to log information about the purchase order state completion message. + +. From the *Mule Palette* view, select *Core* and drag a *Logger* component next to *Action source* on the canvas. +. In the *Message* field, enter the following text: ++ +`Seller action message #[attributes.replyAttributes.messageId] completed as #[payload.completionCode]` + +==== Save and Run the App + +To save the app, click *File > Save*. + +To run the app, click *Run > Run as > Mule Application*. + +=== XML for the Seller App + +Paste this code into the Studio XML editor to quickly load the flow for the Seller app into your Mule app: + +[source,xml,linenums] +---- + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +---- + +== Test the Examples + +To test the Buyer and Seller apps, do the following after you run the apps: + +. Provide the purchase order request to the Buyer app. +. Provide the purchase order request response to the Seller app. + +=== Provide the Purchase Order Request Document + +Use an HTTP POST to the Buyer app `HTTP_InputListener` endpoint to provide the purchase order request to send to the seller. + +You can download a https://s3-us-west-2.amazonaws.com/mulesoft-sites-vendorcontent/public-assets/sample-purchase-order-request-content.xml[sample purchase order request]. You can then use any HTTP tool, such as a browser plugin, standalone tool such as PostMan, or console tool such as `curl` to POST the data to the Buyer app. + +For example, the following `curl` command posts a purchase order request: + +`+curl -v -H "Content-Type: application/xml" -XPOST --data-binary @sample-purchase-order-request-content.xml http://localhost:8801+` + +RosettaNet Connector generates a RosettaNet message based on the purchase order request and sends it to the seller, responding to the HTTP POST operation with a message identifier. In your console, your output should look like this: + +[source,java,linenums] +---- +INFO ... Seller received action message pMAIhTBMsGzAf/NFx83KBO9nt+T+DV2RNLhwlpNqnXM=0 +INFO ... Buyer action message pMAIhTBMsGzAf/NFx83KBO9nt+T+DV2RNLhwlpNqnXM=0 completed as SUCCESS +---- + +=== Provide the Purchase Order Confirmation Document + +Use an HTTP POST to the Seller app `HTTP_InputListener` endpoint to provide the purchase order confirmation to send to the buyer. + +You can download a https://s3-us-west-2.amazonaws.com/mulesoft-sites-vendorcontent/public-assets/sample-purchase-order-confirmation-content.xml[sample purchase order confirmation] and then use any HTTP tool to post the data to the Seller app. + +For example, the following `curl` command posts a purchase order confirmation: + +`+curl -v -H "Content-Type: application/xml" -XPOST --data-binary @sample-purchase-order-confirmation-content.xml http://localhost:8802+` + +RosettaNet Connector generates a RosettaNet message based on the purchase order confirmation and sends it to the buyer, responding to the HTTP POST operation with a message identifier. In your console, your output should look like this: + +[source,java,linenums] +---- +INFO ... Buyer received action message ng7+TalLLPTJZHok4tQSBi8RYZD8IsD9+iB85cubzM=1 +INFO ... Seller action message sng7+TalLLPTJZHok4tQSBi8RYZD8IsD9+iB85cubzM=1 completed as SUCCESS +---- + +The purchase order confirmation action sent by this sample app is only an example. To send a real purchase order confirmation, you must configure the `replyAttributes` on the RosettaNet `send-action` operation with the information provided by when you received the corresponding purchase order request. These `replayAttributes` enable the RosettaNet protocol to distinguish between many concurrent requests. + +== See Also + +* xref:connectors::introduction/introduction-to-anypoint-connectors.adoc[Introduction to Anypoint Connectors] +* https://help.salesforce.com[Salesforce Help] \ No newline at end of file diff --git a/rosettanet/3.0/modules/ROOT/pages/rosettanet-connector-reference.adoc b/rosettanet/3.0/modules/ROOT/pages/rosettanet-connector-reference.adoc new file mode 100644 index 0000000000..c10745ac4f --- /dev/null +++ b/rosettanet/3.0/modules/ROOT/pages/rosettanet-connector-reference.adoc @@ -0,0 +1,331 @@ += RosettaNet Connector 3.0 Reference +:page-aliases: connectors::rosettanet/rosettanet-connector-reference.adoc + +Anypoint Connector for RosettaNet (Rosettanet Connector) provides B2B functionality that uses the RosettaNet Information Framework (RNIF) for the information exchange of RosettaNet Partner Interface Process (PIP) messages. + +Release Notes: xref:release-notes::connector/rosettanet-connector-release-notes-mule-4.adoc[RosettaNet Connector Release Notes] + +[[config]] +== Configurations + +Configuration for RosettaNet Connector. + +=== Parameters +[%header,cols="20s,20a,35a,20a,5a"] +|=== +| Name | Type | Description | Default Value | Required +|Name | String | Name of this configuration. Connectors reference the configuration with this name. | | x +| Global HTTP Listener a| String | Reference to the global HTTP Listener definition for the service endpoint used by the partner for action and signal messages.| | x +| Service Endpoint Path a| String | Service endpoint path, appended to the base path of HTTP Listener.| | x +| Global HTTP Request a| String | Global HTTP request definition for the partner service endpoint. This value is used when sending action and signal messages. | | x +| Request Endpoint Path a| String | Partner endpoint path, appended to the base path on an HTTP request. | | x +| Require secure transport a| Boolean | When HTTPS is active, the system verifies its usage and records the *isSecureTransportRequired* field in the `DeliveryHeader` as *Yes*. An error is generated for any insecure channels detected during messaging between partners. | false | +| Keystore path a| String | Keystore that contains trusted partner certificates and the connector's private signing key and certificate (JKS format).| | +| Keystore access password a| String | Access password for the keystore. | | +| Signing key password a| String | Private signing key password (required if signing action and signal messages). | | +| Override message signing a| Enumeration, one of: + +** ALWAYS +** NEVER | Turns message signing on or off. Setting this value to `ALWAYS` overrides the signing configured by the PIP definition. | | +| Signing algorithm| Enumeration, one of: + +** SHA256 +** SHA1 | Algorithm used to sign S/MIME messages. | SHA1 | +| Global usage code a| Enumeration, one of: + +** Test +** Production | Whether to operate in test mode or production mode.| `Production`| +a| Object store reference a| Object Store | Object store configuration reference: + +* If specified, the connector uses the referenced object store configuration to retain sent messages for acknowledgments and retries. +* If not specified, the connector uses the default persistent object store to retain sent messages for acknowledgments and retries. +| | +| Mule DUNS identifier a| String | DUNS business identifier for the organization. | | x +a| Mule location identifier a| String | Location identifier for the organization: + +* If specified, this value is included in all sent messages and verified in all received messages. +* If not specified, no value is sent, and received values are ignored. | | +| Partner DUNS identifier a| String | Expected DUNS business identifier for the partner organization.| | x +| Partner location identifier a| String | Expected location identifier for the partner organization. + +* If specified, this value is included in all sent messages and verified in all received messages. +* If not specified, no value is sent and received values are ignored. | | +| Role in PIP a| Enumeration, one of: + +** INITIATOR +** RESPONDER | Connector's role in the PIP. | | x +| PIP definition path a| String | PIP file path.| | x +| Expiration Policy a| <> | Configures the minimum amount of time that a dynamic configuration instance can remain idle before Mule considers it eligible for expiration. +This does not mean that the platform expires the instance at the exact moment that it becomes eligible. Mule purges the instances as appropriate.| | +|=== + +== Sources +* <> +* <> + +[[actionSource]] +=== Action source +`` + +==== Parameters +[%header,cols="20s,20a,35a,20a,5a"] +|=== +| Name | Type | Description | Default Value | Required +| Configuration | String | Name of the configuration to use. | | x +| Primary Node Only a| Boolean | Determines whether to execute this source on only the primary node when running Mule instances in a cluster.| | +| Streaming Strategy a| * <> +* <> + +* <> | Configures how Mule processes streams. By default, Mule uses repeatable streams. | | +| Redelivery Policy a| <> | Configures a policy for processing the redelivery of the same message. | | +|=== + +==== Output +[%autowidth.spread] +|=== + +|Type |Binary +| Attributes Type a| <> +|=== + +==== For Configurations +* <> + +[[completionSource]] +=== Completion source +`` + +==== Parameters +[%header,cols="20s,20a,35a,20a,5a"] +|=== +| Name | Type | Description | Default Value | Required +| Configuration | String | Name of the configuration to use. | | x +| Primary Node Only a| Boolean | Whether this source should be executed only on the primary node when running in a cluster. | | +| Redelivery Policy a| <> | Configures a policy for processing the redelivery of the same message. | | +|=== + +==== Output +[%autowidth.spread] +|=== +|Type |<> +| Attributes Type a| <> +|=== + +==== For Configurations +* <> + +== Operations +* <> + +[[sendAction]] +=== Send Action +`` + +Transmits the relevant electronic document to a trading partner. + +==== Parameters +[%header,cols="20s,20a,35a,20a,5a"] +|=== +| Name | Type | Description | Default Value | Required +| Configuration | String | Name of the configuration to use. | | x +| Initiating action a| <> | Lists the reply attributes to send inside the Service header in the MIME message.| | +| Content a| Binary | Contents of the business document being exchanged between trading partners. | `#[payload]` | +| Streaming Strategy a| * <> +* <> +* <> | Configures how Mule processes streams. By default, Mule uses repeatable streams.| | +| Target Variable a| String | Name of the variable that stores the operation's output. | | +| Target Value a| String | Expression that evaluates the operation’s output. The outcome of the expression is stored in the *Target Variable* field.| `#[payload]` | +|=== + +==== Output +[%autowidth.spread] +|=== +|Type |Binary +| Attributes Type a| <> +|=== + +==== For Configurations +* <> + +==== Throws +* ROSETTA:WRITE +* ROSETTA:CONFIGURATION +* ROSETTA:PARSE +* ROSETTA:UNKNOWN + +== Object Types + +[[Completion]] +=== Completion + +Completion status and details for the *Completion source* source. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Completion Code a| Enumeration, one of: + +** SUCCESS +** FAILURE +** EXCEPTION a| Type of completion for the action message. Valid values are: + +*** SUCCESS: An acknowledgment signal was received from the partner. +*** EXCEPTION: An exception signal was received from the partner. +*** FAILURE: No response signal was received from the partner after the number of transmission attempts defined in the PIP configuration. | | x +| Exception Detail a| <> | Details of the received exception signal. Present if the completion code is `EXCEPTION`. | | +| Mime Data a| Binary | Received MIME signal message provided to the application in support of signed acknowledgment signals. Present if the completion code is `SUCCESS` or `EXCEPTION`. | | +|=== + +[[ExceptionDetail]] +=== Exception Detail + +Details of the received exception signal. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Exception Code a| String | Error code. | | x +| Exception Error Description a| String | Error description. + | | x +| Exception Component Code a| String | Code that identifies the transaction for which the error occurred. | | x +| Exception Type a| String | Error category. | | x +|=== + +[[ExpirationPolicy]] +=== Expiration Policy + +Configures an expiration policy strategy. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Max Idle Time a| Number | Configures the maximum amount of time that a dynamic configuration instance can remain idle before Mule considers it eligible for expiration. | | +| Time Unit a| Enumeration, one of: + +** NANOSECONDS +** MICROSECONDS +** MILLISECONDS +** SECONDS +** MINUTES +** HOURS +** DAYS | A time unit that qualifies *Max Idle Time*. | | +|=== + +[[MessageAttributes]] +=== Message Attributes + +Output of the *Action source* source, *Completion source* source, or *Send Action* operation. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Message Id a| String | Unique identifier of the message. | | x +| Partner Business Id a| String | Unique identifier of the trading partner. | | x +| Partner Location Id a| String | Identifier that represents the trading partner's location. | | x +| Reply Attributes a| <> | Identifier values used when generating an action message in reply to another action. The *Action source* source sets this value. | | x +| Mime Data a| Binary | MIME action or signal message, including the signature, if signing is used. The app supplies this value to + support non-repudiation. | | x +| Acknowledge Data a| Binary | MIME acknowledgment signal returned to the sender, including the signature, if signing is used. The *Action source* source sets this value. | | x +|=== + +[non-repeatable-stream] +=== Non-repeatable Stream + +Disables the repeatable stream functionality and uses non-repeatable streams to have less performance overhead, memory use, and cost. + +[[reconnect]] +=== Reconnect + +Configures a standard reconnection strategy, which specifies how often to reconnect and how many reconnection attempts the connector source or operation can make. + +[%header%autowidth.spread] +|=== +| Field | Type | Description | Default Value | Required +| Frequency a| Number | How often in milliseconds to reconnect. | | +| Count a| Number | How many reconnection attempts to make. | | +| blocking |Boolean |If `false`, the reconnection strategy runs in a separate, non-blocking thread. |`true` | +|=== + +[[reconnect-forever]] +=== Reconnect Forever + +Configures a forever reconnection strategy by which the connector source or operation attempts to reconnect at a specified frequency for as long as the Mule app runs. + +[%header%autowidth.spread] +|=== +| Field | Type | Description | Default Value | Required +| Frequency a| Number | How often in milliseconds to reconnect. | | +| blocking |Boolean |If false, the reconnection strategy runs in a separate, non-blocking thread. |`true` | +|=== + +[[RedeliveryPolicy]] +=== Redelivery Policy + +Configures the redelivery policy for executing requests that generate errors. You can add a redelivery policy to any source in a flow. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Max Redelivery Count a| Number | Maximum number of times that a message can be redelivered and processed unsuccessfully before triggering a `process-failed-message`. | | +| Use Secure Hash a| Boolean | Whether to use a secure hash algorithm to identify a redelivered message. | | +| Message Digest Algorithm a| String | Secure hashing algorithm to use if *Use Secure Hash* is `true`. If the payload of the message is a Java object, Mule ignores this value and returns the value that the payload’s `hashCode()` returned. | `SHA-256` | +| Id Expression a| String | One or more expressions that determine when a message was redelivered. This property can be set only if *Use Secure Hash* is `false`. | | +| Object Store a| Object Store | Configures the object store that stores the redelivery counter for each message. | | +|=== + +[[repeatable-file-store-stream]] +=== Repeatable File Store Stream + +Configures the repeatable file-store streaming strategy by which Mule keeps a portion of the stream content in memory. If the stream content is larger than the configured buffer size, Mule backs up the buffer’s content to disk and then clears the memory. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Max In Memory Size a| Number a| Maximum amount of memory that the stream can use for data. If the amount of memory exceeds this value, Mule buffers the content to disk. To optimize performance: + +* Configure a larger buffer size to avoid the number of times Mule needs to write the buffer on disk. This increases performance, but it also limits the number of concurrent requests your application can process, because it requires additional memory. +* Configure a smaller buffer size to decrease memory load at the expense of response time. | | +| Buffer Unit a| Enumeration, one of: + +** BYTE +** KB +** MB +** GB | Unit for *Max In Memory Size*. | | +|=== + +[[repeatable-in-memory-stream]] +=== Repeatable In Memory Stream + +Configures the in-memory streaming strategy by which the request fails if the data exceeds the maximum buffer size. Always run performance tests to find the optimal buffer size for your specific use case. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Initial Buffer Size a| Number | Initial amount of memory to allocate to the data stream. If the streamed data exceeds this value, the buffer expands by *Buffer Size Increment*, with an upper limit of *Max Buffer Size* value. | | +| Buffer Size Increment a| Number | Amount by which the buffer size expands if it exceeds its initial size. Setting a value of `0` or lower specifies that the buffer can't expand.| | +| Max Buffer Size a| Number | Maximum size of the buffer. If the buffer size exceeds this value, Mule raises a `STREAM_MAXIMUM_SIZE_EXCEEDED` error. A value of less than or equal to `0` means no limit.| | +| Buffer Unit a| Enumeration, one of: + +** BYTE +** KB +** MB +** GB | Unit for the *Initial Buffer Size*, *Buffer Size Increment*, and *Max Buffer Size* fields. | | +|=== + +[[ReplyAttributes]] +=== Reply Attributes + +Configures the values used when generating an action message in reply to another action. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Message Id a| String | Identifier of the message associated with the reponse. | | x +| Action Id a| String | Identifier that indicates the type of respone. | | x +| Pip Instance Id a| String | Identifier associated with an instance of a PIP. | | x +|=== + +== See Also + +* xref:connectors::introduction/introduction-to-anypoint-connectors.adoc[Anypoint Connectors Overview] +* https://help.salesforce.com[Salesforce Help] diff --git a/rosettanet/3.0/modules/ROOT/pages/rosettanet-connector-upgrade-migrate.adoc b/rosettanet/3.0/modules/ROOT/pages/rosettanet-connector-upgrade-migrate.adoc new file mode 100644 index 0000000000..e8adbf89ee --- /dev/null +++ b/rosettanet/3.0/modules/ROOT/pages/rosettanet-connector-upgrade-migrate.adoc @@ -0,0 +1,492 @@ += Upgrading and Migrating RosettaNet Connector to Version 3.x +:page-aliases: connectors::rosettanet/rosettanet-connector-upgrade-migrate.adoc + +Upgrade Anypoint Connector for RosettaNet (RosettaNet Connector) from version 2.x to 3.x to take advantage of FIPS-compliant cryptographic support and other improvements. + +== Supported Upgrade Paths + +[%header,cols="50a,50a"] +|=== +|From Version | To Version +|2.x |3.x +|=== + +== Before You Begin + +Before you upgrade to RosettaNet Connector 3.x, make sure you have: + +* Mule runtime 4.4.0 or later. See the Mule runtime release-notes::connector/rosettanet-connector-release-notes-mule-4.adoc for FIPS support by version. +* RosettaNet Connector version 3.0.0 or later. +* RosettaNet Support Libraries version 2.0.0 or later. +* Bouncy Castle Java Cryptography Extension (JCE) provider designed for JDK 1.8 or higher for non-FIPS mode. This configuration requires the `bcprov-jdk18on`, `bcpkix-jdk18on`, and `bcjmail-jdk18on` libraries. Version 1.82 is recommended. +* The `jakarta.activation` and `jakarta.mail` libraries for signing MIME Parts. +* `bcjmail-fips` library for FIPS modes and other Bouncy Castle FIPS (BCFIPS) libraries as required by your Mule runtime and security model. +* Java 17 or later with FIPS-capable JVM if required by your deployment for FIPS 140-3. + +== Supported Security Modes + +RosettaNet Connector 3.x supports these security modes, which are controlled by the `mule.security.model` system property: + +* *non-FIPS (default)* ++ +This is the default security mode for Mule applications that don't require FIPS compliance. RosettaNet Connector uses the non-FIPS compliant standard cryptographic libraries `bcprov-jdk18on`,`bcpkix-jdk18on`, `bcjmail-jdk18on`, `jakarta.activation` and `jakarta.mail` which aren't FIPS compliant. Don't set the system property as the default mode. +* *FIPS 140-2 Compliant Mode* ++ +Enable this security mode to configure RosettaNet Connector to use FIPS 140-2 approved cryptographic providers. +* *FIPS 140-3 Compliant Mode* ++ +Enable this security mode to configure RosettaNet Connector to use FIPS 140-3 approved cryptographic providers. + +If the `mule.security.model` property begins with `fips140-`, then RosettaNet Connector activates FIPS mode and applies the corresponding security controls, as shown in the example. + +[source,bash] +---- +-Dmule.security.model=fips140-3 +---- + +[[configure-external-libraries]] +== Configure External Libraries + +Mule applications using RosettaNet Connector require a Global Element configuration that includes the necessary RosettaNet support and cryptographic libraries for each security mode. The table shows the global configuration and required libraries for each security mode. Use only one security mode per application. + +For FIPS modes, the Mule runtime and BCFIPS requirements apply. + +[%header%autowidth] +|=== +|Security Mode | Global Configuration | Default Name | Required Library Maven Coordinates +|non-FIPS | `RosettaNet External Libs - Non FIPS` | `RosettaNet__External_Libs___Non_FIPS` | org.bouncycastle:bcpkix-jdk18on:1.82, org.bouncycastle:bcprov-jdk18on:1.82, org.bouncycastle:bcjmail-jdk18on:1.82, com.sun.activation:jakarta.activation:2.0.1, com.sun.mail:jakarta.mail:2.0.2 +|FIPS 140-2 | `RosettaNet External Libs - FIPS 140-2` | `RosettaNet__External_Libs___FIPS_140_2` | org.bouncycastle:bcjmail-fips:1.0.4, com.sun.activation:jakarta.activation:2.0.1, com.sun.mail:jakarta.mail:2.0.2 +|FIPS 140-3 | `RosettaNet External Libs - FIPS 140-3` | `RosettaNet__External_Libs___FIPS_140_3` | org.bouncycastle:bcjmail-fips:2.1.6, com.sun.activation:jakarta.activation:2.0.1, com.sun.mail:jakarta.mail:2.0.2 +|=== + +image::rosettanet-connector-upgrade-global-element-config.png["Connector configurations that are used for creating Global Elements",width=50%] + +[[upgrade-steps]] +== Upgrade Steps + +Follow these steps to upgrade from RosettaNet Connector 2.x to 3.x. Use the configuration that applies to your selected security mode. + +=== Step 1: Update the Connector Dependency + +. Update your project's `pom.xml` file to use RosettaNet Connector 3.x: + +[source,xml,subs=attributes+] +---- + + com.mulesoft.connectors + mule-rosettanet-connector + 3.0.0 + mule-plugin + +---- + +[start=2] +. Rebuild the project and resolve API or configuration changes reported by the build. + +=== Step 2: Add a Connector Configuration Global Element + +Include only one external library global configuration. Follow the global element configuration steps for your selected security mode. + +==== Configure a Global Element for the non-FIPS Security Mode + +. Add the external library global configuration and don't set the runtime property. Make sure the BouncyCastle jdk18on library version 1.82 is available to add as an external library. + +. Configure the global element as a Mule app in Anypoint Studio: + +.. In the *Package Explorer* or Anypoint Studio canvas, open your Mule flow or configuration. +.. Click *Global Elements*. Or click *Create global element*, and then click the plus icon next to Global Elements. +. Click *Create*, and then search for the `RosettaNet` or `External Libs` option and select *RosettaNet External Libs - Non FIPS*. +.. Name the configuration. +.. Click *Configure* > *Add recommended libraries*. +.. Click *OK* to include the libraries as dependencies and shared libraries in the Mule application `pom.xml` file. +. Verify that your project has the required dependencies for your selected security mode. Add the dependencies via Maven if they aren't added automatically. + +image::rosettanet-connector-upgrade-non-fips-config.png["The Connector Configuration Global Element and the configurations for non-FIPS security mode"] + +To configure the global element manually in XML (Maven or standalone): + +. Open your main Mule configuration file, such as `src/main/mule/` or `src/main/resources/`. +. Add the `rosetta:external-libs-non-fips-config` global element to the Mule configuration file. +. Add the `RosettaNet External Libs - Non FIPS` global configuration to your Mule configuration file, as shown in the example: + +[source,xml,subs=attributes+] +---- + +---- + +[start=4] +. Add the required Maven dependencies to the `pom.xml` file. Refer to the +xref:release-notes::connector/rosettanet-connector-release-notes-mule-4.adoc[RosettaNet Connector Release Notes] for the compatible versions of the dependencies. + +[source,xml,subs=attributes+] +---- + + org.bouncycastle + bcpkix-jdk18on + ${bouncy.castle.jdk18on.version} + + + org.bouncycastle + bcprov-jdk18on + ${bouncy.castle.jdk18on.version} + + + org.bouncycastle + bcjmail-jdk18on + ${bouncy.castle.jdk18on.version} + + + com.sun.activation + jakarta.activation + ${jakarta.activation.version} + + + com.sun.mail + jakarta.mail + ${jakarta.mail.version} + +---- + +[start=5] +. Update the `mule-maven-plugin` by including the shared libraries in the *build* > *plugins* > *plugin* section of the `pom.xml` file. + +[source,xml,subs=attributes+] +---- + + + + org.bouncycastle + bcpkix-jdk18on + + + org.bouncycastle + bcprov-jdk18on + + + org.bouncycastle + bcjmail-jdk18on + + + com.sun.activation + jakarta.activation + + + com.sun.mail + jakarta.mail + + + +---- + +==== Configure a Global Element for the FIPS 140-2 Security Mode + +. Add the external library global configuration and set the runtime property. Make sure BouncyCastle FIPS (BCFIPS) is available as required by your Mule runtime. Configure BCFIPS in Java Security. ++ +For FIPS 140-2 compliance, follow the xref:mule-runtime::fips-140-2-compliance-support.adoc[FIPS 140-2 Compliance Support] documentation. + +. Configure the global element as a Mule app in Anypoint Studio: + +.. In the *Package Explorer* or Anypoint Studio canvas, open your Mule flow or configuration. +.. Click *Global Elements*. Or click *Create global element*, and then click the plus icon next to Global Elements. +. Click *Create*, and then search for the `RosettaNet` or `External Libs` option and select *RosettaNet External Libs - FIPS 140-2*. +.. Name the configuration. +.. Click *Configure* > *Add recommended libraries*. +.. Click *OK* to include the libraries as dependencies and shared libraries in the Mule app `pom.xml` file. +. Verify that your project has the required dependencies for your selected security mode. Add the dependencies via Maven if they aren't added automatically. + +image::rosettanet-connector-upgrade-fips140-2-config.png["The Connector Configuration Global Element and the configurations for FIPS 140-2 security mode"] + +To configure the global element manually in XML (Maven or standalone): + +. Open your main Mule configuration file, such as `src/main/mule/` or `src/main/resources/`. +. Add the `rosettanet:external-libs-fips140-2-config` global element to the Mule configuration file. +. Add the `RosettaNet External Libs - FIPS 140-2` global configuration to your Mule configuration file, as shown in the example. + +[source,xml,subs=attributes+] +---- + +---- + +[start=4] +. Add the required Maven dependencies to the `pom.xml` file. Refer to the +xref:release-notes::connector/rosettanet-connector-release-notes-mule-4.adoc[RosettaNet Connector Release Notes] for the compatible versions of the dependencies. + +[source,xml,subs=attributes+] +---- + + org.bouncycastle + bcjmail-fips + ${bouncycastle.mail.fips.version} + + + com.sun.activation + jakarta.activation + ${jakarta.activation.version} + + + com.sun.mail + jakarta.mail + ${jakarta.mail.version} + +---- + +[start=5] +. Update the `mule-maven-plugin` by including the shared libraries in the *build* > *plugins* > *plugin* section of the `pom.xml` file. + +[source,xml,subs=attributes+] +---- + + + + org.bouncycastle + bcjmail-fips + + + com.sun.activation + jakarta.activation + + + com.sun.mail + jakarta.mail + + + +---- + +[start=6] +. In JVM or Mule runtime, set the security model to FIPS 140-2. + +[source,bash] +---- +-Dmule.security.model=fips140-2 +---- + +[start=7] +. Restrict BCFIPS to use only FIPS-approved algorithms. + +[source,bash] +---- +-Dorg.bouncycastle.fips.approved_only=true +---- + +This example shows the Mule runtime startup configuration for FIPS 140-2: + +[source,bash] +---- +java -Dmule.security.model=fips140-2 \ + -Dorg.bouncycastle.fips.approved_only=true \ + -jar mule-standalone.jar +---- + +==== Configure a Global Element for the FIPS 140-3 Security Mode + +. Add the external library global configuration and set the runtime property. Also: +** Make sure BouncyCastle FIPS (BCFIPS) is available as required by your Mule runtime. +** Configure BCFIPS in Java Security or by following the Mule runtime FIPS documentation for your version. +** Make sure you have Java 17 or later as required for FIPS 140-3 support in your deployment. + +. Configure the global element as a Mule app in Anypoint Studio: + +.. In the *Package Explorer* or Anypoint Studio canvas, open your Mule flow or configuration. +.. Click *Global Elements*. Or click *Create global element*, and then click the plus icon next to Global Elements. +. Click *Create*, and then search for the `RosettaNet` or `External Libs` option and select *RosettaNet External Libs - FIPS 140-3*. +.. Name the configuration. +.. Click *Configure* > *Add recommended libraries*. +.. Click *OK* to include the libraries as dependencies and shared libraries in the Mule app `pom.xml` file. +. Verify that your project has the required dependencies for your selected security mode. Add the dependencies via Maven if they aren't added automatically. + +image::rosettanet-connector-upgrade-fips140-3-config.png["The Connector Configuration Global Element and the configurations for FIPS 140-3 security mode"] + +To configure the global element manually in XML (Maven or standalone): + +. Open your main Mule configuration file, such as `src/main/mule/` or `src/main/resources/`. +. Add the `rosettanet:external-libs-fips140-3-config` global element to the Mule configuration file. +. Add the `RosettaNet External Libs - FIPS 140-3` global configuration to your Mule configuration file, as shown in the example: + +[source,xml,subs=attributes+] +---- + +---- + +[start=4] +. Add the required Maven dependencies to the `pom.xml` file. Refer to the +xref:release-notes::connector/rosettanet-connector-release-notes-mule-4.adoc[RosettaNet Connector Release Notes] for the compatible versions of the dependencies. + +[source,xml,subs=attributes+] +---- + + org.bouncycastle + bcjmail-fips + ${bouncycastle.mail.fips.version} + + + com.sun.activation + jakarta.activation + ${jakarta.activation.version} + + + com.sun.mail + jakarta.mail + ${jakarta.mail.version} + +---- + +[start=5] +. Update the `mule-maven-plugin` by including the shared libraries in the *build* > *plugins* > *plugin* section of the `pom.xml` file. + +[source,xml,subs=attributes+] +---- + + + + org.bouncycastle + bcjmail-fips + + + com.sun.activation + jakarta.activation + + + com.sun.mail + jakarta.mail + + + +---- + +[start=6] +. In JVM or Mule runtime, set the security model to FIPS 140-3. + +[source,bash] +---- +-Dmule.security.model=fips140-3 +---- + +[start=7] +. Restrict BCFIPS to use only FIPS-approved algorithms. + +[source,bash] +---- +-Dorg.bouncycastle.fips.approved_only=true +---- + +This example shows the Mule runtime startup configuration for FIPS 140-3: + +[source,bash] +---- +java -Dmule.security.model=fips140-3 \ + -Dorg.bouncycastle.fips.approved_only=true \ + -jar mule-standalone.jar +---- + +[NOTE] +==== +The `org.bouncycastle.fips.approved_only` property is JVM-wide and must be set in your system or runtime configuration when running in FIPS mode. + +If you use BCFIPS in FIPS mode, key and algorithm restrictions apply. Only approved algorithms supported by the BCFIPS provider are allowed. +==== + +=== Step 3: Verify Keystore and Algorithm Compatibility + +. Verify that keystores and certificates are compatible with your selected security mode. Some FIPS modes require FIPS-approved algorithms. +. Review the Mule and BCFIPS documentation for approved algorithms if you use BCFIPS in FIPS mode, since key and algorithm restrictions apply. + +=== Step 4: Verify Connector Usage in Flows + +. Verify that partner certificates and algorithms are compatible with your selected security mode. +. If you use RosettaNet Connector operations in your flows, verify that the connector configuration also exists in your Mule app. + +[[startup-validation]] +== RosettaNet Connector Startup Validation + +At startup, RosettaNet Connector validates that the external library configuration and runtime settings are correct. Validation fails if the Mule application doesn't meet these requirements: + +* The application must include one external library. An error occurs if more than one external library is included or if none are included. +* Match the `mule.security.model` system property to the selected external library configuration: +** For non-FIPS, disable the `mule.security.model`. If it's enabled, remove the property. +** For FIPS 140-2, set `mule.security.model` to `fips140-2`. If the property isn't configured correctly, a message is logged to correct the setting to `-Dmule.security.model=fips140-2`. +** For FIPS 140-3, set `mule.security.model` to `fips140-3`. If the property isn't configured correctly, a message is logged to correct the setting to `-Dmule.security.model=fips140-3`. + +* RosettaNet Connector instantiates the cryptographic implementation for the selected security mode at startup. If this fails, for example due to missing or incompatible libraries, an error is logged that includes the security profile and the cause. + +== Post-Upgrade Steps + +. Verify that the application starts without errors and that RosettaNet Connector initializes correctly for your selected security mode. +. Test the operations against your RosettaNet partners. +. Confirm that certificates and algorithms are accepted in FIPS mode if applicable. +. Notify partners of URL or port changes if you modified the HTTP Listener configuration. + +== System Properties Reference + +The table details the system-level properties that are required to configure RosettaNet Connector's security modes and BCFIPS compliance within the Mule runtime or JVM. + +[%header%autowidth] +|=== +|Property | Description | Values | Default | Scope +|`mule.security.model` | Security mode used by the connector | `fips140-2` or `fips140-3` | `non-FIPS` (when not set) | Mule runtime or JVM +|`org.bouncycastle.fips.approved_only` | Restricts BCFIPS to FIPS-approved algorithms only. Required for FIPS compliance when using BCFIPS. | `true`, `false` | `false` | JVM-wide +|=== + +The `org.bouncycastle.fips.approved_only` property affects the entire JVM. When the application runs in FIPS mode, the system administrator must configure the property. For more information, see the *FIPS 140-2 Compliance Support* section on the xref:mule-runtime::securing.adoc[Security] page in the Mule runtime documentation. + +== Migrate Existing Deployments + +RosettaNet Connector 3.x introduces a Global Connector Configuration and supports configurable security modes including non-FIPS, FIPS 140-2, and FIPS 140-3 via the `mule.security.model` system property. Follow the <> to make the necessary changes to your Mule app. RosettaNet Connector's cryptographic behavior is determined by the global configuration, which provides the required libraries and defines the runtime security model. + +Existing 2.x flows remain functional without requiring code changes. + +=== Migrate Deployments from FIPS 140-2 or 140-3 Environments + +. Verify that BCFIPS and FIPS-related settings are configured correctly for your Mule runtime version. For more information, see the *FIPS 140-2 Compliance Support* section on the +xref:mule-runtime::securing.adoc[Security] page in the Mule runtime documentation. +. Set `mule.security.model` to `fips140-2` or `fips140-3` as appropriate for your compliance requirements. +. Set `org.bouncycastle.fips.approved_only` to `true` if required by your runtime for compliance. +. Test your configuration in a non-production environment by running your flows that use the operations. +. Deploy the application to production and monitor the error log to verify a successful startup and RosettaNet message exchange. + +== Troubleshooting + +These common error messages and issues indicate configuration or `classpath` problems that prevent RosettaNet Connector from operating in the selected security mode. Follow the recommendations to resolve the issues. + +* *RosettaNet Connector requires at least one External Libs configuration* ++ +Add `RosettaNet External Libs - Non FIPS`, `RosettaNet External Libs - FIPS 140-2`, or `RosettaNet External Libs - FIPS 140-3` to your application. See <>. +* *Only one External Libs configuration is allowed per application* ++ +Remove the additional external library configurations so that you only have one. +* *Detected 'mule4-rosettanet-support-non-fips' but system property 'mule.security.model' is ...* ++ +For non-FIPS mode, disable `mule.security.model` or remove it from the JVM arguments or runtime configuration. +* *Detected 'mule4-rosettanet-support-fips1' but system property ... Set -Dmule.security.model=fips140-2* ++ +Add `-Dmule.security.model=fips140-2` if you're using `RosettaNet Connector External Libs - FIPS 140-2`. +* *Detected 'mule4-rosettanet-support-fips2' but system property ... Set -Dmule.security.model=fips140-3* ++ +Add `-Dmule.security.model=fips140-3` if you're using `RosettaNet Connector External Libs - FIPS 140-3`. +* *External Libs - ... configuration selected, but '...' is not on the classpath* ++ +Add the correct implementation dependency for your selected security mode or make sure the external library configuration imports the dependency. If you receive a warning, make sure only the library for your active security mode remains on the `classpath` by removing any additional RosettaNet cryptographic implementations. +* *Startup or Crypto Errors in FIPS Mode* ++ +Make sure `mule.security.model` matches your runtime FIPS setup and that BCFIPS is installed and registered. Set `org.bouncycastle.fips.approved_only` to `true` if required. +* *Tests or Flows that Relied on non-FIPS Behavior* ++ +If your application is running with `mule.security.model=fips140-2` or `fips140-3`, some algorithms or key usages are restricted. Align keystores and partner expectations with FIPS-approved algorithms. +* *Caching or Metadata Issues* ++ +If Anypoint Studio or Anypoint Design Center shows a stale configuration, try restarting the IDE or clearing your cache. + +== Revert the Upgrade + +To revert to RosettaNet Connector 2.x: + +. Change the `mule-rosettanet-connector` dependency in your project's `pom.xml` file to the desired 2.x version. +. Remove the external library global configuration. +. Remove the libraries that were added as dependencies and shared libraries from the `pom.xml` file. +. Remove or adjust 3.x system properties, such as `mule.security.model`, if they aren't being used by other components. + +== See Also + +* xref:connectors::introduction/introduction-to-anypoint-connectors.adoc[Introduction to Anypoint Connectors] +* xref:rosettanet-connector-reference.adoc[RosettaNet Connector Reference] +* https://help.salesforce.com[Salesforce Help]