Nav

AS2 Connector 2.0.0

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

Introduction

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

  • Install the AS2 Connector.

  • Build a simple Hello World project.

  • Run the example project.

Prerequisites

This document assumes that you are familiar with Mule, the Anypoint Studio Essentials and Global Elements. Further, it is assumed that you are familiar with AS2 endpoints and have received endpoint configuration requirements.

Namespace and Schema Location

The XML namespace and schema location are as follows:

xmlns:as2="http://www.mulesoft.org/schema/mule/as2"

http://xsischemaLocation=[xsi:schemaLocation=]"

...

http://www.mulesoft.org/schema/mule/as2 http://www.mulesoft.org/schema/mule/as2/current/mule-as2.xsd"

Requirements

Installation

Installing AS2 Connector in Anypoint Studio

Follow the instructions for installing a Connector from Anypoint Exchange to install the AS2 Connector in Anypoint Studio.

Using AS2 Connector via Maven

If you wish to use the AS2 Connector in conjunction with Maven, please follow the instructions here.

Using This Connector

Use Cases

  • Send an AS2 Message

  • Receive an AS2 Message

  • Signed and/or encrypted and/or compressed AS2 messages

  • Signed or unsigned receipts

  • Synchronous or asynchronous receipts

  • HTTP/HTTPS support

Tips

  • Pick unique AS2 IDs per connector instance, it will help you track your messages

  • Test your trading partner ports and your own are open and reachable

  • It is recommended to use port 80 and 443 when possible (avoids mapping firewall rules for each partner)

  • When creating certificates, include it’s expiration date and your AS2 ID in the filename.

Adding to a Flow

Using the AS2 Connector in your application is explained in detail in the Example Use Case section below.

Example Use Case - Hello World

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

Receive any AS2 message over HTTP

Step 1

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

receive-example-step-1

Step 2

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

receive-example-step-2

Step 3

Drag the connector over to the canvas:

receive-example-step-3

Step 4

The connector requires an AS2 Connector Configuration. To create a connector configuration, you must first create a global HTTP endpoint and then bind the connector configuration to the endpoint. The connector’s operations leverage the HTTP endpoint to receive and send AS2 messages.

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

4+http+global

Step 5

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

5+configure+http

Step 6

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

6+as2+http

Step 7

Press OK to close the global HTTP endpoint dialog box:

7+endpoint

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:

image2015-6-25+21%3A7%3A49

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.

image2015-6-25+21%3A10%3A5

Step 10

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

image2015-6-25+21%3A11%3A5

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:

image2015-6-25+21%3A13%3A1

Step 11

The connector’s Key Store Path 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

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.

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”:

image2015-6-25+21%3A15%3A36

Step 13

Finally, run the example as a Mule application:

image2015-6-25+21%3A16%3A12

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

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:

image2015-6-26+9%3A7%3A18

Step 2

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

image2015-6-26+9%3A18%3A1

Step 3

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

image2015-6-26+9%3A19%3A48

Step 4

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

image2015-6-26+9%3A21%3A35

Step 5

The connector requires an AS2 Connector Configuration. To create a connector configuration, you must first create a global HTTP endpoint and then bind the connector configuration to the endpoint. The connector’s operations leverage the HTTP transport to receive and send AS2 messages.

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

image2015-6-26+9%3A23%3A54

Step 6

Give the endpoint HTTP connector 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:

image2015-6-26+9%3A25%3A58

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:

image2015-6-26+9%3A36%3A29

Step 8

Press OK to close the global HTTP endpoint dialog box:

image2015-6-26+9%3A28%3A33

Step 9

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

image2015-6-25+21%3A7%3A49

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 connector. Press OK.

image2015-6-26+9%3A31%3A14

Step 11

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

image2015-6-26+9%3A32%3A54

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:

image2015-6-26+9%3A37%3A25

Step 12

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

image2015-6-26+9%3A38%3A57

Step 13

The connector’s Key Store Path 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

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.

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 14

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.

image2015-6-26+9%3A41%3A2

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

Step 15

Finally, run the example as a Mule application:

image2015-6-26+9%3A41%3A51

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.