The RNIF Connector sends and receives messages via the RosettaNet protocol.
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 ArcESB 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.
The RNIF Profile must be configured before connections can be established with individual RNIF Connectors.
RNIF Profile Tab
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.
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.
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.
After configuring the RNIF Profile, RNIF Connectors can be created in the Flows page and configured for a specific trading partner.
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.
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.
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.
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.
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.
Settings that determine the folder on disk that files will be sent/uploaded from, and the folder that they will be received/downloaded to.
- Input Folder (Send) The connector can send/upload files placed in this folder. If Send Automation is enabled, the connector will automatically poll this location for files to process.
- Output Folder (Receive) The connector will place received/downloaded files in this folder. If the connector is connected to another connector in the flow, files will not remain here and will instead be passed along to the Input/Send folder for the connected connector.
- Processed Folder (Sent) After processing a file, the connector will place a copy of sent/uploaded files in this folder if Save to Sent Folder is enabled.
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.
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.
An arbitrary set of custom headers to be included as part of the outgoing message.
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.
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:
- 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.
- Supply your private certificate and password if using encryption and/or signing of messages.
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
- Trading Partner Certificates
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.
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 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. ArcESB 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.
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:
|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|
|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|