Communicating Hermes 2 through WS

Introduction

Hermes 2 has applied SOAP messaging framework as the way for external application to communicate, rather than using JAVA-based callback registery mechanisms in Hermes 1. The main advantages using SOAP web services here are reducing coupling between external application and Hermes 2, and allowing external application to integrate Hermes 2 seamlessly using any programming language which support SOAP and SOAP Messages with Attachments (instead JAVA application only).

This article is purposed to assist developers whose want to communicate Hermes 2 through SOAP web service by writing a web service call client.

It assumes you have successfully installed Hermes 2 and know what is partnership. Please refer to Hermes 2 Installation Guide and The first step you hermes if you don't.

image


Overview

Let's take a briefing on the communication port architecture between Hermes 2 and external application. First of all, we all know that the core of Hermes 2 is attached to any J2EE compliant web server as kind of Servlet. The core itself in fact does not provide any SOAP web service nor HTTP listener. Even it does not have any functionality related to the messaging. All features in Hermes 2 are derived from the core by SPA (simple plugin architecture).

One of the core SPA is called Main Plugin (shown below at the core SPA layer) which provides HTTP context listener for accepting HTTP request at the specified context path (extension point) for the external invocation. Then the protocol-specific SPA ebMS and AS2 plugin (shown below at the SPA layer) are making use of this listener for providing all SOAP web service i am going to elaborate in this article.

By default, ebMS 2.0 plugin and AS2 plugin have registered 5 web services each in Hermes 2 (shown below at the External SPA layer). They are:

  1. ebMS 2.0 Sender Web Service
  2. ebMS 2.0 Receiver List Web Service
  3. ebMS 2.0 Receiver Web Service
  4. ebMS 2.0 Status Web Service
  5. ebMS 2.0 Message History Web Service
  6. AS2 Sender Web Service
  7. AS2 Receiver List Web Service
  8. AS2 Receiver Web Service
  9. AS2 Status Web Service
  10. AS2 Message History Web Service



image
The High Level Architecture of SPA Layers in Hermes 2




1. ebMS 2.0 Sender Web Service

Service Endpoint: http://<HOST>:<PORT>/corvus/httpd/ebms/sender

ebMS 2.0 Sender Web Service is the web service interface for external sending party to request Hermes 2 to send an ebMS 2.0 message to the Hermes 2 or any other ebMS 2.0 compliance messaging gateway as receiving party. The service returns a message identifier to the sending party for reference purpose. This is the major channel for external application to deliver ebMS message through Hermes 2.

image


-- SOAP Request Message --

Instead of requiring sender to compose the entire ebMS message or acquire ebMS knowledge, sender just needed to request Hermes 2 to do so with key identities including CPA-ID, Service, Action. These 3 key parameter identify the sender's partnership in Hermes 2 that will be used to configure the ebMS message.


The sender web service requires elements with namespace URI http://service.ebms.edi.cecid.hku.hk/ and namespace prefix tns. The sample SOAP request for sender web service is shown below.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<tns:cpaId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <CPA-id> </tns:cpaId>
<tns:service xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <Service> </tns:service>
<tns:action xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <Action> </tns:action>
<tns:convId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <Conversation Id> </tns:convId>
<tns:fromPartyId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <From Party ID> </tns:fromPartyId>
<tns:fromPartyType xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <From Party Type> </tns:fromPartyType>
<tns:toPartyId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <To Party ID> </tns:toPartyId>
<tns:toPartyType xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <To Party Type> </tns:toPartyType>
<tns:refToMessageId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <Reference Message Id </refToMessageId>
<tns:serviceType xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <Service Type </tns:serviceType>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
.
.
.
Attached Payload


The meaning of the elements under SOAP Body in the above request message is as follows:

