AS4 Connector

Version 21.0.8222


AS4 Connector


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

概要

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 ArcESB 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.

  • パーティ識別子 Your AS4 identifier. Messages sent by ArcESB must be addressed to this identifier, and outgoing messages will use this value to identify the originator of the message. Identifiers are case-sensitive.
  • パーティ識別子の種類 The optional type declaration of the パーティ識別子. If specified, this value should be the domain to which the identifier belongs.

Personal Certificate

Settings related to the private decryption and signature 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.
  • 証明書のパスワード The password required to access the プライベート証明書.

Application URLs

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

  • 受信URL The URL at which ArcESB 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.
  • パーティ識別子 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.
  • パーティ識別子の種類 The optional type declaration of the パーティ識別子. If specified, this value should be the domain to which the identifier belongs.
  • パートナー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.

  • 送信メッセージのセキュリティ Whether to sign and/or encrypt outgoing AS4 messages. Signatures and encryption are strongly recommended.
  • 受信メッセージのセキュリティ 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.
  • 圧縮 Whether to compress the payload of outgoing messages.
  • 接続タイムアウト The length of time the connector will wait for a connection response before throwing a timeout error.
  • プロファイル 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.
  • メッセージパーティションチャネル 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.

  • レシートを使用 Whether a Receipt should be returned in response to incoming AS4 messages, and expected in response to outgoing AS4 messages.
  • デリバリー 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.

  • 暗号化証明書 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.
  • 検証証明書 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 暗号化証明書 to verify signatures.
  • SSL サーバー証明書 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.

  • サービス The business process accepting the message.
  • サービスアクション The operation or activity being executed in the business process.
  • サービスの種類 The optional qualifier providing context to the サービス.
  • 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.

  • 送信 Whether files arriving at the connector will automatically be sent as AS4 messages.
  • 再試行間隔 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.
  • 再送信間隔 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.
  • 受信 Whether the connector should automatically make pull requests to receive messages from the trading partner.
  • Pull 間隔 The interval between automatic pull requests.
  • The number of minutes to wait before downloading. Only applicable when Pull 間隔 is set to Minute.
  • 毎時何分 The minutes offset for an hourly schedule. Only applicable when Pull 間隔 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.
  • The time within a given day that the pull request should occur. Only applicable when Pull 間隔 is set to Daily, or Weekly, or Monthly.
  • The day on which the pull request should occur. Only applicable when Pull 間隔 is set to Weekly or Monthly.
  • Cron 式 An arbitrary string representing a cron expression that determines when the pull request should occur. Only applicable when Pull 間隔 is set to Advanced.

Advanced Tab

Token Authentication

Settings related to using and requiring token authentication.

  • トークン認証が必要 Whether authentication tokens must be included in incoming AS4 messages. If enabled, incoming messages must include username credentials that match the ユーザー名 and パスワード fields set under this option.
  • トークン認証を使用 Whether authentication tokens should be included in outgoing AS4 messages. If enabled, outgoing messages will include username credentials that match the ユーザー名 and パスワード fields set under this option.
  • パスワードの種類 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.

  • パーティ識別子 Your AS4 identifier. Overrides パーティ識別子 in the Profile section.
  • パーティ識別子の種類 Optionally, your AS4 identifier type. Overrides パーティ識別子の種類 in the Profile section.
  • プライベート証明書 The certificate that will be used to decrypt incoming messages and sign outgoing messages. Overrides プライベート証明書 in the Profile sections.
  • 証明書のパスワード The password required to access the local private certificate.

SSL Client Authentication

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

  • [プロファイル]タブのプライベート証明書を使用 Whether to use the same プライベート証明書 configured in the Profile page as the SSL certificate for client authentication.
  • プライベート証明書 The private certificate presented during SSL client authentication. Only applicable if not using the same private certificate from the Profile page.
  • 証明書のパスワード 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 の種類 The reference type attribute of the shared AS4 agreement.
  • XML ファイルを添付 Whether XML payloads should be packaged as a MIME attachment to the SOAP message, or included directly in the SOAP body.
  • 暗号化アルゴリズム The algorithm to use when encrypting outgoing AS4 messages.
  • 送信フィルタ 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. ログレベル The verbosity of logs generated by the connector. When requesting support, it is recommended to set this value to Debug.
  • ログをリクエスト 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.
  • 親コネクタ 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.
  • URL をプル The URL endpoint to which pull requests should be sent, if different from the パートナーURL.
  • レシートURL The URL endpoint to which Receipts should be sent, if different from the パートナーURL.
  • 署名アルゴリズム The algorithm to use when signing outgoing messages. The same algorithm will be requested for the corresponding Receipts.
  • 重複メッセージへのアクション 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 が有効化されたプロトコル 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 ArcESB.

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 証明書をアップロード in the Private Certificate menu to select an existing certificate from disk.
  • Create a new self-signed certificate by clicking 証明書を作成. 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 ArcESB listening endpoint.

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

パートナーの設定

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 URL をプル and レシート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. ArcESB 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 暗号化証明書 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 検証証明書.

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 サーバー証明書. 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 レシートを使用 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 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 送信オートメーション 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 テストファイルを作成 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.