Introduction

The AS2 Connector allows you to send and receive data from AS2 certified servers.

After reading this page you should be able to accomplish the following:

  • Install the AS2 Connector.

  • Build a Hello World project.

  • Run the project.

Prerequisites

Installing AS2 Connector

The following instructions were written for Anypoint Studio on OS X. Instructions may vary for other operating systems.

\1. Launch Anypoint Studio and click on Help → Install New Software.

installation step 1

\2. Select Anypoint Connectors Update Site - http://repository.mulesoft.org/connectors/releases/3.5.0 from the drop-down menu next to the Work with field. If you don’t see the update site, click Add to add it manually.

installation step 2

\3. Expand Premium and select the AS2 Connector version of your chosing. Uncheck Show only the latest versions of available software to see older versions. Press Next > to review the items to be installed.

installation step 3

\4. Press Next > again to review and accept the license. Press Finish to install the connector.

installation step 4.1 installation step 4.2

\5. Press OK to accept the prompted security dialog box and allow Anypoint Studio to restart.

installation step 5.1 installation step 5.2

Example Use Case - Receive any AS2 message over HTTP

The following example requires basic familiarity with AS2, Anypoint Studio, and Mule ESB.

Step 1

Create a new Mule Project with Mule Server 3.6.0 EE as runtime:

example step 1

Step 2

Locate the AS2 Connector on the right hand-side palette:

example step 2

Step 3

Drag the connector over to the canvas:

example step 3

Step 4

The connector’s operations leverage the HTTP transport to receive and send AS2 messages. Both endpoint-based and operation-based versions of the HTTP transport are supported since version 2.2.0.

The connector requires an AS2 Connector Configuration. To create a connector configuration, you must first create either a legacy global HTTP endpoint or a HTTP Listener Configuration for receiving messages. Regardless of the HTTP implementation of your choice, you need then to bind the connector configuration to that endpoint.

Steps 5 to 10 depict the creation and association of a legacy (deprecated) HTTP endpoint.

For the current HTTP transport implementation usage jump to Step 11.

Step 5

Click on the Global Elements tab and create an HTTP endpoint:

example step 4

Give the HTTP endpoint a more descriptive name like “receive-as2-http-endpoint”. Click on the Connector Configuration add symbol to bring up the HTTP connector configuration dialog:

example step 5

Step 6

Give the HTTP connector a more descriptive name like “as2-http-connector” and press OK to go back to the global HTTP endpoint dialog box:

example step 6

Step 7

Press OK to close the global HTTP endpoint dialog box:

example step 7

Step 8

In this step, you will make an AS2 connector configuration and bind it to the global HTTP endpoint. Create an AS2 Connector Configuration from the Global Elements view:

example step 8

Step 9

Type “receive-as2-http-endpoint” in the attribute Global HTTP Endpoint Reference to bind the AS2 connector to the previously created global HTTP endpoint. Press OK.

example step 9

Step 10

After completing the previous steps, you should have the following in the Global Elements view:

example step 10.1

Step 11

(if you’ve chosen the legacy HTTP endpoint implementation, skip to Step 14)

Click on the Global Elements tab and create an HTTP Listener Configuration:

Give the HTTP Listener Configuration a more descriptive name like “receive-as2-http-endpoint”.

Press OK to close the global HTTP endpoint dialog box.

Step 12

In this step, you will make an AS2 connector configuration and bind it to the global HTTP endpoint. Create an AS2 Connector Configuration from the Global Elements view:

example step 8

Step 13

Type “receive-as2-http-endpoint” in the attribute Global HTTP Endpoint Reference to bind the AS2 connector to the previously created global HTTP endpoint. Press OK.

example step 9

Step 14

Back to the Message Flow view, on the AS2 message source, select “AS2” from the Connector Configuration drop-down list and select “Receive” from the Operation drop-down list:

example step 10.2

Step 11

The connector’s Key Store Path1 attribute must be configured in either of the following scenarios:

  1. Connector receives a signed request

  2. Connector receives an encrypted request

  3. Sender requests a signed receipt

For scenario 1, the key store has to contain the certificate used by the AS2 connector to verify the request’s authenticity. Scenario 2 and 3 require the key store to have a dual-purpose public/private key pair that the connector uses to decrypt the request and sign the receipt. The key store entry alias name for the certificate is required to match the AS2-From field received in the request’s headers. Similarly, the key store entry alias name for the public/private key pair is required to match the AS2-To field received in the request’s headers. The attribute Key Store Password must be set if the key store is protected by a password.

For the sake of keeping the example simple, no key store is set so no security is provided by the connector.

Step 12

Add a File outbound endpoint to save the sender’s AS2 message content. Drag a File outbound endpoint from the palette next to the AS2 Connector. Set the Path attribute to “inbox” and Output Pattern to “data.txt”:

example step 12

Step 13