Element Mandatory Description
<cpaId>, <service> and <action> Yes They are the CPA Id, Service and Action elements in the ebMS messages sent by Hermes.
These three fields are used to identify the partnership used to send / receive the ebMS messages at sender / receiver party respectively.
These are mandatory values to identify a registered partnership in Hermes 2.
<convId> Yes It corresponds to the conversation id element in the ebMS messages sent by Hermes.
<fromPartyId> Yes It identifies the Party that originated the message (the sender). [ebMS v2_0 3.1.1]
It corresponds to the PartyId element in From element of the ebMS messages sent by Hermes.
<fromPartyType> Yes It identifies the domain of the fromPartyId.
It corresponds to the type attribute of PartyId in the From element of the ebMS messages sent by Hermes.
<toPartyId> Yes It identifies the Party that it is the intended recipient of the message (the receiver).
[ebMS v2_0 3.1.1]
It corresponds to the PartyId element in To element of the ebMS messages sent by Hermes.
<toPartyType> Yes It identifies the domain of the ToPartyId.
It corresponds to the type attribute of PartyId in the From element of the ebMS messages sent by Hermes.
<refToMessageId> No It corresponds to the RefToMessageId of the ebMS messages sent by Hermes.
<serviceType> No A type identifier for the ebXML service defined in partnership.

-- SOAP Response Message --

The element inside SOAP Body is using namespace URI http://service.ebms.edi.cecid.hku.hk/.

The sample SOAP response for sender web service is shown below:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<message_id xmlns:ns0="http://www.w3.org/2001/XMLSchema-instance" ns0:type="xsd:string" xmlns="http://service.ebms.edi.cecid.hku.hk/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <Newly created message id>
</message_id>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>


Same as the SOAP request message, The <message_id> element is the message identifier assigned by the Hermes of the sending party. The sending application can use it for later reference purpose and status tracking through Status Web Service.

Top




2. ebMS 2.0 Receiver List Web Service

Service Endpoint: http://<HOST>:<PORT>/corvus/httpd/ebms/receiver_list

The Receiver List Service is for the application of the receiving party to retrieve the message identifiers of the received and processed ebMS messages which have not been downloaded by the application. The message identifiers will be used to retrieve the message payloads with the Receiver Service.



-- SOAP Request Message --

The receiver list web service requires elements with namespace URI http://service.ebms.edi.cecid.hku.hk/ and namespasce prefix tns.

The sample SOAP request for receiver list web service is shown below:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<tns:cpaId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <CPA-id> </tns:cpaId>
<tns:service xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <Service> </tns:service>
<tns:action xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <Action> </tns:action>
<tns:convId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <Conversation Id> </tns:convId>
<tns:fromPartyId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <From Party ID> </tns:fromPartyId>
<tns:fromPartyType xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <From Party Type> </tns:fromPartyType>
<tns:toPartyId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <To Party ID> </tns:toPartyId>
<tns:toPartyType xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <To Party Type> </tns:toPartyType>
<tns:numOfMessages xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <Number of messages> </SOAP-ENV:Body>
</SOAP-ENV:Envelope>


The meaning of the elements under SOAp Bosy is shown as following:
Element Mandatory Description
<cpaId>, <service> and <action> Yes They are the CPA Id, Service and Action elements in the ebMS messages sent by Hermes. These three fields are used to identify the partnership used to send the ebMS messages.
These are mandatory values for query the list of available message
<convId> No Only the message identifiers of those messages with Conversation Id matching the value of will be retrieved.
<fromPartyId> No Only the message identifiers of those messages with From Party Id matching the value of will be retrieved.
<fromPartyType> No Only the message identifiers of those messages with From Party Type matching the value of will be retrieved.
<toPartyId> No Only the message identifiers of those messages with To Party Id matching the value of will be retrieved.
<toPartyType> No Only the message identifiers of those messages with To Party Type matching the value of will be retrieved.
<numOfMessages> No The maximum number of message identifiers retrieved by this request.

Since the tuple of (cpaId, service and action) is the composite key of partnership and it is part of filtering criteria, it is implied that only one partnership of received message can be retrieved by a web service request.



-- SOAP Response Message --

Same as the SOAP request message, the element inside SOAP body is using namespace URI http://service.ebms.edi.cecid.hku.hk/.

