Search

AS4 Connector

Version 22.0.8473

AS4 Connector

The AS4 Connector supports sending and receiving messages via the AS4 protocol.

Overview

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

When CData Arc receives a file over AS4, it attempts to route the file to a specific AS4 Connector. The application uses the AS4 party identifiers in the AS4 message to determine which AS4 Connector should receive the file. When a file is routed to an AS4 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 AS4 Profile must be configured before connections can be established with individual AS4 Connectors.

AS4 Profile Tab

Personal Id

Settings for identifying the local profile.

  • Party Identifier Your AS4 identifier. Messages sent by Arc must be addressed to this identifier, and outgoing messages will use this value to identify the originator of the message. Identifiers are case-sensitive.
  • Party Identifier Type The optional type declaration of the Party identifier. If specified, this value should be the domain to which the identifier belongs.

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 AS4 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 AS4 messages. This URL should be advertised to all trading partners.

Connector Configuration

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

Settings Tab

Trading Partner Info

Settings for identifying and connecting to a specific AS4 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.
  • Party Identifier The AS4 party identifier specific to the target trading partner. This value is included in the outgoing AS4 message to ensure it is delivered to the intended recipient, and it is also used to route incoming AS4 messages to the appropriate AS4 Connector.
  • Party Identifier Type The optional type declaration of the Party identifier. If specified, this value should be the domain to which the identifier belongs.
  • Partner URL The trading partner’s public endpoint where outgoing AS4 messages should be sent.
  • Agreement The shared AS4 Agreement that governs the exchange.

Connection Info

Settings related connection parameters for the specified trading partner.

  • Send Message Security Whether to sign and/or encrypt outgoing AS4 messages. Signatures and encryption are strongly recommended.
  • Receive Message Security Whether to require that signatures and encryption are present for incoming AS4 messages. An error will be thrown if a received message does not have a required security parameter.
  • Compression Whether to compress the payload of outgoing messages.
  • Connection Timeout The length of time the connector will wait for a connection response before throwing a timeout error.
  • Profile The AS4 profile to use in the AS4 interchange. Profiles help determine shared configuration settings to ensure compatibility between partners. Setting the profile will automatically update relevant configuration options in the connector.
  • Message Partition Channel The channel over which the AS4 interchange should occur. If no channel is specified, the default Message Partition Channel (MPC) is implicitly assigned. MPCs are important when sending or receiving pull requests, as only messages queued in the assigned MPC will be returned in response to the pull request.

Receipt

Settings related to requesting Receipts when sending AS4 messages.

  • Use Receipt Whether a Receipt should be returned in response to incoming AS4 messages, and expected in response to outgoing AS4 messages.
  • Delivery Whether the Receipt should be returned as a direct response to the outgoing AS4 message (Synchronous) or returned later as part of a separate connection (Asynchronous). Synchronous MDNs are recommended unless the size of AS4 messages is very large (50MB is a common threshold), in which case processing the message and delivering a synchronous Receipt 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 AS4 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 AS4 configuration details.
  • Verification Certificate The public key certificate used to verify AS4 signatures when receiving messages. This field is often unnecessary; most AS4 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 AS4 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.

Business Agreement Details

Settings related to the shared details of the AS4 business agreement. These values should be confirmed with the trading partner prior to configuration.

  • Service The business process accepting the message.
  • Service Action The operation or activity being executed in the business process.
  • Service Type The optional qualifier providing context to the Service.
  • From Role The role of the party from which the message originates. These roles may either be reversed or remain the same when sending versus receiving AS4 requests, per partner agreement. This value is used in the within the PartyInfo element of the resulting AS4 SOAP envelope.
  • To Role The role of the party to which the message is delivered. These roles may either be reversed or remain the same when sending versus receiving AS4 requests, per partner agreement. This value is used in the within the PartyInfo element of the resulting AS4 SOAP envelope.

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 AS4 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 Receipt 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.
  • Receive Whether the connector should automatically make pull requests to receive messages from the trading partner.
  • Pull Interval The interval between automatic pull requests.
  • Minutes The number of minutes to wait before downloading. Only applicable when Pull Interval is set to Minute.
  • Minutes Past the Hour The minutes offset for an hourly schedule. Only applicable when Pull Interval is set to Hourly. For example, if this value is set to 5, the automation service will pull at 1:05, 2:05, 3:05, etc.
  • Time The time within a given day that the pull request should occur. Only applicable when Pull Interval is set to Daily, or Weekly, or Monthly.
  • Day The day on which the pull request should occur. Only applicable when Pull Interval is set to Weekly or Monthly.
  • Cron Expression An arbitrary string representing a cron expression that determines when the pull request should occur. Only applicable when Pull Interval is set to Advanced.

