Versions Compared

Version Old Version 4 New Version Current
Changes made by

Rohitashva Gaurava

Rohitashva Gaurava

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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

AS2

...

Personal Id

Settings for identifying the local profile.

  • Connector IdThe static name of the connector. All connector-specific files are held in a folder by the same name within the Data Directory.

  • Connector DescriptionAn optional field to provide free-form description of the connector and its role in the flow.

  • AS2 IdentifierYour AS2 identifier. Messages sent by Justransform will include this value as the ‘AS2-From’ header. Incoming messages must have this value set as the ‘AS2-To’ header to be successfully received. AS2 Identifiers are case-sensitive.

Personal Certificate

Settings related to the private decryption and signature certificate.

  • Private CertificateThe 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 AS2 transaction; a corresponding public key will also be generated with the same filename and a ‘.cer’ extension.

  • Certificate PasswordThe password required to access the Private Certificate.

  • Rollover Private CertificateA secondary private certificate that can be used to decrypt incoming messages if decryption with the Private Certificate fails. This setting should be used only when transitioning certificates and an overlap period is necessary to accept incoming messages encrypted with either the old or the new certificate. Note that the rollover certificate is never used to sign outgoing messages, which may cause signature verification issues when sending to trading partners that are still using the old certificate.

  • Rollover Certificate PasswordThe password required to access the Rollover Private Certificate.

Application URLs

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

  • Public DomainThe publicly-accessible domain or IP address for the server hosting Justransform. The application will use this value to generate URLs for endpoints that are important for receiving transmissions and responses. Any partners that need to connect to the application should be granted firewall access to the specified domain.

  • Asynchronous MDN URLThe URL at which Justransform will listen for asynchronous MDN responses. This value is automatically generated based on the Public Domain and the default MDN endpoint, ReceiveMDN.rsb. This endpoint rarely needs to be modified.

  • Receiving URLThe URL at which Justransform will listen for incoming AS2 messages. This URL should be advertised to all trading partners.

  • Publish my AS2 profile settings at Public.rstIf enabled, an endpoint will be exposed where trading partners can view AS2 configuration details including identifiers, URLs, algorithms, and certificates.

  • Public URLThe endpoint at which trading partners can view AS2 configuration details. This URL can be advertised to trading partners to simplify the communication of AS2 specifics.

  • Public CertificateThe public key certificate to be advertised in the public configuration page. This should be set to the encryption certificate that trading partners should use when sending AS2 messages to Justransform. This certificate should have the same name as the Private Certificate but with a ‘.cer’ extension.

Connector Configuration

After configuring the AS2 Profile, AS2 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 AS2 trading partner.

  • AS2 IdentifierThe AS2 identifier specific to the target trading partner. This value is included in the AS2 headers for outgoing messages, and it is also used to route incoming AS2 messages to the appropriate AS2 Connector.

  • Partner URLThe trading partner’s public endpoint where outgoing AS2 messages should be sent.

Connection Info

Settings related to connection parameters for the specified trading partner.

  • Send Message SecurityWhether to sign and/or encrypt outgoing AS2 messages. Signatures and encryption are strongly recommended.

  • Receive Message SecurityWhether to require that signatures and encryption are present for incoming AS2 messages. An error will be thrown if a received message does not have a required security parameter.

  • CompressionWhether to compress the payload of outgoing messages.

  • Connection TimeoutThe length of time the connector will wait for a connection response before throwing a timeout error.

MDN Receipts

Settings related to requesting MDNs when sending AS2 messages.

  • Request MDN ReceiptWhether an MDN Receipt should be returned in response to outgoing AS2 messages. Requesting MDN Receipts is strongly recommended.

  • SecurityWhether the MDN Receipt should include a signature block verifying the message integrity and identity of the recipient. MDN Security is strongly recommended.

  • DeliveryWhether the MDN should be returned as a direct response to the outgoing AS2 message (Synchronous) or returned later as part of a separate connection (Asynchronous). Synchronous MDNs are recommended unless the size of AS2 messages is very large (50MB is a common threshold), in which case processing the message and delivering a synchronous MDN may strain the connection timeout duration.

Trading Partner Certificates

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

  • Encryption CertificateThe public key certificate used for AS2 encryption when sending messages. This certificate must be paired with the trading partner’s private certificate, and the trading partner should provide a public key certificate when sharing AS2 configuration details.

  • SSL Server CertificateThe public key certificate used to verify the identity of an SSL/TLS server. Only necessary if the partner’s AS2 system requires HTTPS (rather than HTTP). If the trading partner does not provide an SSL server certificate, this setting can be set to ‘Any Certificate’ to unconditionally trust the target server’s identity.