The sample SOAP response for receiver list web service is shown below:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<messageIds xmlns:ns0="http://www.w3.org/2001/XMLSchema-instance" ns0:type="MessageIDs" xmlns="http://service.ebms.edi.cecid.hku.hk/" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<messageId ns0:type="xsd:string"> <downloadable message id> </messageId>
<messageId ns0:type="xsd:string"> <downloadable message id> </messageId>
. .
</messageIds>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Each element in the response message represents the message identifier of a ebMS message received by Hermes in the receiving party.

Note that a message is considered as already downloaded by an application only when the message body has been downloaded by the Receiver Web Service. If your application never calls the Receiver Web Service to download the message body and payloads, the same set of message identifiers will always be retrieved because they are never marked as downloaded.

Top




3. ebMS 2.0 Receiver Web Service

Service Endpoint: http://<HOST>:<PORT>/corvus/httpd/ebms/receiver

The Receiver Service is for the application of the receiving party to retrieve the message payloads of the received ebMS messages. After the message payloads have been downloaded, the message will be marked as already received by the application, and the message identifier of the message will no longer be retrieved by the Receiver List Service.

image

-- SOAP Request Message --

The receiver list web service requires only one element with namespace URI http://service.ebms.edi.cecid.hku.hk/ and namespasce prefix tns.

The sample SOAP request for receiver web service is shown below:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<tns:messageId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <messageId> <The message id you want to download> </tns:messageId>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The <messageId> element is the message identifiers you can obtain in ebMS Receiver List web service.



-- SOAP Response Message --

The element inside SOAP body is using namespace URI http://service.ebms.edi.cecid.hku.hk/.

The sample SOAP response for receiver web service is shown below:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<hasMessage xmlns:ns0="http://www.w3.org/2001/XMLSchema-instance" ns0:type="xsd:string" xmlns="http://service.ebms.edi.cecid.hku.hk/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> true if has payload in message </hasMessage> </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
.
.
.
Attached Payload

If the message of the message identifier specified in web service parameters exists, the element exists and it has the value true.
if the received ebMS message has payloads, the response message will have one or more SOAP attachments. Each SOAP attachment has a content type, which is set by the sender application.

Top




4. ebMS 2.0 Status Web Service

Service Endpoint: http://<HOST>:<PORT>/corvus/httpd/ebms/status

The Status Service is for the application of the sending or receiving party to retrieve the message status of a sent or received ebMS message.

Message status is a 2-character code indicating the progress of an ebMS message. Thus the status web service provides something like tracking service for monitoring the ebMS message you request to Hermes 2.

-- SOAP Request Message --

The status query web service requires only one element with namespace URI http://service.ebms.edi.cecid.hku.hk/ and namespasce prefix tns.

The sample SOAP request for receiver web service is shown below:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<tns:messageId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <messageId> <The message id you want to download> </tns:messageId>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The <messageId> element is the message identifiers you can obtain in ebMS Sedner web service.





-- SOAP Response Message --

The element inside SOAP Body is using namespace URI http://service.ebms.edi.cecid.hku.hk/.

The sample SOAP response for receiver web service is shown below:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<messageInfo xmlns:ns0="http://www.w3.org/2001/XMLSchema-instance" ns0:type="MessageInfo" xmlns="http://service.ebms.edi.cecid.hku.hk/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<status ns0:type="xsd:string"> <status> </status>
<statusDescription ns0:type="xsd:string"> <statusDescription> </statusDescription>
<ackMessageId ns0:type="xsd:string"> <ackMessageId> </ackMessageId>
<ackStatus ns0:type="xsd:string"> <ackStatus> </ackStatus>
<ackStatusDescription ns0:type="xsd:string"> <ackStatusDescription> </ackStatusDescription>
</messageInfo>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The meanings of the elements under SOAP Body in the above response message are as follows:
Element Description
<Status> The current status of the ebMS message.
<StatusDescription> The text description of the current status.
<ackMessageId> The message identifiers of the associated acknowledgment (if any).
<ackStatus> The current status of the associated acknowledgment (if any).
<ackStatusDescription> The text description of the associated acknowledgment (if any).

