AS2 Connector

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

After reading this page you should be able to:

  • Install the AS2 Connector

  • Build a Hello World project

  • Run the project

Before you begin

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

Requirements

Use Cases

AS2 Connector functionality includes:

  • Sending an AS2 Message

  • Receiving an AS2 Message

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

  • Signed or unsigned receipts

  • Synchronous or asynchronous receipts

  • HTTP/HTTPS support

The use cases in this section illustrate this functionality.

Tips

  • Choose unique AS2 IDs for each connector instance to facilitate message-tracking.

  • Verify that both your trading partner ports and your own ports are open and reachable.

  • Use ports 80 and 443 when possible (this avoids mapping firewall rules for each partner).

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

Use Case: Receive any AS2 message over HTTP

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

Create a new Mule Project

Create a new Mule Project with Mule Server 4.0.0 EE or greater as runtime as shown in New Mule Project.

New Mule Project
Figure 1. New Mule Project

Install the AS2 Connector

Install the AS2 Connector by adding the dependency in your application’s POM file as usual.

<dependency>
   <groupId>com.modus</groupId>
   <artifactId>mule-as2-connector</artifactId>
   <version>1.0.0</version>
   <classifier>mule-plugin</classifier>
</dependency>

Anypoint Studio should resolve the AS2 plugin as shown in AS2 plugin.

AS2 plugin
Figure 2. AS2 plugin

Drag the connector over to the canvas

As shown in Drag Connector.

Drag Connector
Figure 3. Drag Connector

Create a Connector configuration

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 that 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 Listener Config as shown in Choose Global Type.

Choose Global Type
Figure 4. Choose Global Type

Rename the HTTP Endpoint

Give the HTTP endpoint a more descriptive name. For example, receive-as2-global-elements-http-endpoint, as shown in Global Element Properties.

Global Element Properties
Figure 5. Global Element Properties

Create configuration

Create an AS2 Receive config from the Global Elements view as shown in Choose Global Type.

Choose Global Type
Figure 6. Choose Global Type

Bind connector to endpoint

Type receive-as2-http-endpoint in the attribute Http endpoint ref to bind the AS2 connector to the previously created global HTTP endpoint, as shown in Global Element Properties.

.Global Element Properties
Figure 7. Global Element Properties

Click OK.

Verify view

Verify that the Global Configuration Elements view appears, as shown in Global Configuration Elements.

Global Configuration Elements
Figure 8. Global Configuration Elements

Select configuration

In the Message Flow view, on the AS2 message source, select as2-receive-config from the Connector configuration drop-down list, as shown in Message Flow View.

Message Flow View
Figure 9. Message Flow View

Configure Key Store Path attribute

The connector’s Key Store Path attribute must be configured in each 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. KeyStore Explorer is a cross-platform tool that can help you with the setting up of JKS key stores.

  • CloudHub deployments must have key stores located within the Mule application Java classpath (for example, src/main/resources. The key store path attribute must be relative to the classpath. For example, 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.

Scenarios 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 must 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 must 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 this case study simple, no key store is set; therefore no security is provided by the connector, as shown in Message Flow View.

Message Flow View
Figure 10. Message Flow View

Add operation

Add a File Write operation to save the sender’s AS2 message content. Should you be prompted to, select the latest version of the File connector to be installed.

Drag a File Write operation from the palette next to the AS2 Connector. Under Connector configuration create a new File Config by clicking on the plus sign. Set the Path attribute to inbox/data.txt, as shown in Message Flow View (File).

Message Flow View (File)
Figure 11. Message Flow View (File)

Run as Mule application

Finally, run the example as a Mule application, as shown in Run as Mule application.

Run as Mule application
Figure 12. Run as Mule application

The connector will save the content of valid AS2 messages in the file “data.txt” inside a folder in the users home directory named “inbox”.

Use Case: Send a clear and unsigned AS2 message over HTTP

Create a new project

Create a new Mule Project with Mule Server 4.0.0 EE as runtime, as shown in New Mule Project.

New Mule Project
Figure 13. New Mule Project

Add a file

Add a File On New or Updated File listener to the canvas to create a message source for a flow, as shown in Add file.

Add file
Figure 14. Add file

Should you be prompted to, select the latest version of the File connector to be installed. Under Connector configuration create a new File Config by clicking on the plus sign. Set the Directory attribute to outbox.

NOTE: All paths are relative to the user’s home directory by default.

Install the Connector

Install the AS2 Connector by adding the dependency in your application’s POM file as usual.

<dependency>
   <groupId>com.modus</groupId>
   <artifactId>mule-as2-connector</artifactId>
   <version>1.0.0</version>
   <classifier>mule-plugin</classifier>
</dependency>

Anypoint Studio should resolve the AS2 plugin, as shown in Resolve plugin.

Resolve plugin
Figure 15. Resolve plugin

Drag the operation to the canvas

Drag the AS2 Send operation over to the canvas, as shown in Drag Send operation.

Drag Send operation
Figure 16. Drag Send operation

Configure connector

The connector requires an AS2 Connector Configuration. To create a connector configuration, you must click on the plus sign next to Connector configuration within the AS2 Send configuration. Set the host and port attributes to point to an AS2 receiver, as shown in Configure Connector.

Configure Connector
Figure 17. Configure Connector

Press OK to close dialog box; the AS2 configuration will be automatically set to the operation.

Set up service path

Set up the Service Path of the AS2 receiver, as shown in Set up service path.

Set up service path
Figure 18. Set up service path

Click in the System Identifiers tab on the left. Populate the AS2-From and AS2-To attributes. The AS2-To identifier is typically provided out-of-band by the AS2 receiver.

Configure Key Store Path attribute

The connector’s Key Store Path attribute must be configured in each 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. KeyStore Explorer is a cross-platform tool that can help you with the setting up of JKS key stores.

  • CloudHub deployments must have key stores located within the Mule application Java classpath (for example, src/main/resources. The key store path attribute must be relative to the classpath. For example, 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.

Scenarios 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 must 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 must 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 this case study simple, no key store is set; therefore no security is provided by the connector, as shown in Message Flow View.

Message Flow View
Figure 19. Message Flow View

View receipt

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, as shown in Message Flow.

Message Flow
Figure 20. Message Flow

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

Run as Mule application

Finally, run the example as a Mule application, as shown in Run as Mule application.

Run as Mule application
Figure 21. Run as Mule application

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