Finally, run the example as a Mule application:

example step 13

The connector will save the content of valid AS2 messages in the file “data.txt” inside the project root directory “inbox”.

Example Use Case - Send a clear and unsigned AS2 message over HTTP

Step 1

Create a new Mule Project with Mule Server 3.6.0 EE as runtime:

example step 1

Step 2

Drag a File inbound endpoint to the canvas to create a message source for a flow. Set the Path attribute to “outbox”:

example step 2

Step 3

Locate the AS2 Connector on the right hand-side palette:

example step 3

Step 4

Drag the connector over to the canvas next to the File message source:

example step 4

Step 5

The connector’s operations leverage the HTTP transport to receive and send AS2 messages. Both legacy and current versions of the HTTP transport are supported since version 2.2.0.

The connector requires an AS2 Connector Configuration. To create a connector configuration, you must first create either a legacy global HTTP endpoint or a HTTP Request Configuration for sending messages. Regardless of the HTTP implementation of your choice, you need then to bind the connector configuration to that endpoint.

Steps 6 to 10 depict the creation and association of a legacy (deprecated) HTTP endpoint.

For the current HTTP transport implementation usage jump to Step 11.

Step 6

Click on the Global Elements tab and create an HTTP endpoint:

example step 5

Give the HTTP endpoint a more descriptive name like “send-as2-http-endpoint”. Set the host, port and path attributes to point to an AS2 receiver. Click on the Connector Configuration add symbol to bring up the HTTP connector configuration dialog:

example step 6

Step 7

Give the HTTP connector a more descriptive name like “as2-http-connector” and press OK to go back to the global HTTP endpoint dialog box:

example step 7

Step 8

Press OK to close the global HTTP endpoint dialog box:

example step 8

Step 9

In this step, you will make an AS2 connector configuration and bind it to the global HTTP endpoint. From the Global Elements view, create an AS2 Connector Configuration:

example step 9

Step 10

Type “send-as2-http-endpoint” in the attribute Global HTTP Endpoint Reference to bind the AS2 connector to the previously created global HTTP endpoint. Press OK.

example step 10

After completing the previous steps, you should have the following in the Global Elements view:

example step 11.1

Step 11

(if you’ve chosen the legacy HTTP endpoint implementation, skip to Step 14)

Click on the Global Elements tab and create an HTTP Listener Configuration:

Give the HTTP Listener Configuration a more descriptive name like “send-as2-http-endpoint”. Set the host, port and basePath attributes to point to an AS2 receiver.

Press OK to close the global HTTP endpoint dialog box.

Step 12

In this step, you will make an AS2 connector configuration and bind it to the global HTTP endpoint. From the Global Elements view, create an AS2 Connector Configuration:

example step 9

Step 13

Type “send-as2-http-endpoint” in the attribute Global HTTP Endpoint Reference to bind the AS2 connector to the previously created global HTTP endpoint. Press OK.

example step 10

Step 14

Back to the Message Flow view, on the AS2 processor, select “AS2” from the Connector Configuration drop-down list and select “Send” from the Operation drop-down list:

example step 11.2

Step 15

Populate the AS2-From and AS2-To attributes. The AS2-To identifier is typically provided out-of-band by the AS2 receiver.

example step 12

Step 16

The connector’s Key Store Path1 attribute must be configured in either of the following scenarios:

  1. Connector sends a signed request

  2. Connector sends an encrypted request

  3. Receiver returns a signed receipt

Scenario 1 and 2 require the key store to have a dual-purpose public/private key pair that the connector uses to encrypt and sign the request. For scenario 3, the key store has to contain the certificate used by the AS2 connector to verify the receipt’s authenticity. The key store entry alias name for the public/private key pair is required to match the value set in the AS2 From attribute. Similarly, the key store entry alias name for the certificate is required to match the value set in the AS2 To attribute. The attribute Key Store Password must be set if the key store is protected by a password.

For the sake of keeping the example simple, no key store is set so no security is provided by the connector.

Step 17

Viewing the receipt returned by the AS2 receiver is optional but useful for testing. Append to the flow a Byte Array to String transformer followed by a Logger processor to print the receipt’s content to console.

example step 14

Note that the Logger in the screenshot has its Message attribute set to "#[payload]"

Step 18

Finally, run the example as a Mule application:

example step 13

Drop a file in the "outbox" directory to send it to the receiver over AS2. If you have followed step 14, you should see the receiver’s receipt in the console.

1: The key store must be in JKS format. A cross-platform tool that can help you with the setting up of JKS key stores is KeyStore Explorer. CloudHub deployments must have key stores located within the Mule application Java classpath (e.g., src/main/resources). Furthermore, the key store path attribute has to be relative to the classpath. For instance, if the key store is located at src/main/resources/key-stores/my-key-store.jks, then Key Store Path is set to key-stores/my-key-store.jks.