Top



5. EBMS Message History Web Service

Service Endpoint: http://<HOST>:<PORT>/corvus/httpd/ebms/msg_history

The Message History Service is for the application of the sending or receiving party to query message(s)accroding to specific parameter(s).

image

-- SOAP Request Message --

The sample SOAP request for receiver web service is shown below:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<tns:messageBox xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"><Message Box></tns:messageBox>
<tns:status xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"><Message Status></tns:status>
<tns:messageId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"><Message Id></tns:messageId>
<tns:conversationId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"><Conversation Id></tns:conversationId>
<tns:cpaId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"><CPA Id></tns:cpaId>
<tns:service xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"><Defined Service with trading party></tns:service>
<tns:action xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"><Actiongt;</tns:action>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

In the above shown, the receiver list web service requires only one elements with namespace URI http://service.ebms.edi.cecid.hku.hk/ and namespasce prefix tns.



-- SOAP Response Message --

The element "messageList" inside SOAP Body is using namespace URI http://service.ebms.edi.cecid.hku.hk/.

The sample SOAP response for receiver web service is shown below:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<messageList xmlns="http://service.ebms.edi.cecid.hku.hk/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ns0="http://www.w3.org/2001/XMLSchema-instance" ns0:type="MessageList">
<messageElement ns0:type="MessageElement">
<messageId ns0:type="xsd:string"> MessageID of the Message </messageId>
<messageBox ns0:type="xsd:string">Message Box containing this message </messageBox>
</messageElement>
<messageElement ns0:type="MessageElement">
<messageId ns0:type="xsd:string"> MessageID of the Message </messageId>
<messageBox ns0:type="xsd:string"> Message Box containing this message </messageBox>
</messageElement>
<messageElement ns0:type="MessageElement"> . . . </messageElement>
<messageElement ns0:type="MessageElement"> . . . </messageElement>
</messageList>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The meanings of the elements under SOAP Body in the above response message are as follows:
Element Description
<messageList> The list of return message element(s).
<messageElement> A complex element containing messageId and messageBox value of return message.
<MessageId> The message identifiers of the return message.
<Status> The located message box of return message..

Top




6. AS2 Sender Web Service

Service Endpoint: http://<HOST>:<PORT>/corvus/httpd/as2/sender

The Sender Service is for the application of the sending party to request Hermes to send a AS2 message to the Hermes or any other compatible messaging gateway of the receiving party. The service returns the message identifier to the application for reference purpose.

image

-- SOAP Request Message --

The sender web service requires elements with namespace URI http://service.as2.edi.cecid.hku.hk/ and namespasce prefix tns.

The sample SOAP request for sender web service is shown below:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<tns:as2_from xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <as2_from> </tns:as2_from>
<tns:as2_to xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <as2_to> </tns:as2_to>
<tns:type xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <type> </tns:type>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
.
.
.
Attached Payload



The meanings of the elements under SOAP Body in the above request message are as follows:
Element Mandatory Description
<as2_from> and <as2_to> Yes They are the values of the "from" and "to" fields in the AS2 messages sent through the partnership by Hermes. These two fields are used to identify the partnership used to send the AS2 messages.
These are mandatory value to identify an message destination.
<type> Yes The three-character code indicating the content type of the sent payload. The available codes are:
  • "edi", for the content type "application/EDIFACT".
  • "x12", for the content type "application/EDI-X12".
  • "eco", for the content type "application/edi-consent".
  • "xml", for the content type "application/XML".
  • "bin", for the content type "application/ octet-stream".
For other values, Hermes will assume the content type of the payload is "application/deflate", which means that the payload is compressed by Zip.




-- SOAP Response Message --

The element inside is using namespace URI http://service.as2.edi.cecid.hku.hk/.

