Web Service Usage Guide

Web service in ebMS plugin

The following are tasks can be archived through ebMS web services.

Send ebMS message to Hermes 2
Receive ebMS message from Hermes 2
Query EbMS message which are ready to download
Query ebMS message status
Query ebMS message history with different partnership criteria

Web services in AS2 plugin

The following are tasks can be archived through AS2 web services.

Send AS2 message to Hermes 2
Receive AS2 message from Hermes 2
Query AS2 message which are ready to download
Query AS2 message status
Query AS2 message history with different partnership criteria

We have created sample programs to demonstrate how to communicate with H2O by web services. For example, "ebms-send" which upload the payload to H2O and H2O will attach the payload and send as ebMS message. "ebms-history" which query message history and take action according to the message box of this message.

Maintain partnership

Before explain the web service of AS2/EbMS, it would be better if we talk about how to maintain an partnershio here. However, be reminded that the partnership maintainace operation is not done by web-service.
A partnership must be registered on hermes to send an message as partnership stored information of the trading partner. Hence, hermes needs partnership information to deliver message.

However, I would not explain too much in here, please refer to the article
What is EbMS 2.0 Partnership? and What is AS2 Partnership?

Let's take a look on program parameter.

Syntax:
	as2-partnership [parntership-xml] [config-xml] [log-path]
	
		partnership-xml	: The filepath of the partnership configuration file. 
					Default is "./config/as2-partnership.xml".
		config-xml 	: The filepath of the message configuration file. 
				  	Default is "./config/as2-partnership/as2-request.xml".
		log-path	: The filepath of the logger to log query result or error. 
					Default is "./logs/as2-partnership.log".
					
					
	ebms-partnership [parntership-xml] [config-xml] [log-path]
	
		partnership-xml	: The filepath of the partnership configuration file. 
					Default is "./config/ebms-partnership.xml".
		config-xml 	: The filepath of the message configuration file. 
				  	Default is "./config/ebms-partnership/ebms-request.xml".
		log-path	: The filepath of the logger to log query result or error. 
					Default is "./logs/ebms-partnership.log".

Configuration File

Here is the sample content of config-xml. This config-xml is named "ebms-request.xml" and "as2-request.xml", and placed under "/config/ebms-partnership" and "/config/as2-partnership" respectively.

Configuration File for EbMS

Configuration File for AS2

Partnership File

The sample content of partnership-xml are show as following, But i would not explain each field in here.

Please refer to the article of EbMS Partnership and AS2 Partnership.

Sample EbMS Partnership

Sample AS2 Partnership

EbMS

We have created two sample programs "ebms-send" and "ebms-history" to demonstrate you how to communicate with H2O webservice.

"ebms-send", which is a program to upload an message to H2O through EbMS web service. "ebms-history" query message history according to criteria.

Send EbMS message to Herme2

"ebms-send" is a sample program to demonstrate you how to upload an message to Hermes.
There is a web service opened in the EbMS plugin called sender. You can pack up your payload as SOAP message and send this message to this service, the default endpoint, http://hermes-host/corvus/httpd/ebms/sender.

The Required Elements defined in SOAP Request

<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>

As the SOAP request message shown, it is clear to understand that what has to be included. Partnership information has to be included "cpaid", "service" and "action".
Another configuration file needed is partnership-xml, which named "ebms-partnership.xml" and placed under "config" folder by default.
All in all, to construct a valid soap message you have to put those information in one or 2 configuration file.

Before sending a ebms message, please making sure that partnership is registered. Please refer to section Parnership Maintenance to see more information

Let’s take a look on program parameter.

Syntax:
	ebms-send [parntership-xml] [config-xml] [log-path] [payload-path].
	
		partnership-xml	: The filepath of the partnership configuration file. 
					Default is "./config/ebms-partnership.xml".
		config-xml 	: The filepath of the message configuration file. 
				  	Default is "./config/ebms-send/ebms-request.xml".
		log-path	: The filepath of the logger to log query result or error. 
					Default is "./logs/ebms-send.log".
		payload (optional)	: The filepath of the payload attached in the message.
					Default is "./config/ebms-send/testpayload"

Configuration File

Here is the sample content of config-xml. This config-xml is named "ebms-request.xml", and placed under "/config/ebms-send".

You may wonder what the use of these fields is or, what the value of these fields is.

