RosettaNet Connector

Version 22.0.8473


RosettaNet Connector


The RNIF Connector sends and receives messages via the RosettaNet protocol.

Overview

An RNIF connection is configured in two places. The RNIF Profile section should be configured with a local RNIF identifier, and private certificates. Then, each RNIF Connector should be configured with connection settings specific to a single trading partner. When an input file is processed by an RNIF Connector, it is packaged and sent to the specified trading partner.

When CData Arc receives a file over RNIF, it attempts to route the file to a specific RNIF Connector. The application uses the RNIF identifiers in the RNIF message to determine which RNIF Connector should receive the file. When a file is routed to an RNIF Connector, that file is placed in the connector’s Receive directory, or is passed along to the next connected connector in the flow.

Profile Configuration

The RNIF Profile must be configured before connections can be established with individual RNIF Connectors.

RNIF Profile Tab

Personal Id

Settings for identifying the local profile.

  • Business Identifier Your identifier. Messages sent by Arc will include this value in outgoing messages to identify the sender. Incoming messages must be addressed to this identifier. Identifiers are case-sensitive.
  • Business Location Describes the location of the receiver for incoming messages. This value is not an address, but may be a city name.

Personal Certificate

Settings related to the private decryption and signature certificate.

  • Private Certificate The certificate that will be used to decrypt incoming messages and sign outgoing messages. This certificate should never be shared with any external parties. Click the Create Certificate button to generate a new self-signed certificate that is ready to use in an RNIF transaction; a corresponding public key certificate will also be generated with the same filename and a ‘.cer’ extension.
  • Certificate Password The password required to access the Private Certificate.

Application URLs

Settings and displayed values related to accessing Arc from the public web.

  • Receiving URL The URL at which Arc will listen for incoming RNIF messages. This URL should be advertised to all trading partners.

Connector Configuration

After configuring the RNIF Profile, RNIF Connectors can be created in the Flows page and configured for a specific trading partner.

Settings Tab

Configuration

Settings for identifying and connecting to a specific RNIF trading partner.

  • Connector Id The static name of the connector. All connector-specific files are held in a folder by the same name within the Data Directory.
  • Connector Description An optional field to provide free-form description of the connector and its role in the flow.
  • Business Identifier The identifier specific to the target trading partner. This value is included in the headers for outgoing messages, and it is also used to route incoming messages to the appropriate RNIF Connector.
  • Business Location The location of the intended recipient of outgoing messages.
  • Partner URL The trading partner’s public endpoint where outgoing messages should be sent.

Connection Info

Settings related to connection parameters for the specified trading partner.

  • RNIF Version The protocol version to use when generating RNIF messages.
  • Encryption Type Whether to encrypt the payload, the payload and the headers, or neither.
  • Data Signature Whether to sign outgoing messages.
  • Receive Message Security Whether to require that signatures and encryption are present for incoming messages. An error will be thrown if a received message does not have a required security parameter.
  • Connection Timeout The length of time the connector will wait for a connection response before throwing a timeout error.

Acknowledgments

Settings related to RNIF acknowledgments.

  • Send Acknowledgment Automatically Whether an Acknowledgment should be sent automatically in response to incoming RNIF messages.
  • Send Exception Automatically Whether an Exception should be sent automatically in response to failed message reception.
  • Require Acknowledgment Whether an Acknowledgment should be returned in response to outgoing RNIF messages.
  • Security Whether the Acknowledgment should include a signature block verifying the message integrity and identity of the recipient.
  • Delivery Whether the Acknowledgment should be returned as a direct response to the outgoing RNIF message (Synchronous) or returned later as part of a separate connection (Asynchronous). Synchronous Acknowledgments are recommended unless the size of RNIF messages is very large, in which case processing the message and delivering a synchronous Acknowledgment may strain the connection timeout duration.

Trading Partner Certificates

