Adding an AS2 Partner

1 What is an AS2 Partner

An AS2 Partner definition within the AS2Gateway specifies details about a trading partner, with which your Organization would be exchanging messages using AS2. Similar to an AS2 Station, a Partner has a unique AS2 ID, URL and certificates. You will select the Partner, when sending AS2 messages through the AS2Gateway. When messages are received into your AS2 inbox, they will also list the Partner from whom they have been received.

2 Creating an AS2 Partner

Partners need to be added/declared on AS2 Gateway, before you can send, as well as receive, messages from them. Declaring a Partner requires some information from the respective remote party, such as its AS2 ID, URL and certificate/s. (These are the information of the remote trading station corresponding to the ‘Partner Configuration’ that we saw on our local trading station page in the previous section).

To add a partner, first go to the partners view using the ‘Partners’ icon on the left navigation menu. Then click the ‘New Partner’ button.

2.1 Basic information of a Partner

Provide the required information to configure the trading partner you are about to add. Your Partner would be sending you this information, usually through email.

Specify a name for the trading partner. This is a textual identifier for you to easily distinguish this partner from others in the system. This will be very helpful when your partners use cryptic AS2 identifiers, such as 08925485US00 by Walmart. The name will not be used within the AS2 communications.
Specify the AS2 Identifier of the partner, which will be provided to you by your Partner.
Specify the partner URL that your Partner will provide you. It will be used to send messages to this partner, and the partner would be listening on this URL for incoming messages.
Provide a default message subject (similar to an email subject line) which will be used if a subject has not been specified when sending messages. A subject line is optional, and you can leave this to its default value.
Opening the ‘Advanced Options’ section below if you would be needing to configure any advanced configuration options
Upload the partner’s public certificate, which will be provided by your Partner. AS2 Gateway will use this to encrypt messages (if encryption has been enabled for outgoing messages), so that they can only be decrypted on the partner’s end, using the corresponding private key.
Click the Save button to submit the form.

Once the partner has been created, you will land back in the partner list view. Now that we have a station and a partner, we can proceed to sending our first message!

Testing the partner URL

In order to ensure that the partner URL you entered is reachable by its internal AS2 transmission system, AS2G requires you to run a connectivity test when you enter or modify a partner URL. For this, you can simply click the Test button next to the URI field.

