AS4 Nodes for n8n

Requirements: /n software Adapters for Microsoft BizTalk

Introduction

The /n software n8n nodes extend n8n with powerful integration capabilities backed by the /n software node library. This guide provides an overview of the following nodes:

• The AS4 Sender node implements a complete AS4 client within an n8n workflow and may be used to upload files to a remote AS4 server.
• The AS4 Trigger node implements a complete AS4 client within an n8n workflow and may be used to receive files from a server over a Message Partition Channel (MPC).
• The AS4Web Trigger node implements a fully-functional AS4 server, allowing n8n workflows to receive and process inbound AS4 messages through a webhook endpoint.

These nodes enable secure AS4-based EDI exchanges directly within an n8n workflow. This article provides an overview of the above AS4 nodes, their basic configuration, and common usage patterns.

Node Installation

Before proceeding, please ensure that the /n software n8n nodes have been installed successfully. For instructions on how to install the /n software n8n nodes, please refer to the installation guide here. Afterwards, assuming the mentioned node location is populated, simply restart your n8n server instance, and the /n software nodes should be searchable via the n8n UI.

Certificate Properties

Before discussing each node, the AS4 Sender, AS4 Trigger, and AS4Web Trigger nodes contain many properties that are used to specify certificates (whether they be public keys or private keys). When setting a certificate, there are five properties that may be utilized. As an example, we can look at the SigningCert* properties that are available in the AS4 Sender node, which are used to specify the private key certificate used to sign the outgoing AS4 request:

• SigningCertStore - This property specifies the name of the signing certificate. Depending on the certificate type (see below setting), this may be set to User and Machine certificate stores on Windows (e.g., MY, CA, ROOT, SPC), or a path to a local PFX file (C:\certs\test.pfx), for example.
• SigningCertStorePassword - This property specifies the password of the signing certificate, if one is applicable. In this case, since the signing certificate requires a private key, this property is usually required, though for properties using the public key (e.g., RecipientCertStorePassword), the password is not necessary.
• SigningCertStoreType - This property specifies the type of certificate used for signing. For a full list of supported properties, please refer to the product documentation; however, some possible types are "PFX File", "Machine", "PEMKeyFile", etc.
• SigningCertSubject - This property specifies the subject of the signing certificate, where the subject is a comma-separated list of distinguished name fields and values. This is especially useful if multiple certificates are contained within the store. The special value "*" picks a random certificate in the store.
• SigningCertThumbprint - This property specifies the thumbprint of the signing certificate. In the event that there are multiple certificates in the store with the same subject, this property can be specified to distinguish between those certificates. Assuming unique subjects amongst certificates in the same store, this property is not necessary to set.

AS4 Sender Node

The AS4 Sender node implements an AS4 client within an n8n workflow and is used to transmit files to a trading partner's AS4 server. At a minimum, the node must be configured with the identifiers of both trading partners and the destination URL.

The AS4FromId property specifies the Id of the sending party. This value represents your organization's AS4 identifier, and corresponds to the ebMS element "eb:Messaging/eb:UserMessage/eb:PartyInfo/eb:From/eb:PartyId". Optionally, the AS4FromIdType property (corresponding ebMS element: eb:Messaging/eb:UserMessage/eb:PartyInfo/eb:From/eb:PartyId@type) and the AS4FromRole property (corresponding ebMS element: eb:Messaging/eb:UserMessage/eb:PartyInfo/eb:From/eb:Role) may also be specified if needed. Note the default value of AS4FromRole is "http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/initiator".

The AS4ToId property specifies the Id of the receiving party. This value represents the receiving organization's AS4 identifier, and corresponds to the ebMS element "eb:Messaging/eb:UserMessage/eb:PartyInfo/eb:To/eb:PartyId". Optionally, the AS4ToIdType property (corresponding ebMS element: eb:Messaging/eb:UserMessage/eb:PartyInfo/eb:To/eb:PartyId@type) and the AS4ToRole property (corresponding ebMS element: eb:Messaging/eb:UserMessage/eb:PartyInfo/eb:To/eb:Role) may also be specified if needed. Note the default value of AS4ToRole is "http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/responder".

The URL property specifies the HTTP endpoint where the AS4 messages will be delivered. When the URL uses the "https" scheme, the message will be transmitted over SSL/TLS.

In addition to these required properties, several other settings are commonly configured to support message security and integrity. The SigningCert properties are used to specify your private key certificate to sign the outgoing message. Note that the receiver in this case should have your public key certificate in order to successfully verify the message. Additionally, the RecipientCert properties are used to specify the receiver's public key certificate to encrypt the outgoing message. Optionally, the SignerCert* properties may be specified to verify the signature on the response from the receiver.

After ensuring the above properties are set (if necessary), the data to upload may need to be set. The node may reference a file located on disk by specifying the EDIFileName property (and potentially the EDIType property, specifying the content type of the file here). In this case, the node reads the file and sends its contents as the AS4 payload.

