isaitb/asx-messaging-v4 repository overview

⁠Introduction

A web application implementing the GITB messaging service API⁠ to allow GITB TDL test cases⁠ to send and receive messages over a Domibus AS4 gateway⁠ (eDelivery⁠). This service is meant to be used as the service handler⁠ for GITB TDL messaging transactions⁠, to realise send⁠ and receive⁠ steps.

This image is maintained by the European Commission's DIGIT and specifically the Interoperability Test Bed, a conformance testing service for projects involved in the delivery of cross-border public services. Find out more here⁠.

⁠Capabilities

The purpose of this service is to integrate with a specific Domibus instance in order to:

• Send a message using a prepared header and payload as inputs.
• Check for an acknowledgement received for a given message (previously sent) based on a message identifier.
• Receive a message based on an expected message identifier.

In carrying out these actions, this component expects to interact with the linked Domibus instance via its Default WebService Plugin⁠ (minimum version 4.0). In the case of messages waiting to be received (i.e. a receive⁠ step in a test case), the service uses polling based on a configurable polling rate.

⁠Configuration and deployment

To deploy this service the simplest approach is to use it via Docker Compose⁠. The following is a sample docker-compose.yml file to use for its deployment that represents the minimum configuration needed:

version: '2'

services:
   asx-messaging:
      image: isaitb/asx-messaging-v4:latest
      restart: unless-stopped
      environment:
       - messaging.as4GatewayUrl=https://path.to/domibus/services/msh
       - messaging.as4Backend=https://path.to/domibus/services/backend?wsdl
      ports:
       - "8888:8888"

Regarding the configuration of the service, the key points to take into account are the following:

• The internal port on which the service is listening on is 8888. This needs to be mapped to your host or accessed directly if within the same Docker network.
• The web application context used by the service is /ms.

The following table lists the supported configuration properties that can be used as environment variables as well as any assumed defaults:

In addition, is it interesting to note that the service is implemented using Spring Boot⁠ and as such any standard Spring Boot configuration properties⁠ can also be similarly set via environment variables. Properties you may consider to override are relevant to logging, the server.servlet.context-path (set by default to /ms) and the server.port (set by default to 8888).

Once your docker-compose.yml file has been prepared to match your environment you may start the service using docker compose up -d. Assuming a deployment using the default configuration on your localhost's port 8080, the service will be available at http://localhost:8080/ms/api/as4messaging. This means that when used in the Test Bed as a messaging handler (which requires the WSDL address), this would be provided as http://localhost:8080/ms/api/as4messaging?wsdl.

⁠Use within GITB TDL test cases

The following sections explain how to use the service from GITB TDL test cases.

⁠Send a message

To send a message use a send⁠ step passing the following inputs:

• as4.send.header, the AS4 message XML header (of type "string", "object" or "binary").
• as4.send.payload, the list of payloads to send (of type "list[binary]").

<steps>
   <btxn from="sender" to="received" txnId="t1" handler="http://localhost:8080/ms/api/as4messaging?wsdl"/>
   <assign to="header">$headerToUse</assign>
   <assign to="payloads" append="true">$payloadToInclude</assign>
   <send id="data" desc="Send message" from="sender" to="receiver" txnId="t1">
      <input name="as4.send.header">$header</input>
      <input name="as4.send.payload">$payloads</input>
   </send>
   <!-- Assigned message ID returned as "as4.send.messageId" -->
   <log>$data{as4.send.messageId}</log>
   <!--
      Sent content returned as a map named "sentContent" including entries:
      - "as4.send.header": The header of the message.
      - "as4.send.payload": The list of payloads.
   -->
   <etxn txnId="t1"/>
</steps>

⁠Check for a sent message's acknowledgement

To check for a sent message's acknowledgement use a receive⁠ step passing the following inputs:

• as4.receive.type, set to ack_check.
• as4.receive.messageId, the ID of the message to check for (of type "string").

<steps>
   <btxn from="sender" to="received" txnId="t1" handler="http://localhost:8080/ms/api/as4messaging?wsdl"/>
   ...
   <send id="data" desc="Send message" from="sender" to="receiver" txnId="t1">
      <input name="as4.send.header">$header</input>
      <input name="as4.send.payload">$payloads</input>
   </send>
   ...
   <receive id="ackData" desc="Receive acknowledgement" from="receiver" to="sender" txnId="t1">
      <input name="as4.receive.messageId">$data{as4.send.messageId}</input>
      <input name="as4.receive.type">'ack_check'</input>
   </receive>   
   <!-- 
      The receive step returns a map of two entries:
      - "as4.send.messageId": The message ID that was acknowledged.
      - "as4.message.send.reason": The acknowledgement text.
      Whether the step is a success or failure depends on the state returned and the service's "messaging.ackFailureStates" environment variable.
   -->
   <log>$ackData{as4.send.messageId}</log>
   <log>$ackData{as4.message.send.reason}</log>
   <etxn txnId="t1"/>
</steps>

⁠Receive a message

To receive a message use a receive⁠ step passing the following input:

• as4.receive.messageId, the ID of the message to lookup (of type "string").

<steps>
   <btxn from="sender" to="receiver" txnId="t1" handler="http://localhost:8080/ms/api/as4messaging?wsdl"/>
   <receive id="data" desc="Receive message" from="sender" to="receiver" txnId="t1">
      <input name="as4.receive.messageId">$messageId</input>
   </receive>
   <!-- 
      The receive step returns a map of the following entries:
      - "header": The message header (of type "object").
      - "payload": A map containing the payload data. Each separate payload received is added in a separate map named "payload.N" (where N is a 1-based index). Each of these includes the following entries:
         - "payload.id": The ID of the payload (of type string).
         - "payload.contentType": The payload's content/mime type (of type string).
         - "payload.content": The payload's data (of type binary).
   -->
   <log>$data{payload}{payload.1}{payload.content}</log>
   <etxn txnId="t1"/> 
</steps>

⁠Licence

This tool is shared using the European Union Public Licence (EUPL) version 1.2⁠.

⁠Legal notice

The authors of this tool waive any and all liability linked to its usage. In terms of data, the tool does not harvest, collect or process in any way data nor does it maintain any state linked to its processed eDelivery messages.

⁠Contact

To get in touch for feedback or questions please send an email to [email protected]⁠.