Here is a table to explain the use of the element.

sendEndpoint	Refer to the address of the ebms send service. Normally, it would be http://hermes-host/corvus/httpd/ebms/sender
convesationId	A value to indentify which conversation would this message belongs. This is mandatory value for hermes to create an valid message.
fromPartyId fromPartyType toPartyId toPartyType	A value to identify the party info of your organization and the trading partner. These are mandatory values for hermes to retreive the message destination.
refToMessageId	The message id that targeted to response to.
serviceType	A type identifier for the ebXML service defined in partnership.

All in all, the only thing that you have to change is “sendEndpoint”. As the hermes-host should be replaced by a actual address of the hermes.
Another configuration file needed is partnership-xml, which named "ebms-partnership.xml" and placed under "config" folder by default.
The sample content is shown as following:

You may see the partnership file that different from this, but these 3 elements are MANDATORY when constructing the SOAP message according to the WSDL. I won't explain the field here, for more information, please read the article about EBMS Partnership Configuration.

Once you configured these parameters correctly, you can now execute the program. Here is the example out of the program if it is successfully executed. You can see returned message id if programe has successfully executed.

Example Output:

EBMS History Query

"ebms-history" demonstrates the use of message history service of EbMS plug-in. The web service provided called "msg-history". There is several criteria are defined for message history query. By parsing these criteria to hermes through SOAP message, you can retrieve your target results.

The message history service endpoint is http://hermes-host/corvus/httpd/msg_history

The Required Elements defined in SOAP Request

<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>

As you can see, there are several message properties acting as searching criteria, such as the message status, message id, message box. Moreover, you can search for message(s) depends on the partnership information, like cpa id, action and service.

After the message result is listed, you can perform further action by choosing your target 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. We will talk about be it in later section.

Let’s take a look on program parameter.

Syntax:
	ebms-history [config-xml] [log-path]
	
		config-xml 	: The filepath of the message configuration file. 
				  	Default is "./config/ebms-history/ebms-request.xml".
		log-path	: The filepath of the logger to log query result or error. 
					Default is "./logs/ebms-history.log".

Configuration File

Here is the sample content of config-xml. This config-xml is named "ebms-request.xml", and placed under "/config/ebms-history". You can see there is several element are listed as your searching criteria(s), you can use wildcard character (%) in the value, or you can comment the elements which means ignore this criteria

Program Operation

As we mentioned before, the program can helps to check the message status or retrieve the payload from Hermes. These actions are done by web-service.
If the query is sucessfully executed, the result will list as following.

Retrieve Message Payload

For the payload retreiveing parts, there is a receiver service provided on the EbMS plug-in. The receiver service endpoint http://hermes-host/corvus/httpd/ebms/receiver.

The Required Elements defined in SOAP Request

<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>

According to the request message, message-id is the only criteria to retrieve the payload of targeted message. However, the payload is only available for onc time. If the payload of message has been downloaded, the program is not able to retrieve it again.

As you see in the program output. The program will ask for the output directory for storing the payload(s). And payload will stored in name ebms.MessageId.Payload.IndexofPayload.

Check Outgoing Message Status

For outgoing message status checking part, the program achieves this operation by using the “status” service which is provided in the EbMS plug-in. Be reminded that the message should be an outgoing message, otherwise this service can check the status.

The Required Elements defined in SOAP Request

<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>

messageId is the only criteria for query message status

The program listed out the message status and a simply description of the message status.

AS2

We created samples not only for EbMS, but alsoAS2. The program "as2-send" and "as2-history" are used to demonstrate how to communicate with H2O web service.

"as2-send", which is a program to upload an message to H2O through AS2 web service. "as2-history" query message history according to criteria.

Send AS2 Message

"as2-send" is a sample program to demonstrate the way to upload an message to Hermes.
There is a web service opened in the AS2 plug-in called sender. You can pack up your payload as SOAP message and send this message to this service, the default endpoint, http://Hermes-host/corvus/httpd/as2/sender.

The Required Elements defined in SOAP Request

<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

It is clear to understand that what has to be included in the SOAP message. Partnership information has to be included "as2_from" and "as2_to". And the "type" element which stating the content type of the payload. The values of these elements are stored in one or 2 configuration file.

Before sending an AS2 message, please be confirmed that partnership is registered. Please refer to section Parnership Maintenance to see more information.