Alternatively, the payload may be supplied as binary data produced by a previous node in the workflow. When binary input is used, the node reads the specified binary field and sends it as the message body. In this case, the EDIFileName property can be set as well, to attach a particular filename to the outgoing data. In this case, the component will not read data from the specified filename due to the presence of binary data.

After the component has successfully sent the data and optionally verified the received receipt, information regarding the request and receipt will be provided by the node. For example, this may look like (assuming a receipt is received):

[ { "ReceiptContent": "<eb3:Receipt xmlns:eb3=...>", "ReceiptRefToMessageId": "_5895631c-...", "ReceiptAS4ToId": "Test To Organization", "MessageId": "_5895631c-..." } ]

AS4 Trigger Node

The AS4 Trigger node implements a complete AS4 client within an n8n workflow and may be used to receive files from a server over a Message Partition Channel (MPC). Note that this node does not host a webhook and cannot process HTTP requests. For this functionality, please refer to the AS4Web Trigger node section here.

The AS4 Trigger node will establish a connection to an AS4 server, specified by the URL property. After connecting, the node will request messages to download from the MPC, which is specified via the MPC property. If the SendReceipt property is true (default), the node will automatically generate a receipt and send it with the next request.

To decrypt the incoming files, the DecryptionCert properties should be set your private key certificate. If the incoming messages are signed, the SignerCert properties should be set to the public key certificate of the server. If SendReceipt is true, the SigningCert* properties should be set to your private key certificate in order to sign the outgoing receipts.

Note that during each polling interval, the node will attempt to download all files present in the specified MPC.

The file content of each downloaded file is provided to the n8n workflow as binary data. Additionally, information regarding each file (and potentially, the receipt) is also provided as JSON. For example, this may look like:

[ { "ReceivedFileName": "test.edi", "EDIType": "image/jpeg", "EDIProperties": "", "EDISchemaLocation": null, "EDISchemaNamespace": null, "EDISchemaVersion": null, "AS4FromId": "Test From Organization", "AS4FromIdType": "", "AS4FromRole": "Sender", "AS4ToId": "Test To Organization", "AS4ToIdType": "", "AS4ToRole": "Receiver", "AgreementRef": "http://agreements...", "ConversationId": "some_id", "Service": "Examples", "ServiceAction": "StoreMessage", "ServiceType": "ServiceType", "MessageId": "10d1873a-...", "ReceiptContent": "<eb3:Receipt xmlns:eb3=...>", "ReceiptRefToMessageId": "10d1873a-...", "MessageProperties": "" } ]

Given multiple files, there should be multiple entries (data contained within curly braces {}) here, each representing the information associated with each respective file.

AS4Web Trigger Node

The AS4Web Trigger node implements a fully functional AS4 server that can communicate with your n8n workflow. To use the node, you must configure the AS4SiteURL where the AS4 endpoint is hosted.

The TradingPartner property specifies the identity of the sending system, i.e., the trading partner's AS4 identifier.

The ReceivingPartner property specifies the identity of the receiving system, i.e., your AS4 identifier.

The node will read all incoming AS4 requests and verify these values to ensure that the message originates from a known trading partner and is intended for the correct receiving entity.

Note that the node listens for inbound HTTP requests through an n8n webhook endpoint and processes incoming AS4 messages before passing the data to the workflow. The AS4SiteURL property must be set to the URL assigned to the node's webhook endpoint.

Certificates may also be configured to enable decryption, signature validation, and signing of outgoing receipts (if needed by the client). The DecryptionCert properties specify the private key used to decrypt the incoming messages. The SignerCert properties specify the public key certificate of the trading partner and is used to verify the signature of the incoming AS4 message. To sign receipts sent back to your partner, the SignerCert* properties should be set to your private key certificate (note if a receipt should be sent, set the SendReceipt property to Yes).

After the component has successfully received data and sent a receipt, the information regarding the request and receipt will be provided by the node. For example, this may look like (assuming a receipt was returned to the client):

[ { "ReceivedFileName": "test.edi", "EDIType": "application/edi-x12", "EDIProperties": "", "EDISchemaLocation": null, "EDISchemaNamespace": null, "EDISchemaVersion": null, "EDIPartId": "cid:_cb2f20e8-...". "AS4FromId": "Test From Organization", "AS4FromIdType": "", "AS4FromRole": "Sender", "AS4ToId": "Test To Organization", "AS4ToIdType": "", "AS4ToRole": "Receiver", "AgreementRef": "", "ConversationId": "_5895631c-...", "ReceiptRefToMessageId": "", "Service": "http://docs-...", "ServiceAction": "http://docs-...", "ServiceType": "", "MessageId": "_5895631c-...", "MessageProperties": "" } ]