Advanced Tab

Token Authentication

Settings related to using and requiring token authentication.

  • Require Token Authentication Whether authentication tokens must be included in incoming AS4 messages. If enabled, incoming messages must include username credentials that match the Username and Password fields set under this option.
  • Use Token Authentication Whether authentication tokens should be included in outgoing AS4 messages. If enabled, outgoing messages will include username credentials that match the Username and Password fields set under this option.
  • Password Type Whether username tokens should be in plain text or encrypted digest format.

Alternate Local Profile

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

  • Party Identifier Your AS4 identifier. Overrides Party Identifier in the Profile section.
  • Party Identifier Type Optionally, your AS4 identifier type. Overrides Party Identifier Type 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 sections.
  • 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.

Message Properties

An arbitrary set of custom message properties, specified in name-value pairs, to be included as part of the outgoing message.

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.

Other Settings

Settings not included in the previous categories.

  • Agreement Ref P-Mode The processing mode attribute of the shared AS4 agreement.
  • Agreement Ref Type The reference type attribute of the shared AS4 agreement.
  • Attach XML Files Whether XML payloads should be packaged as a MIME attachment to the SOAP message, or included directly in the SOAP body.
  • Encryption Algorithm The algorithm to use when encrypting outgoing AS4 messages.
  • 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.
  • Log Requests Whether the payload and request logs should be written when sending messages. This increases the disk space consumed when sending large messages. When requesting support, it is recommended to include requests in the debug logs and provide these along with the support request.
  • 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.
  • Pull URL The URL endpoint to which pull requests should be sent, if different from the Partner URL.
  • Receipt URL The URL endpoint to which Receipts should be sent, if different from the Partner URL.
  • Signature Algorithm The algorithm to use when signing outgoing messages. The same algorithm will be requested for the corresponding Receipts.
  • Duplicate Message Action How the connector should behave when receiving an AS4 message with a Message ID that the connector has seen before. If set to Ignore, the connector will silently ignore (discard) the inbound file. If set to Continue, the connector will process the duplicate file like any other file. If set to Failure, the connector will raise an error and not process the file. The connector detects duplicate messages by “remembering” Message IDs that are received for a duration according to Duplicate Message Interval.
  • Duplicate Message Interval The length of time, in minutes, that a message with the same Message ID will be considered a duplicate. In other words, the length of time the connector will “remember” that a specific ID has already been received. If set to 0, the Message IDs will be stored until the server is restarted.
  • 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

The AS4 profile contains key pieces of information that are used to identify you with trading partners, and is configured within the Profile page of the application.

To get started, specify the following information:

  • Party Identifier
  • Personal Certificate

Identifier

Similar to an email address in an email exchange, this identifies the partner in an AS4 transmission.

Set the AS4 Identifier to a value that meaningfully identifies you or your organization. The value set here is sent in the headers of AS4 transmissions initiated by Arc.

The AS4 Identifier is one piece of information exchanged with trading partners when sharing profile information. Trading partners should use this value in their AS4 system so that they can process requests coming from that identifier.

Personal Certificate

The private key certificate is used to sign outgoing messages and to decrypt incoming messages. The AS4 profile uses a private key certificate in PKCS#12 format (a .pfx or .p12 file).

The application installation includes a private key certificate in the test profile, test.pfx. This certificate is distributed with all downloads of this application, so it should ONLY be used for initial testing.

  • Select Upload Certificate in the Private Certificate menu to select an existing certificate from disk.
  • Create a new self-signed certificate by clicking Create Certificate. This action creates both a new private key certificate and a public key certificate (.cer file) with the same name.

Receiving URL

This value is generated based on the specified Base URL in Settings → Advanced, and the default Arc listening endpoint.

This value should be shared with trading partners so that they can successfully send AS4 messages to the application.

Partner Setup

Trading partners are responsible for providing specific settings required to connect to their AS4 endpoints. Each AS4 Connector should be configured for a single trading partner relationship.

Several AS4 configuration options are required:

  • Party Identifier
  • Partner URL
  • Trading Partner Certificates
  • Use Receipt
  • Service
  • Service Action