Let’s take a look on program parameter.

Syntax:
	as2-send [parntership-xml] [config-xml] [log-path] [payload-path].
	
		partnership-xml	: The filepath of the partnership configuration file. 
					Default is "./config/as2-partnership.xml".
		config-xml 	: The filepath of the message configuration file. 
				  	  Default is "./config/as2-send/as2-request.xml"..
		log-path	: The filepath of the logger to log query result or error. 
					Default is "./logs/as2-send.log".
		payload (optional)	: The filepath of the payload attached in the message.
					Default is "./config/as2-send/testpayload"

Configuration File

Here is the sample content of config-xml. This config-xml is named "as2-request.xml", and placed under "/config/as2-send".

You may wonder what the use of these fields is or, what the value of these fields is.

sendEndpoint	Refer to the address of the ebms send service. Normally, it would be http://hermes-host/corvus/httpd/as2/sender
type	Specify the content type.for more information please refer to SOAP Request Message part of AS2 Sender Service Article.

You may have to change is "sendEndpoint". As the hermes-host should be replaced by a actual address of the hermes.
Another configuration file needed is partnership-xml, which named "ebms-partnership.xml" and placed under "config" folder by default.

The sample content is shown as following:

You may see the partnership file that different from this, but these 2 elements are MANDATORY when constructing the SOAP message according to the WSDL. I won’t explain the field here, for more information, please read the article of AS2 Partnership.

Once you configured these parameters correctly, you can now execute the program. Here is the example out of the program if it is successfully executed. An message id will be returned if the program has sucessfully executed.

AS2 History Query

"as2-history" is a demo program on using message history service of AS2 plug-in. The web service provided called "msg-history". There is several criteria are defined for message history query. By parsing these criteria to hermes through SOAP message, you can retrieve your target results.

The message history service endpoint is http://hermes-host/corvus/httpd/as2/msg_history

The Required Elements defined in SOAP Request

<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:as2Fromxmlns:tns="http://service.ebms.edi.cecid.hku.hk/"><AS2 From Party></tns:as2From> <tns:as2Toxmlns:tns="http://service.ebms.edi.cecid.hku.hk/"><AS2 To Party></tns:as2To> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

As the service defined, you can parse in several message properties as searching criteria, such as the message status, message id, message box. Moreover, you can search for message(s) depends on the partnership information, After the message result is listed, you can perform further action by choosing your target message. If the message is placed under INBOX, the program will query its current status. If the message is placed under OUTBOX, the program will download the payload if available. We will talk about be it in later section.

Let’s take a look on program parameter.

Syntax:
	as2-history [config-xml] [log-path]
	
		config-xml 	: The filepath of the message configuration file. 
				  	  Default is "./config/as2-history/as2-request.xml"..
		log-path	: The filepath of the logger to log query result or error. 
					Default is "./logs/as2-history.log".

Here is the sample content of config-xml. This config-xml is named "as2-request.xml", and placed under "/config/as2-history". You can see there is several element are listed as your searching criteria(s), you can use wildcard character (%) in the value, or you can comment the elements which means ignore this criteria

Program Operation
As we mentioned before, the program can helps to check the message status or retrieve the payload from Hermes. These actions are done by web-service.
If the query has been executed successfully, the result will be listed as following.

Message(s) are list in ascending timestamp of the message, the earliest message will list as index 0 and so on.

Retrieve Message Payload

For the payload retreiveing parts, there is a receiver service provided on the EbMS plug-in. The receiver service endpoint http://hermes-host/corvus/httpd/as2/receiver

The Required Elements defined in SOAP Request

<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 parse your target message-id in the SOAP message to retrieve the payload of the message. However, the payload is only available for once. If the payload of message has been downloaded, the program is not able to retrieve it again.

As you see in the program output. The program will ask for the output directory for storing the payload(s). And payload will stored in name as2.MessageId.Payload.IndexofPayload.

Check Outgoing Message Status

For outgoing message status checking part, the program achieves this operation by using the “status” service which is provided in the AS2 plug-in. Be reminded that the message should be an outgoing message, otherwise this service can check the status.

The Required Elements defined in SOAP Request

<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>

The only required element is the message-id.

Here is the program out

The program listed out the message status and a simply description of the message status.

Reference Article

Discuss this in our forum

Posted by Ronnie Kwok on 09/05 at 11:34 AM