Public Profile

The AS2 profile configuration details published on a public endpoint accessible to trading partners. This endpoint is configured within the Profile page.

Automation Tab

Automation Settings

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

  • SendWhether files arriving at the connector will automatically be sent as AS2 messages.

  • Retry IntervalThe 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.

  • Retry Maximum AttemptsThe maximum number of times a failed send will be retried before an error is thrown by the connector.

  • Resend IntervalThe amount of time before unacknowledged messages are resent. A resend is triggered when the server receives the file, but an asynchronous MDN Receipt is not provided within the expected timeframe.

  • Resend Maximum AttemptsThe maximum number of times a file will be resent before an error is thrown by the connector.

Advanced Tab

Very Large Message Support (VLM)

Settings used to support sending large AS2 messages.

  • Streaming - (HTTP chunked transfer encoding)Whether to use HTTP Chunked Transfer Encoding when sending messages. This allows the application to send portions (chunks) of the message sequentially to avoid overloading the connection. Note that not all AS2 systems support this type of transmission.

  • AS2 RestartWhether to support resuming transmissions that were interrupted. This is useful when streaming large messages in chunks. Note that not all AS2 systems support this feature.

Reliability

Settings related to the Reliability feature of the AS2 protocol.

  • AS2 ReliabilityWhether to reuse AS2 Message IDs when re-sending a document. This helps prevent the same document from being processed twice on the receiving side.

Local Folders

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 AS2 configuration in the Profile page for this specific AS2 Connector. Setting an alternate local profile allows the use of different local certificates and identifiers for certain trading partners.

  • Local AS2 IdentifierYour AS2 identifier. Overrides AS2 Identifier in the Profile section.

  • Private CertificateThe certificate that will be used to decrypt incoming messages and sign outgoing messages. Overrides Private Certificate in the Profile section.

  • Certificate PasswordThe 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 tabWhether to use the same Private Certificate configured in the Profile page as the SSL certificate for client authentication.

  • Private CertificateThe private certificate presented during SSL client authentication. Only applicable if not using the same private certificate from the Profile page.

  • Certificate PasswordThe password required to access the SSL client certificate.

HTTP Authentication

Settings related to HTTP client authentication.

  • Use HTTP AuthenticationWhether client HTTP Authentication is enabled.

  • HTTP Authentication TypeWhether 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).

  • UserThe User credential for HTTP client authentication.

  • PasswordThe Password credential for HTTP client authentication.

Custom Headers

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

Performance

Settings related to the allocation of resources to the connector.

  • Max WorkersThe 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 FilesThe 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.

  • Async MDN TimeoutThe length of time the connector will wait for a connection when receiving an asynchronous MDN before throwing a timeout error.

  • Duplicate File ActionHow the connector should behave when receiving an AS2 message with a filename that the connector has seen before. If set to Warning, the connector will process the file but return a warning in the MDN. If set to Failure, the connector will not accept the file and return an error in the MDN. The connector will “remember” filenames that are received for a duration according to Duplicate File Interval.

  • Duplicate File IntervalThe length of time, in minutes, that a file with the same filename will be considered a duplicate. In other words, the length of time the connector will “remember” that a specific filename has already been received. If set to 0, the filenames will be stored until the server is restarted.

  • Encryption AlgorithmThe algorithm to use when encrypting outgoing AS2 messages.

  • Send FilterA 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.

  • Extension MapA set of name-value pairs that maps file extensions to the desired HTTP Content-Type header value. By default, the application will map the following file extensions to content types:
    .xml -> application/xml
    .edi or .x12 -> application/edi-x12
    .edifact -> application/edifact.
    All other file extensions are sent with an application/octet-stream content type. To add or overwrite mappings, this setting should be a comma-delimited list in extension=contenttype syntax (e.g. .txt=text/plain,.edi=application/edifact).

  • HTTP SubjectThe HTTP Subject header to be included in the outgoing AS2 message. This header is not used in the AS2 protocol, but may be used by some solutions for additional business logic processing.

  • Log Debug InfoWhether enhanced logging is enabled for the connector. When requesting support, it is recommended to generate debug logs and provide these along with the support request.

  • Log RequestsWhether 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.

  • Message IdUsed to overwrite the AS2 Message Id automatically generated by the connector.

  • Temp Receive DirectoryIf set, the application will write received files to the temporary directory as they are received, then move the finished file to the Receive directory. This ensures that partial files are never present in the Receive directory, even when receiving very large files.

  • Parent ConnectorThe 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.

  • Parse FDA ExtensionsWhether to parse outgoing filenames to include FDA-specific headers in the AS2 message. If enabled, files in the Send directory should have the FDA center and the FDA submission type as the first two parts of the filename, separated by periods (e.g. CDRH.eMDR.myfile.txt). The application will automatically translate these filename prefixes into the appropriate FDA-required headers.

  • Signature AlgorithmThe algorithm to use when signing outgoing messages. The same algorithm will be requested for the corresponding MDN receipts.

  • Partner Signing CertificateIf the trading partner uses separate private certificates to sign messages and to decrypt messages, this should be set to the public key certificate that corresponds to the partner’s signing certificate. The trading partners should be able to provide this public key certificate.

  • Log MessagesWhether the log entry for a processed file will include a copy of the file itself.

  • Save to Sent FolderWhether files processed by the connector should be copied to the Sent folder for the connector.

  • SSL Enabled ProtocolsThe 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.

