Using Sample Clients¶
These sample Java clients demonstrate Hermes messaging flow. They provide a set of sample code for writing web service client applications connecting to Hermes.
Maintaining partnerships¶
A partnership must be registered on Hermes to send messages since partnerships contain information about your trading partner. A separate partnership is required to receive messages.
If you want to know more about partnership, please refer to the section What is an ebMS 2.0 partnership? and What is an AS2 partnership?
Let’s take a look at the program parameters.
as2-partnership [partnership-xml] [config-xml] [log-path]
| partnership-xml | The filepath of the partnership configuration file. Default is |
| config-xml | The filepath of the message configuration file. Default is |
| log-path | The filepath of the logger to log query result or error. Default is |
ebms-partnership [partnership-xml] [config-xml] [log-path]
| partnership-xml | The filepath of the partnership configuration file. Default is |
| config-xml | The filepath of the message configuration file. Default is |
| log-path | The filepath of the logger to log query result or error. Default is |
config-xml¶
Here is sample content of the config-xml files. These files are named ebms-request.xml and as2-request.xml, and placed under <HERMES2_HOME>/config/ebms-partnership and <HERMES2_HOME>/config/as2-partnership respectively.
Configuration file for ebMS:
Configuration file for AS2:
partnership-xml¶
Sample content of the partnership-xml files are shown below. For more details, please refer to the articles Setting Up ebMS 2.0 Partnerships and Setting Up AS2 Partnerships.
Sample ebMS partnership:
Sample AS2 partnership:
ebMS¶
We have created two sample programs, ebms-send and ebms-history, to demonstrate how to communicate with Hermes web services.
Sending an ebMS message¶
ebms-send is a sample program to demonstrate how to upload an ebMS message to Hermes using the sender web service in the ebMS plugin. You can pack your payload as a SOAP message and send it to this service at the endpoint http://<HOST>:<PORT>/corvus/httpd/ebms/sender.
The elements in a SOAP request are 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>
For more information on the elements in the SOAP body of a send request, please refer to the section ebMS Send Message Web Service.
Before sending an ebMS message, please make sure a partnership is registered. Please refer to the section Maintaining Partnerships for more information.
Let’s take a look at the program parameters.
ebms-send [partnership-xml] [config-xml] [log-path] [payload-path]
| partnership-xml | The filepath of the partnership configuration file. Default is |
| config-xml | The filepath of the message configuration file. Default is |
| log-path | The filepath of the logger to log query result or error. Default is |
| payload (optional) | The filepath of the payload attached in the message. Default is |
config-xml¶
Here is sample content of the config-xml file. This file is named ebms-request.xml, and placed under <HERMES2_HOME>/config/ebms-send.
The following table explains the use of each element:
<sendEndpoint> |
Refers to the address of the ebMS send service. It should be |
<conversationId> |
Identifies which conversation this message belongs to. This is required for Hermes to create a valid message. |
|
Identifies the sender and receiver. These are required for Hermes to retrieve the message destination. |
<refToMessageId> |
The message id that is targeted to respond to. |
<serviceType> |
A type identifier for the ebXML service defined in the partnership. |
You only need to change <sendEndpoint> to contain the correct address.
partnership-xml¶
Another configuration file needed is partnership-xml, which is named ebms-partnership.xml and placed under <HERMES2_HOME>/config by default.
Sample content is shown below:
The mandatory elements are necessary to construct a SOAP message according to the WSDL. For more information, please read the article Setting Up ebMS 2.0 Partnerships.
Once you have configured these parameters correctly, the program can be executed. A message id will be displayed if the program has successfully executed.
Here is sample output from the program:
ebMS history query¶
ebms-history demonstrates the use of the message history web service (msg-history) in the ebMS plugin. There are several criteria defined for message history queries. By passing these criteria to Hermes through SOAP messages, the target results can be retrieved.
The message history service endpoint is http://<HOST>:<PORT>/corvus/httpd/msg_history.
The required elements in a SOAP request are as follows:
<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/">[Action]</tns:action>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Let’s take a look at the program parameters.
ebms-history [config-xml] [log-path]
| config-xml | The filepath of the message configuration file. Default is |
| log-path | The filepath of the logger to log query result or error. Default is |
config-xml¶
Here is sample content of the config-xml. This config-xml is named ebms-request.xml, and placed under <HERMES2_HOME>/config/ebms-history. There are several elements listed as search criteria. You can use the wildcard % in the values, and you can comment out unwanted elements.
Program operation¶
If the query is successfully executed, the result will look like:
After the messages are displayed by the program, you can perform further action on a selected message. If the selected message is placed under OUTBOX, the program will query its current status. If the message is placed under INBOX, the program will download the payload(s) if available.
Retrieving message payloads¶
There is a receiver web service provided by the ebMS plugin to retrieve messages. The receiver service endpoint is http://<HOST>:<PORT>/corvus/httpd/ebms/receiver.
The required elements in a SOAP request are as follows:
<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></tns:messageId>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
The message id is the only criteria needed to retrieve the payload of the target message. However, the payload is only available once. If the payload of a message has already been downloaded, the program cannot retrieve it again.
The program will ask for a folder path to store the payload with the filename ebms.<MessageId>.Payload.<IndexofPayload>.
Check outgoing message status¶
To check the status of outgoing messages, the program uses the status web service provided in the ebMS plugin. This service cannot check the status of incoming messages.
The required elements in a SOAP request are as follows:
<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></tns:messageId>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
The program lists the message status along with a simple description:
AS2¶
We created similar sample programs for AS2 as well. The programs as2-send and as2-history are used to demonstrate how to communicate with Hermes web services through AS2 SOAP messages.
Sending an AS2 message¶
as2-send is a sample program to demonstrate how to upload a message to Hermes using the Sender Web Service in the AS2 plugin. You can pack your payload as a SOAP message and send it to this service with the endpoint http://<HOST>:<PORT>/corvus/httpd/as2/sender.
The required elements in a SOAP request are 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
<as2_from> and <as2_to> contain the partnership information and <type> contains the content type of the payload.
Before sending an AS2 message, please check a partnership is registered. Please refer to the section Maintaining Partnerships for more information.
Let’s take a look at the program parameters.
as2-send [partnership-xml] [config-xml] [log-path] [payload-path]
| partnership-xml | The filepath of the partnership configuration file. Default is |
| config-xml | The filepath of the message configuration file. Default is |
| log-path | The filepath of the logger to log query result or error. Default is |
| payload (optional) | The filepath of the payload attached in the message. Default is |
config-xml¶
Below is sample content of the config-xml file. This file is named as2-request.xml, and placed under <HERMES2_HOME>/config/as2-send.
The elements are explained in the table below:
<sendEndpoint> |
Refer to the address of the AS2 sender web service. It should be |
<type> |
Specify the content type. For more information, please refer to AS2 Sender Web Service. Only |
partnership-xml¶
Another configuration file is the partnership-xml, which is named as2-partnership.xml and placed under <HERMES2_HOME>/config folder by default.
Sample content is shown below:
<as2From> and <as2To> are required to construct a SOAP message according to the WSDL. For more information, please refer to Setting Up AS2 Partnerships.
Once you have configured these parameters, you can execute the program. A message id will be returned if the program has been successfully executed. Below is a sample output from the program.
AS2 history query¶
as2-history is a demo program that utilizes the message history web service in the AS2 plugin. The web service is called msg-history. There are several criteria defined for message history queries. By passing these criteria to Hermes 2 through SOAP messages, you can retrieve your target messages.
The message history web service endpoint is http://<HOST>:<PORT>/corvus/httpd/as2/msg_history.
The required elements in a SOAP request are shown as 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:as2From xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[AS2_From_Party]</tns:as2From>
<tns:as2To xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[AS2_To_Party]</tns:as2To>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Using this service, you can search for messages by message properties as well as partnership information.
Let’s take a look at the program parameters.
as2-history [config-xml] [log-path]
| config-xml | The filepath of the message configuration file. Default is |
| log-path | The filepath of the logger to log query result or error. Default is |
config-xml¶
Below is sample content of the config-xml file. This file is named as2-request.xml, and placed under <HERMES2_HOME>/config/as2-history. There are several elements available to use as searching criteria. You can use the wildcard character % in the values and comment the unwanted elements.
Program operation¶
If the query has been executed successfully, the result will look like:
Messages are listed in ascending order of the message timestamp (i.e. the earliest message will be listed with index 0). After the results are listed, you can select a message. If the message is placed under OUTBOX, the program will query its current status. If the message is placed under INBOX, the program will download the payload if available.
Retrieve message payload¶
There is a receiver service provided by the AS2 plugin for retrieving messages. The receiver service endpoint is http://<HOST>:<PORT>/corvus/httpd/as2/receiver.
The required elements in a SOAP request are as follows:
<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/"> [Message_Id]</tns:messageId>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
You can specify the id of your target message in the SOAP message to retrieve its payload. However, the payload is only available once. If the payload has already been downloaded, the program cannot retrieve it again.
As shown above, the program will ask for a folder to store the payload(s) with filename as2.<MessageId>.Payload.<IndexofPayload>.
Check outgoing message status¶
To check the status of outgoing messages, the program uses the status web service provided in the AS2 plugin. This service cannot check the status of incoming messages.
The required elements in a SOAP request are the following:
<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/"> [Message_ID]</tns:messageId>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Here is sample output from the program:
The program will display the message status along with a simple description.