The First Step You Hermes 2

1. Introduction

One of the most common difficulty in using Hermes 2 for new developers / users are required to manage (create) the partnership and program the web service requester before they are able to deliver ebMS or AS2 through Hermes 2 to their partner. This article is purposed to assist user to maintain their set of partnership registered in the Hermes 2. It assumes you have successfully installed Hermes 2 and able to browse the Hermes 2 administration console. Please refer to Hermes 2 Installation Guide if you don't.

2. What is partnership ?

A partnership in Hermes 2 is defined as a channel to your business partner. A partnership is a simplex (one-way) communication channel to your business partner. In a typical two-ways business document exchange, the Hermes 2 in each party should have TWO partnerships. One is for sending, another is for receiving. After the partnerships have been defined, the application can reference the partnerships to send or receive business messages.

image

3. Existing partnership type

Currently, Hermes 2 has two types of partnership you can manage with. They are ebMS partnership and AS2 partnership which representing the communication agreement to your partner using ebMS protocol and AS2 protocol respectively.

4. Getting Started

  1. EbMS
    1. What is ebMS 2.0 Partnership ?
    2. Procedures to create your first ebMS 2.0 Partnership
    3. Procedures to update an ebMS 2.0 Partnership
    4. Procedures to delete an ebMS 2.0 Partnership
  2. AS2
    1. What is AS2 Partnership ?
    2. Procedures to create your first AS2 Partnership
    3. Procedures to update an AS2 Partnership
    4. Procedures to delete an AS2 Partnership


4.1.1 What is ebMS 2.0 Partnership ?

If the communication protocol with your business partner¡¦s messaging gateway is ebMS, CPA (Collaboration Protocol Agreement) ID, Service and Action are used to uniquely identify a partnership. Actually, these parameters are protocol parameters in ebMS protocol and their values appear in an ebMS message header you want to send. The meanings of these parameters for Send Partnership (the partnership for sending) and Receive Partnership (the partnership for receiving) are different:

  • The values of CPA ID, Service and Action in Send Partnership are taken as the values in the ebMS header of the outgoing messages sent by the Send Partnership.
  • The values of CPA ID, Serviceand Action in Receive Partnership are taken as filtering criteria. If Hermes 2 receives an ebMS message whose CPA ID, Service and Action values do not have a matching partnership, a negative acknowledgement will be sent back to the sender and no application can retrieve the message on the receiver side.
For Hermes 2, the Service parameter for Send Partnership and Receive Partnership has to be HTTP URL (Universal Resource Locator) even though ebMS specification allows a Service value that is not HTTP URL. The Service has different meanings in Send Partnership and Receive Partnership:
  • For Send Partnership, the Service acts as the endpoint URL of the sending Hermes to which the acknowledgement is sent by the receiver. That is, this should be the endpoint URL of the sending Hermes for receiving ebMS messages.
  • For Receive Partnership, since the Service is a filtering criterion for the incoming messages, it should be the endpoint URL of the sending Hermes.

Let us look at a typical example below, in which two Hermes communicate in ebMS protocol and two partnerships are setup in each of them:

image

In the above scenario, the Hermes in company A has an IP 1.1.1.1. So, its endpoint URL for receiving incoming ebMS messages is http://1.1.1.1:8080/corvus/httpd/ebms/inbound, where we suppose the application server is running on port 8080. Similarly, the endpoint URL for receiving ebMS messages of the Hermes in company B is http://1.1.1.2:8080/corvus/httpd/ebms/inbound.

Since a partnership is a simplex channel, each Hermes should have a pair of partnership, one for sending and another for receiving. The partnerships are identified by CPA ID, Service and Action. Their values should be negotiated between the two parties.

The Service of the Send Partnership in the Hermes of company A should be the endpoint URL for receiving incoming ebMS messages or acknowledgements. Therefore, the Service should be http://1.1.1.1:8080/corvus/httpd/ebms/inbound. The messages sent by this Send Partnership will contain this Service value in the header, so the receiver Hermes will know where the acknowledgement should be sent to.