Settings related to the public key certificates provided by the trading partner.

  • Encryption Certificate The public key certificate used for RNIF encryption when sending messages. This certificate must be paired with the trading partner’s private decryption certificate, and the trading partner should provide this public key certificate when sharing RNIF configuration details.
  • Verification Certificate The public key certificate used to verify RNIF signatures when receiving messages. This field is often unnecessary; most RNIF parties will use the same private certificate for both signing and decrypting, and if this field is not specified then the application will use the Encryption Certificate to verify signatures.
  • SSL Server Certificate The public key certificate used to verify the identity of an SSL/TLS server. Only necessary if the partner’s RNIF system requires HTTPS (rather than HTTP). If the trading partner does not provide an SSL server certificate, this setting can be left blank, to allow the underlying OS/JVM to perform certificate validation, or it can be set to ‘Any Certificate’ to unconditionally trust the target server’s identity.

Automation Tab

Automation Settings

Settings related to the automatic processing of files by the connector.

  • Send Whether files arriving at the connector will automatically be sent as RNIF messages.
  • Retry Interval The amount of time before a failed send is retried. A retry is triggered when the server does not respond to a send attempt, or responds negatively to communicate that the file was not received.
  • Max Attempts The maximum number of times the connector will process the input file. Success is based on a successful server acknowledgement and validation of the receipt (when requested synchronously). If this is set to 0, the connector will retry the file indefinitely.
  • Resend Interval The amount of time before unacknowledged messages are resent. A resend is triggered when the server receives the file, but an asynchronous Acknowledgment is not provided within the expected timeframe.
  • Max Attempts (async) The maximum number of times the connector will process the input file when asynchronous receipts are requested. Success is based on the return of an asynchronous receipt within the Resend Interval after a successful server acknowledgement (if a successful server acknowledgement is not returned, Max Attempts is applied instead). If this is set to 0, the connector will resend the file indefinitely.

Performance

Settings related to the allocation of resources to the connector.

  • Max Workers The maximum number of worker threads that will be consumed from the threadpool to process files on this connector. If set, overrides the default setting from the Profile tab.
  • Max Files The maximum number of files that will be processed by the connector each time worker threads are assigned to the connector. If set, overrides the default setting from the Profile tab.

Advanced Tab

Alternate Local Profile

Settings that override the configuration in the Profile page for this specific RNIF Connector. Setting an alternate local profile allows the use of different local certificates and identifiers for certain trading partners.

  • Local Business Location Your location. Overrides Business Location in the Profile section.
  • Local Business Identifier Your identifier. Overrides Business Identifier in the Profile section.
  • Private Certificate The certificate that will be used to decrypt incoming messages and sign outgoing messages. Overrides Private Certificate in the Profile section.
  • Certificate Password The password required to access the local private certificate.

SSL Client Authentication

Settings related to client authentication when two-way SSL authentication is required.

  • Use private certificate from the Profile tab Whether to use the same Private Certificate configured in the Profile page as the SSL certificate for client authentication.
  • Private Certificate The private certificate presented during SSL client authentication. Only applicable if not using the same private certificate from the Profile page.
  • Certificate Password The password required to access the SSL client certificate.

HTTP Authentication

Settings related to HTTP client authentication.

  • Use HTTP Authentication Whether client HTTP Authentication is enabled.
  • HTTP Authentication Type Whether to provide HTTP authentication credentials in an encrypted format (Digest) or in plain text (Basic). Basic authentication should only be used if the the connection is an HTTPS connection (rather than HTTP).
  • User The User credential for HTTP client authentication.
  • Password The Password credential for HTTP client authentication.

Custom Headers

An arbitrary set of custom headers to be included as part of the outgoing message.

Other Settings

Settings not included in the previous categories.

  • Send Filter A glob pattern filter to determine which files in the Send folder will be sent by the connector (e.g. *.txt). Negative patterns may be used to indicate files that should not be processed by the connector (e.g. -*.tmp). Multiple patterns may be separated by commas, with later filters taking priority except when an exact match is found. Log Level The verbosity of logs generated by the connector. When requesting support, it is recommended to set this value to Debug.
  • Parent Connector The connector from which settings should be inherited, unless explicitly overwritten within the existing connector configuration. Must be set to a connector of the same type as the current connector.
  • RNIF Debug Mode Whether communication errors related to the validation of PIPs or the authentication of the sender should be returned by RNIF receivers. This setting must be enabled on both sides of the transfer for the exceptions to be returned.
  • Log Subfolder Scheme Instructs the connector to group files in the Logs folder according to the selected interval. For example, the Weekly option instructs the connector to create a new subfolder each week and store all logs for the week in that folder. The blank setting tells the connector to save all logs directly in the Logs folder. For connectors that process many transactions, using subfolders can help keep logs organized and improve performance.
  • Log Messages Whether the log entry for a processed file will include a copy of the file itself.
  • Save to Sent Folder Whether files processed by the connector should be copied to the Sent folder for the connector.
  • SSL Enabled Protocols The list of SSL/TLS protocols supported when establishing outgoing connections. It is strongly recommended to only use TLS protocols. Some obsolete operating systems do not support TLS 1.2.