Establishing a Connection

Trading partners must share some of the connection details that are required when configuring a new AS2 Connector. At a minimum, these details should include:

  • AS2 Identifier

  • Partner URL

  • Partner Certificates

AS2 Identifier

Your trading partner identifies themselves in an AS2 transaction via their AS2 Identifier. When sending outgoing requests, the AS2 Identifier is used in the header of the request to indicate the recipient.

To establish an AS2 self-test, the identifier should be set to the same value as the AS2 Identifier in the Profile section.

Note: This value is case-sensitive.

Partner URL

The Partner URL is the endpoint where the trading partner receives AS2 transmissions. Outgoing AS2 messages are sent to this target endpoint, which much be unique for each trading partner. The Partner URL can be tested with a web browser to check for any networking or connectivity issues.

To establish an AS2 self-test, the target URL should be either identical or nearly identical to the Receiving URL in the Profile page. The Public Domain name from the Profile page can be replaced with the loopback address ‘localhost’ to keep the AS2 transaction within the local network.

If the Public Domain name is not replaced with ‘localhost’, then the AS2 message is routed outside of the local network. This can be used to check network configuration settings and to make sure that the message can reach Justransform through any firewalls.

Trading partners may sometimes provide more than one URL: a Receiving URL and a URL for asynchronous MDNs. In this case, only the Receiving URL (Partner URL) needs to be configured; the application can read the Asynchronous MDN URL from incoming AS2 transmissions.

Partner Certificates

Each AS2 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 AS2 messages exchanged with them. Justransform 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). Rarely, a separate public key certificate may be required to verify the partner’s digital signatures. In this case, set the signature verification certificate under Advanced -> Other Settings -> Partner Signing Certificate.

To establish an AS2 self-test, the ‘test.cer’ public key certificate included with the application should be set as the Encryption Certificate and the ‘test.pfx’ private certificate should be set as the Private Certificate in the Profile page.

Send and Receive Files

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

Send Files

Within an AS2 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 packaged 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 AS2 Resend is triggered when the trading partner is expected to return an asynchronous MDN, 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 Resend Maximum Attempts 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 Retry Maximum Attempts is exhausted.

Receive Files

Within an AS2 Connector, the Output tab displays the files that have been received by the application and routed to the connector (based on the AS2 identifiers present in the incoming AS2 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 AS2 Connector to the Send directory of the next connector in the flow.

The AS2 protocol does not allow for actively pulling files from trading partners; the AS2 Connector can only passively wait for a trading partner to send a file.

Troubleshooting Receiving Files

Issues that occur when receiving AS2 messages may be harder to track down than issues that occur when sending files. When an error occurs while sending a file, the error is immediately reported in the Input tab (and Transaction Log) for the AS2 Connector. When receiving files, errors and other debug information may appear in multiple places.

After Justransform receives an AS2 message, it attempts to route that message to a specific AS2 Connector, based on the AS2 Identifier configured in the connector (and the AS2 Identifiers present in the incoming message). There are three possible locations to check for logging information, depending on whether this routing operation succeeds:

  • The Output tab for the AS2 Connector (configured for this trading partner) will have error logs if Justransform could successfully route the message.

  • The Application Log will have error logs if Justransform could not successfully route the message.

  • If no logs appear in the AS2 Connector nor the Application Log, then the AS2 message never reached Justransform in the first place.

...

Common Connection Details:

Refer to Common Connection Modules

Protocol Config

AS2 From

AS2 To

Subject

Message Polling Interval

URL

Encryption Algorithm

MIME Type

MDN Required

MDN Security

MDN Delivery

Outgoing Message Security

Incoming Message Security

Certificate

JT Server Information

AS2 Server

URL:http://localhost:8080/justransform/as2/receive

AS2 Certificate 

...

What Happens in an AS2 Exchange

...