Other elements of AS4 configuration are optional and subject to agreement between trading partners ahead-of-time. Communicate clearly with trading partners to establish which fields are necessary to communicate successfully with the specific partner.

Party Identifier

The trading partner provides their Party Identifier, the part of their profile that is used to identify their organization in an AS4 transmission. The identifier is used in the header of outgoing requests to indicate the intended recipient.

Note: This value is case sensitive, so when configuring new trading partners, be sure to check the capitalization is correct.

Partner URL

The Partner URL is the public endpoint where the trading partner’s AS4 system listens for incoming messages. After receiving a URL from the trading partner, test the URL with a web browser to detect any general networking or connectivity issues.

In some cases, the trading partner may provide more than one URL if they provide separate URLs for pushing AS4 transmissions, pulling AS4 transmissions, and returning asynchronous Receipts. Additional URLs are configured in the Advanced tab under Pull URL and Receipt URL.

Trading Partner Certificates

Each AS4 Connector must be configured with the public key certificate(s) for the target trading partner. The trading partner provides the certificates necessary to encrypt and verify AS4 messages exchanged with them. Arc accepts X.509 public key certificates (files with .cer, .der, or .pem extensions).

Typically the trading partner will provide a single certificate, which should be configured in the Encryption Certificate field.

If the trading partner provides multiple certificates, they should clarify the purpose of each certificate. If the partner provides a full certificate chain (as acquired from a commercial certificate authority), only the leaf certificate needs to be configured (the last certificate in the chain). Sometimes, a separate public key certificate should be used to verify the partner’s digital signatures. In this case, set the signature verification certificate under Verification Certificate.

If the trading partner requires SSL/TLS connections, they may also provide you with the public key certificate for their SSL server. This should be set under SSL Server Certificate. Alternatively, this field can be set to ‘Any Certificate’ to implicitly trust the identity of the target SSL server.

Use Receipt

Requesting a receipt ensures non-repudiation of the AS4 message; in other words, the successful delivery of the message cannot be disputed. For this reason, enabling the Use Receipt field is strongly recommended. The use of Receipts should be agreed upon with the trading partner ahead-of-time.

By default, Receipts are delivered synchronously, meaning that they are returned as a direct response to the AS4 message. Asynchronous Receipts are delivered later in a separate connection. Synchronous Receipts are recommended unless the size of the AS4 messages is very large, in which case processing and delivering a synchronous Receipt may strain the connection timeout duration.

Service and Service Action

Service, Service Action, and other business agreement details should be communicated with the trading partner. These values help define the business logic associated with the AS4 messages exchanged and how each party should interpret the messages.

Import from SMP

If the trading partner has a Service Metadata Publisher (SMP) profile, these settings can be imported using the Import from SMP button. The resulting prompt requires the SML Domain, Participant Id/Scheme, and Document Id/Scheme from which to obtain the SMP profile. The Connector settings are automatically populated with the values read from the SMP profile.

Send and Receive Files

After the AS4 profile and partner-specific AS4 Connectors have been configured, files can be securely sent and received.

Send Files

Within an AS4 Connector, the Input tab displays the files that should be sent to the target trading partner. If Send Automation is enabled, files that reach the Input/Send Folder of the connector will automatically be enveloped and sent. Successful transmissions are indicated by a green ‘Sent’ status, while warning and error statuses are represented in yellow and red. The log files for failing or successful transmissions can be accessed by expanding the row associated with the transmitted file.

The Create Test Files button can be used to generate a simple series of test files to send to the trading partner.

Resend and Retry

An AS4 Resend is triggered when the trading partner is expected to return an asynchronous Receipt, but fails to do so within the Resend Interval duration (by default this is 60 minutes). The application then attempts to resend the transmission. The application will continue re-sending the message until an MDN is received or the Max Attempts (async) is exhausted.

A Retry is triggered when the HTTP response from the trading partner indicates that the server has not received the transmission (i.e. the response is not a positive 200 OK status). This often indicates a networking or connectivity issue, which are often transient. The application will retry the transmission every Retry Interval minutes until the transmission is received or the Max Attempts is exhausted.

Receive Files

Within an AS4 Connector, the Output tab displays the files that have been received by the application and routed to the connector (based on the AS4 identifiers present in the incoming AS4 message). Each file row can be expanded to display a list of available logs for the transmission.

These files are available in the Output/Receive Folder of the connector. If the connector is connected to other connectors in the flow, files will automatically be moved from the Output/Receive Folder of the AS4 Connector to the Send directory of the next connector in the flow.