The Receive Partnership's CPA ID, Service and Action form a filtering criterion for the incoming messages. Therefore, these values in the Receive Partnership in the receiving Hermes should be always the same as the Send Partnership in the sending Hermes.



4.1.2 Procedures to create your first ebMS 2.0 Partnership

  1. Open a Web browser.
  2. Browse to Hermes2 Administration Console. It should be http://<H2 INSTALLED HOST>:<PORT>/corvus/admin/home.
  3. Enter the administrator user name and password for Hermes2 accordingly.
  4. Click the Ebms Plugin on the module tab located at left hand side.
  5. Click the Partnership tab on the central horizontal tabbed bar and the partnership creation page should be shown under it.
  6. To create the simplest ebMS 2.0 partnership, you are just required to fill in seven fields in the form shown below:
    1. Partnership ID
    2. CPA ID
    3. Service
    4. Action
    5. Transport URL
    6. Retries
    7. Retry Interval

  7. Fill up the Partnership ID, CPA ID, Service and Action as following shown:
    The Partnership ID is the unique identifier of the partnership in the sender Hermes while the three remaining (CPA ID, Service and Action) form a composite identifier between sender and receiver system.


    Partnership ID MyFirstPartnership
    CPA ID MyFirstCPAID
    Service http://localhost:8080/corvus/httpd/ebms/inbound
    Action MyFirstAction

  8. Fill up the Transport Endpoint (The receiver's URL) as following shown:

    The Transport Endpoint URL should be formatted as http://<RECEIVER HOST>:<PORT>/corvus/httpd/ebms/inbound
    where corvus/httpd/ebms/inbound is the context path for accepting and receiving incoming EbXML message if the receiver system is also using Hermes 2.
    Since the receiver host below is the sender host (i.e. The ebMS message delivers loop back to sender). ONE partnership is required defined for sending and receive.


    Transport Endpoint http://localhost:8080/corvus/httpd/ebms/inbound

  9. Fill up the number of retries allowed when fail to deliver message and the retry interval as following shown:

    Retries 3
    Retry Interval (ms) 30000

  10. Now you are completed to fill up all required fields and you should have the same input as the figure shown here.
  11. Click the add button in the bottom of page.
  12. A dialog is prompted and ask whether confirm adding partnership. Click Ok.
  13. A Message Partnership Added Successfully will be shown on the status bar (the bottom of the page).
  14. Congratulation ! You are successfully created your first ebMS 2.0 partnership.


4.1.3 Procedures to update an ebMS 2.0 Partnership

  1. Do the steps 1-5 in 4.1.2 or whole step in 4.1.2 if you have not registered any partnership in Hermes 2
  2. You should able to see there is drop-down list under the header of Registered Partnership.
  3. Click the change button.
  4. Now you should able to see there is a module called Selected Partnership and contains the information of selected partnership in previous step like here.
  5. Change the parameters / fields you want and click Update when you have done.
  6. A dialog is prompted for confirming the update of partnership. Click Ok.
  7. A Message Partnership Updated Successfully will be shown on the status bar (the bottom of the page).


4.1.4 Procedures to delete ebMS 2.0 Partnership

  1. Do the steps 1-4 in 4.1.3
  2. Click the Delete button
  3. A Message Partnership deleted successfully will be shown on the status bar (the bottom of the page)



4.2.1 What is AS2 2.0 Partnership ?

If the communication protocol with your business partner's messaging gateway is AS2, the AS2 From and AS2 To field in a partnership are used to uniquely identify a partnership. Actually, these parameters are protocol parameters in AS2 protocol and their values appear in an AS2 message header. The meanings of these parameters for Send Partnership (the partnership for sending) and Receive Partnership (the partnership for receiving) are different:

  • The values of AS2 From, AS2 To in Send Partnership are taken as the values in the AS2 header of the outgoing messages sent by the Send Partnership.
  • The values of AS2 From, AS2 To in Receive Partnership are taken as filtering criteria. If Hermes 2 receives an AS2 message whose AS2 From and AS2 To values do not have a matching partnership, the incoming message is rejected/ignored and no application can retrieve the message on the receiver side.

    NOTE: The value of AS2 From and AS2 To in the incoming AS2 message are interchanged before finding the matching partnership (i.e The filtering critera (AS2 From, AS2 To) = (Incoming AS2 To, Incoming AS2 From) in the AS2 message.
Although the value of AS2 From, AS2 To have no any constraint, but it is highly recommended they should be company specific, such as Data Universal Numbering System (DUNS) numbers, or they may be simply identification strings agreed upon between the trading partners.

Let us look at a typical example below, in which two Hermes communicate in AS2 protocol and two partnerships are setup in each of them:

image



4.2.2 Procedures to create your first AS2 Partnership

  1. Open a Web browser.
  2. Browse to Hermes2 Administration Console. It should be http://<H2 INSTALLED HOST>:<PORT>/corvus/admin/home.
  3. Enter the administrator user name and password for Hermes2 accordingly.
  4. Click the Ebms Plugin on the module tab located at left hand side.
  5. Click the Partnership tab on the central horizontal tabbed bar and the partnership creation page should be shown under it.
  6. To create the simplest AS2 partnership, you are just required to fill in seven fields in the form shown below:
    1. Partnership ID
    2. AS2 From
    3. AS2 To
    4. Subject
    5. Transport URL
    6. Retries
    7. Retry Interval

  7. Fill up the Partnership ID, AS2 From, AS2 To as following shown:
    The Partnership ID is the unique identifier of the partnership in the sender Hermes while the two remaining (AS2_From, AS2_To) form a composite identifier between sender and receiver system.


    Partnership ID MyFirstPartnership
    AS2 From FromMyMachine
    AS2 To ToMyMachine

  8. Fill up the Subject ant Transport Endpoint (The receiver's URL) as following shown:

    The Transport Endpoint URL should be formatted as http://<RECEIVER HOST>:<PORT>/corvus/httpd/as2/inbound
    where corvus/httpd/ebms/inbound is the context path for accepting and receiving incoming AS2 message if the receiver system is also using Hermes 2.
    Since the receiver host below is the sender host (i.e. The AS2 message delivers loop back to sender). ONE partnership is required defined for sending and receive.


    Subject MyFirstSubject
    Transport Endpoint http://localhost:8080/corvus/httpd/as2/inbound

  9. Fill up the number of retries allowed when fail to deliver message and the retry interval as following shown:

    Retries 3
    Retry Interval (ms) 30000

  10. Now you are completed to fill up all required fields and you should have the same input as the figure shown here.
  11. Click the add button in the bottom of page.
  12. A dialog is prompted and ask whether confirm adding partnership. Click Ok.
  13. A Message Partnership Added Successfully will be shown on the status bar (the bottom of the page).
  14. Congratulation ! You are successfully created your first AS2 partnership.


4.2.3 Procedures to update an AS2 Partnership

  1. Do the steps 1-5 in 4.2.2 or whole step in 4.2.2 if you have not registered any partnership in Hermes 2
  2. You should able to see there is drop-down list under the header of Registered Partnership.
  3. Click the change button.
  4. Now you should able to see there is a module called Selected Partnership and contains the information of selected partnership in previous step like here.
  5. Change the parameters / fields you want and click Update when you have done.
  6. A dialog is prompted for confirming the update of partnership. Click Ok.
  7. A Message Partnership Updated Successfully will be shown on the status bar (the bottom of the page).


4.2.4 Procedures to delete AS2 Partnership

  1. Do the steps 1-4 in 4.2.3
  2. Click the Delete button
  3. A Message Partnership deleted successfully will be shown on the status bar (the bottom of the page)


5. Conclusion

The main benefit of partnerships is that it provides abstraction on technical parameters. The abstraction is beneficial because:

  1. Since all the technical parameters, such as the communication protocols between the messaging gateways, endpoint URL and delivery options are contained in the partnership, the application does not need changes if your business partner changes the parameters.
  2. The application only needs to submit the payloads. It does not contain any code that is specific to communication protocol between the messaging gateways.
  3. The application does not need to handle the raw and cryptic ebMS or AS2 messages. Therefore, the developers should only focus on business logic and integration with the backend systems.



6. References



7. What's next to read



Posted by Twinsen Tsang on 06/06 at 02:15 PM