During the test, AS2G will try to establish a simple TCP connection to the remote endpoint, performing a TLS (SSL) handshake if necessary (if the URL scheme is HTTPS, https://). It will not transmit any data or make any attempt to initiate a HTTP request, so the partner system will not be notified or affected. Upon success, AS2G will simply disconnect from the partner endpoint using normal TCP semantics.

If AS2G fails to connect to the endpoint within 10 seconds, or faces an issue during TLS handshake, it will mark the connectivity test as a failure.

Some common issues that can lead to connectivity failures, along with possible resolutions, are mentioned in the troubleshooting guide.

2.2 Advanced configuration for an AS2 Partner

Use different certificate as sign certificate

While most AS2 partners use the same certificate and key-pair for both encryption and digital signatures, there are some partners who use two different ones. If your partner uses two certificates, slide the ‘Use different certificate as sign certificate’ to enable you to upload a separate certificate for digital signatures. In addition, if your partner requires a custom SSL certificate to be trusted to establish a TLS/SSL connection, you can upload it by opening the ‘HTTPS (TLS/SSL)’ section and uploading the SSL certificate and any Chain certificates.

2.2.1 Encrypt Messages

Specifies if messages should be encrypted, and if so using which algorithm. Encryption would generally be enabled for all partners, as its one of the key advantages of the AS2 protocol. AES 256 or Triple DES are most commonly used.

The following encryption algorithms are currently supported in AS2 Gateway:

Triple DES (168-bit): DES_EDE3_CBC
AES (128-bit): AES128_CBC
AES (192-bit): AES192_CBC
AES (256-bit): AES256_CBC
Camellia (128-bit): CAMELLIA128_CBC
Camellia (192-bit): CAMELLIA192_CBC
Camellia (256-bit): CAMELLIA256_CBC
CAST5/CAST-128 (128-bit): CAST5_CBC
RC2/ARC2 (40-bit): RC2_CBC
SEED (128-bit): SEED_CBC

2.2.2 Sign Messages

Specifies if messages should be digitally signed, and if so using what sign digest algorithm. Digital signatures are generally enabled for all partners, as its one of the key advantages of the AS2 protocol. SHA-256 or SHA-1 is most commonly used

The following signing (digest) algorithms are currently supported in AS2 Gateway:

SHA1
MD5
MD2
SHA224
SHA256
SHA384
SHA512

2.2.3 Compress Messages

You can specify if compression should be used, especially if your Partner has requested so. If your Partner supports compression, large EDI or text files could be compressed well for transmission as smaller payloads.

You can choose to run the compression:

Before signing and/or encryption i.e. on the original set of files that you included in the message; in this case, the partner would need to first decrypt/verify the payload, and then decompress it
After signing and/or encryption i.e. compression would be the last (outermost) action or “layer” on the payload; in this case, the partner would need to first decompress the payload, and then decrypt/verify the content

2.2.4 Request MDN

You can choose to request a MDN, which is the default and most widely used option, or, choose to turn it off if your partner has specifically informed you to.

2.2.5 Request Asynchronous MDN

You can also specify if messages sent to this Partner should request an asynchronous MDN. By default, this is off, and the AS2 Gateway will be requesting a synchronous MDN. However, if your Partner specifies that it will be issuing an asynchronous MDN, you would need to switch this on.

In this case, AS2 Gateway will inform the partner system where (the URL/endpoint) to send the asynchronous MDN, by including an additional Receipt-Delivery-Option HTTP header on each AS2 message. This URL is, by default, http://service.as2gateway.com:8280/service/as2-async-mdn-receiver (or the test-service.as2gateway.com variant, in case of a test-type partner); see below for possible customizations of the URL.

Request MDN over HTTPS

If your partner requires a HTTPS/secure URL (instead of plain HTTP) for sending asynchronous MDNs back, you can switch this option on. Note that the option is available only in asynchronous-MDN mode (Request Asynchronous MDN turned on).

2.2.6 Request Digitally Signed MDN

You can choose to request a digitally signed MDN for non-repudiation, a key advantage of the AS2 protocol. By saving the receiving MDN, you can prove that the Partner had received the exact version of the message that was sent. By default, this is enabled, as its widely used.

2.2.7 Partner Type

This is an advanced feature, which allows two configurations (i.e. Testing and Production) to share the same AS2 IDs. By default, the partner type is set to Production and it should be left unchanged. Even if your partner has a Testing and Production configuration - but with two distinct AS2 ID’s, this feature is NOT required. Please refer the Partner Types reference for more details.

2.2.8 Description

Specify a description of your trading partner; mainly just for identification purposes within your AS2 Gateway account.

2.2.9 Message Subject

Specify a default message subject, which will be used if a subject is not specified when sending a message (e.g. via SFTP outbox uploads, or API-based submissions without a subject query parameter)

Customizing the message subject

You can use placeholder expressions in the message subject line, to instruct AS2G to dynamically generate the subject at message queueing time:

${filename}: name of the file being sent (first file, if the submission contains multiple files)
${message.as2_id}: AS2 identifier (Message-ID) of the message being composed/sent
${message.profile}: name of the sending profile being used (or “(no profile)” if a profile has not been selected at submission time)
${station.as2_id}: AS2 identifier of the sending station/identity
${station.name}: name of the sending station/identity

If you are using a submission mechanism that also allows specifying a message subject (such as the web dashboard or the REST API), you can also override the default subject (set under the partner settings) by specifying a subject while sending each message. In all other cases (e.g. file submissions via SFTP uploads, or web-UI submissions without specifying a subject), AS2G will use the partner-level message subject with any placeholder expressions resolved as described above.

Contact the development team if you would like to see support for additional data elements as placeholders.

2.2.10 Custom Headers

Some trading partners require you to send additional HTTP headers along with a standard AS2 message (e.g. for authentication or routing purposes). You can use this option to add one or more such headers as key-value pairs.

For example, to add the two headers

X-Cyclone-Routing-Key: ACME_PROD
Authorization: Basic abcdefgh1234

Click +, to add a new key-value pair.
Enter X-Cyclone-Routing-Key (excluding the colon and space, : ) on the Header Key field.
Enter ACME_PROD on the Header Value field.
Repeat above steps for the second header: key Authorization, value Basic abcdefgh1234.

To remove an already defined header, click the dustbin-icon button against that row.

Note:

Header keys cannot be left empty. If you submit an entry with an empty header key, it will be ignored.
Headers will be included in the AS2 message (HTTP request) in the order they are defined.

Using Basic Authentication

If your partner provides you with a username/password pair to use as basic authentication, you need to derive the header value as:

"Basic "base_64_encode(username":"password)

E.g. for username foo and password bar, the header would be:

Header Key: Authorization
Header Value: Basic Zm9vOmJhcg==

Once added, these headers will be included in every AS2 message that you send to this partner. If you have any advanced requirement, contact AS2 Gateway support for more information.

2.2.11 Use AS2 Restart

AS2 Restart optional profile for outgoing messages, allows AS2G (the sender) to resume an interrupted AS2 transfer from the last-known successful position. It is only supported by some partners (receivers/servers), so it is recommended to verify with the partner before enabling this option.

2.2.12 Transmission Timeout

After sending an AS2 message, AS2 Gateway waits for a finite amount of time to receive the network-level (HTTP) response for the transmission. If the response is not received within this time, the transmission is considered as a failure.

If your partner’s AS2 system generally tends to take a long time to respond, you may start getting many such “connection timed out” errors. In such cases, you can try increasing this Transmission Timeout value to tolerate such large delays, instead of failing at the default 60-second (1-minute) timeout.

The transmission timeout does not apply to asynchronous MDNs; if you send a message requesting an asynchronous MDN, and the partner sends the HTTP-level response (network acknowledgement) within the time-out period, all would be fine - regardless of how long the partner may take to send the final MDN. Even if the MDN gets delayed by several hours, AS2 Gateway will continue retaining the message in “MDN pending” status until it is received.

2.2.13 Custom Integration Flows

These are additional features that you can enable, based on the nature of the partner or of the transmitted files/messages; for example,

FDA: when this integration is enabled on a partner representing U.S. Food and Drug Authority (FDA) (e.g. ZZFDATST or ZZFDA), submissions sent to the partner will be automatically tracked and tagged using correlation information (e.g. FDA Core-ID) available in received ACKs/responses. Refer to the FDA communication reference for more details.
EMA: when this integration is enabled on a partner representing European Medicines Agency (EMA/EMEA) (e.g. ESUBVAL or ESUBPROD), submissions sent to the partner will be automatically tracked and tagged using correlation information (e.g. the original submission file name) available in received ACKs/responses.
EDIG: after enabling EDI Generator integration, enable this option on your EDI partners to automatically forward files received from them into EDI Generator. You can keep this turned off for partners that do not send EDI files, or whose files you do not wish to forward to EDI Generator.

3 AS2 Partner Overview

You can see all your existing AS2 partners, on the partner list view. This view also offers some additional actions and management options for the partner:

Send an AS2 message to the partner
View different message categories (inbox, outbox, etc.) filtered for the partner
View message send/receive statistics for the partner
Enable/disable incoming and/or outgoing messages for the partner
Delete the partner from your account