The sample SOAP response for sender web service is shown below:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<message_id xmlns:ns0="http://www.w3.org/2001/XMLSchema-instance" ns0:type="xsd:string" xmlns="http://service.as2.edi.cecid.hku.hk/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <Newly created message id>
</message_id>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The <message_id> element is the message identifier assigned by the Hermes of the sending party. The sending application can use it for later reference purpose and status tracking through Status Web Service.

Top



7. AS2 Receiver List Web Service

Service Endpoint: http://<HERMES_HOST>:<HERMES_PORT>/corvus/httpd/as2/receiver_list

The Receiver List Service is for the application of the receiving party to retrieve the message identifiers of the received AS2 messages which have not been downloaded by the application. The message identifiers will be used to retrieve the message payloads with the Receiver Service.

-- SOAP Request Message --

The receiver list web service requires elements with namespace URI http://service.as2.edi.cecid.hku.hk/ and namespasce prefix tns.

The sample SOAP request for receiver list web service is shown below:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<tns:as2_from xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <as2_from> </tns:as2_from>
<tns:as2_to xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <as2_to> </tns:as2_to>
<tns:numOfMessages xmlns:tns="http://service.ebms.edi.cecid.hku.hk/"> <numOfMessages> </tns:numOfMessages>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>


The meanings of the elements under SOAP Body in the above request message are as follows:
Element Mandatory Description
<as2_from> and <as2_to> Yes They are the values of the "from" and "to" fields in the AS2 messages sent through the partnership by Hermes. These two fields are used to identify the partnership used to send the AS2 messages.
These are mandatory value for query available message(s) of associated with the target partnership.
<numOfMessages> No The maximum number of message identifiers retrieved by this request.




-- SOAP Response Message --

The element inside is using namespace URI http://service.as2.edi.cecid.hku.hk/.

The sample SOAP response for receiver list web service is shown below:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<messageIds xmlns:ns0="http://www.w3.org/2001/XMLSchema-instance" ns0:type="MessageIDs" xmlns="http://service.as2.edi.cecid.hku.hk/" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<messageId ns0:type="xsd:string"> <downloadable message id> </messageId>
<messageId ns0:type="xsd:string"> <downloadable message id> </messageId>
</messageIds>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Each <message_id> element in the response message represents the message identifier of a AS2 message received by Hermes in the receiving party.

Note that a message is considered as already downloaded by an application only when the message body has been downloaded by the Receiver Web Service. If your application never calls the Receiver Web Service to download the message body and payloads, the same set of message identifiers will always be retrieved because they are never marked as downloaded.

Top



8. AS2 Reciever Web Service

Service Endpoint: http://<HOST>:<PORT>/corvus/httpd/as2/receiver.

The Receiver Service is for the application of the receiving party to retrieve the message payloads of the received AS2 messages. After the message payloads have been downloaded, the message will be marked as already received by the application, and the message identifier of the message will no longer be retrieved by the Receiver List Service.

image


-- SOAP Request Message --

The receiver web service requires only one element with namespace URI http://service.as2.edi.cecid.hku.hk/ and namespasce prefix tns.

The sample SOAP request for receiver web service is shown below:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<tns:messageId xmlns:tns="http://service.as2.edi.cecid.hku.hk/"> <messageId> <The message id you want to download> </tns:messageId>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>




-- SOAP Response Message --

The element inside SOAP body is using namespace URI http://service.as2.edi.cecid.hku.hk/.

The sample SOAP response for receiver web service is shown below:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<hasMessage xmlns:ns0="http://www.w3.org/2001/XMLSchema-instance" ns0:type="xsd:string" xmlns="http://service.as2.edi.cecid.hku.hk/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> true if has payload in message </hasMessage>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
.
.
.
Attached Payload

If the message of the message identifier exists, the element exists and it has the value true.
if the received ebMS message has payloads, the response message will have one or more SOAP attachments. Each SOAP attachment has a content type, which is set by the sender application.

Top



9. AS2 Status Web Service

Service Endpoint: http://<HOST>:<PORT>/corvus/httpd/as2/status.

The Status Service is for the application of the sending or receiving party to retrieve the message status of a sent or received AS2 message.

-- SOAP Request Message --