Miscellaneous

Settings for specific use cases.

  • Other Settings Allows configuration of hidden connector settings in a semicolon-separated list, like setting1=value1;setting2=value2. Normal connector use cases and functionality should not require use of these settings.

Personal Profile Configuration

To set up your personal profile for RosettaNet:

  1. Enter your Business Identifier and Location:
    • The Business Identifier should be your company’s DUNS number or some other already agreed upon identifier.
    • The Business Location is an optional field and typically contains your city location.
  2. Supply your private certificate and password if using encryption and/or signing of messages.

Partner Setup

To establish communications with your RosettaNet trading partners, establish a partner profile for them so incoming and outgoing messages can be routed properly. Configure new trading partner profiles in the Connectors section in the administration console. Click the cogwheel button on the drop-down menu where connectors are listed to add or delete a connector. Select a connector type of RNIF to add a new RosettaNet trading partner.

To work with an existing connector, select the connector in the menu. Additional connector configuration can be configured through the Settings tab. Configure the partner profile with the following information:

  • Host Configuration
  • Connection Info
  • Acknowledgments
  • Trading Partner Certificates

Host Configuration

In the host configuration section, supply your trading partner’s Business Identifier, Partner URL, and optional Business Location. The Partner URL is the fully qualified absolute URL to where your partner receives documents. Your own receiving is in the following format:

http(s)://<domain or IP address><:connector>/<virtual path/>pub/Receive.rsb

Construct your receiving URL using your publicly accessible domain or IP address, as well as your prefix, connector, and virtual path information as they are configured on your server.

Connection Info

In the Connection Info section, configure options such as which version of RNIF you are using and whether or not to encrypt or sign messages. You can also restrict incoming messages to only be processed if they have been encrypted and signed.

Acknowledgments

Acknowledgments are receipts sent back after receiving a file and are used by the application to ensure that your file was received. If a file receipt is not returned, it is treated as not being successfully sent and thus, is resent when the resend interval is reached.

Trading Partner Certificates

Finally, one or more digital certificates should be configured for each trading partner. Trading partners must provide the certificates required for communication with their servers. Arc accepts X.509 public key certificates (files with .cer, .der, or .pem extensions).

In the Encryption Certificate menu, you can select an existing certificate from disk to use for both encryption and signature verification purposes. In the SSL Server Certificate menu, you can specify the SSL Server certificate to authenticate with when connecting to your partner’s server.

Configuring PIPs

Partner Interface Processes (PIPs) are the logical XML documents used by RosettaNet to transport information about various business processes. The following is a list of common PIPs:

3A1 Request Quote
3A2 Request Price and Availability
3A3 Request Shopping Cart Transfer
3A4 Request Purchase Order
3A5 Query Order Status
3A6 Distribute Order Status
3A7 Notify of Purchase Order Update
3A8 Request Purchase Order Change
3A9 Request Purchase Order Cancellation
3A10 Notify of Quote Acknowledgement
3A13 Notify of Purchase Order Information
3A14 Distribute Planned Order
3B1 Distribute Transportation Projection
3B2 Notify of Advance Shipment
3B3 Distribute Shipment Status
3B4 Query Shipment Status
3B5 Request Shipment Change
3B6 Notify of Shipments Tendered
3B11 Notify of Shipping Order
3B12 Request Shipping Order
3B13 Notify of Shipping Order Confirmation
3B14 Request Shipping Order Cancellation
3B18 Notify of Shipment Documentation
3C1 Return Product
3C2 Request Financing Approval
3C3 Notify of Invoice
3C4 Notify of Invoice Reject
3C5 Notify of Billing Statement
3C6 Notify of Remittance Advice
3C7 Notify of Self-Billing Invoice