The status query web service requires only one elements with namespace URI http://service.as2.edi.cecid.hku.hk/ and namespasce prefix tns.

The sample SOAP request for receiver web service is shown below:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<tns:messageId xmlns:tns="http://service.as2.edi.cecid.hku.hk/"> <CPA-id> <The message id you want to download> </tns:messageId>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>




-- SOAP Response Message --

The element "messageInfo" inside SOAP body is using namespace URI http://service.as2.edi.cecid.hku.hk/.

The sample SOAP response for receiver web service is shown below:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<messageInfo xmlns:ns0="http://www.w3.org/2001/XMLSchema-instance" ns0:type="MessageInfo" xmlns="http://service.as2.edi.cecid.hku.hk/" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<status ns0:type="xsd:string"> <status> </status>
<statusDescription ns0:type="xsd:string"> <statusDescription> </statusDescription>
<mdnMessageId ns0:type="xsd:string" > <mdnMessageId> </mdnMessageId>
<mdnStatus ns0:type="xsd:string" > <mdnStatus> </mdnStatus>
<mdnStatusDescription ns0:type="xsd:string" > <mdnStatusDescription> </mdnStatusDescription>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The meanings of the elements under SOAP Body in the above response message are as follows:
Element Description
<status> The current status of the AS2 message.
<statusDescription> The text description of the current status.
<mdnMessageId> The message identifiers of the associated receipt (if any).
<mdnStatus> The current status of the associated receipt.
<mdnStatusDescription> The text description of the associated receipt.

Top



10. AS2 Message History Web Service

Service Endpoint: http://<HOST>:<PORT>/corvus/httpd/as2/msg_history

The Message History Service is for the application of the sending or receiving party to query message(s)accroding to specific parameter(s).

image

-- SOAP Request Message --

The message histoyr queryweb service requires only one elements with namespace URI http://service.as2.edi.cecid.hku.hk/ and namespasce prefix tns.

The sample SOAP request for receiver web service is shown below:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<tns:messageBox xmlns:tns="http://service.as2.edi.cecid.hku.hk/"><Message Box></tns:messageBox>
<tns:status xmlns:tns="http://service.as2.edi.cecid.hku.hk/"><Message Status></tns:status>
<tns:messageId xmlns:tns="http://service.as2.edi.cecid.hku.hk/"><Message Id></tns:messageId>
<tns:as2Fromxmlns:tns="http://service.as2.edi.cecid.hku.hk/"><AS2 From Party></tns:as2From>
<tns:as2Toxmlns:tns="http://service.as2.edi.cecid.hku.hk/"><AS2 To Party></tns:as2To>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>




-- SOAP Response Message --

The element "messageList" under SOAP elements is using the namespace URI http://service.as2.edi.cecid.hku.hk/.

The sample SOAP response for receiver web service is shown below:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<messageList xmlns="http://service.as2.edi.cecid.hku.hk/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ns0="http://www.w3.org/2001/XMLSchema-instance" ns0:type="MessageList">
<messageElement ns0:type="MessageElement">
<messageId ns0:type="xsd:string"> MessageID of the Message </messageId>
<messageBox ns0:type="xsd:string">Message Box containing this message </messageBox>
</messageElement>
<messageElement ns0:type="MessageElement">
<messageId ns0:type="xsd:string"> MessageID of the Message </messageId>
<messageBox ns0:type="xsd:string"> Message Box containing this message </messageBox>
</messageElement>
<messageElement ns0:type="MessageElement"> . . . </messageElement>
<messageElement ns0:type="MessageElement"> . . . </messageElement>
</messageList>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The meanings of the elements under SOAP Body in the above request message are as follows:
Element Description
<messageList> The list of return message element(s).
<messageElement> A complex element containing messageId and messageBox value of return message.
<MessageId> The message identifiers of the return message.
<Status> The located message box of return message..

Top



Reference Article




Reference Documentation

  • Hermes 2 Application Development Guide



What's next to read



Posted by Twinsen Tsang on 06/20 at 11:46 AM