Setting up of the Hermes2 Messaging Gateway

in

Introduction



Hermes 2 (or Corvus, the codename we used to call in the office) is a messaging gateway that enables the handling of electronic messages in the format of AS2 or ebMS. For details, you can refer to our product web page.

I have noticed different questions in the mailing list, and as one of the developer behind the product, I hope my contribution can help those people who is interested in using it.

First off, let's start our installation.

The procedures are basically the same as indicated in the installation guide but I will include a small section in answering some commonly asked question. Also, I want to bring up some interesting finding as I am going to deploy Hermes in a little bit different environment.

Prerequisite


Apart from the binary of Hermes 2, you will need to prepare some other supporting applications, note that I have replaced Postgres with Mysql cause my web host only provides the later one. :D

NOTE : I don't have time to test out everything on this platform so if you want full compliance, stick with Postgres. ;)



Configuration - Mysql


I will highlight the steps nvolved in using Mysql in place of Postgres, but for the rest of the installation, please check out the details from the installation guide.


  1. Create two databases, named as "as2" and "ebms" respectively
  2. Create an user "corvus", grant the right to "CREATE", "DELETE", "DROP", "SELECT", "INSERT", "UPDATE". Or you can simply grant ALL if you are as lazy as me.
  3. Modify the table schemas, replace "VARCHAR" with "VARCHAR(255)" and "BYTEA" with "BLOB". Or you can download my copy from here.
  4. Create the tables accordingly.


Configuration - Hermes


The configuration files in the binary is having Postgres configured as the database of choice. You will need to change the setting in using Mysql instead.



  1. Get yourself a nice editor, search for the string

    "org.postgresql.Driver"


    and replace it with

    "com.mysql.jdbc.Driver"



    Also, locate this as well,

    "jdbc:postgresql://localhost:5432/ebms"


    and replace it with,

    "jdbc:mysql://127.0.0.1:3306/ebms"



    Repeat the procedure for AS2.

  2. Put the jdbc driver of Mysql into the "lib" folder of the Corvus webapps

You can now startup the tomcat and check the various log files (catalina.out, corvus.log, ebms.log and as2.log) that no errors are thrown.

Configuration - Loopback test


Congratulation! Now you are just one step away from completion.

It doesn't mean all is set even if no error is thrown during startup, let's try out our installation with the loopback test. BUT since the program is developed with Postgres in mind so some changes has to be made.


  1. Copy the JDBC driver of Mysql into the lib folder and modify the execution batch files to include it in the classpath.
  2. Modify the file "partnership.module.corel.xml" in the "conf" folder. Do the same thing as in Step 1 in Hermes 2 configuration.

Ta-da, now you are all set and done. Run the loopback test as usual and you should get the following results,



- Module 'Corvus Partnership' initialized successfully.
Start sending AS2 loopback test case.
Sent AS2 loopback test case with returned message ID 20061117-170806-45901@210.245.164.9.
Start checking the received list.
Download the message from the list with ID 20061117-170806-45901@210.245.164.9.
Downloaded successfully.
End checking the received list.
============================
AS2 loop back test finished.
============================



Note



There's something funny upon executing the loopback test ...

I have encountered several DAO issues and turns out it is the case sensitivity in the SQL query. The DB tables are all created with a big cap for the first letter and somehow, in the SQL query, some of the statement is using lower cap and the mismatch leads to the DAO issue. I have changed the table name accordingly in all the DAO XML files and everything is working fine.

What if ...


You are lucky if everything can go in one pass. I will put up pointer to questions which I have seen many times in the google group.


  1. When I boot up Hermes 2, I saw this message in the corvus.log,

    Unsupported keysize or algorithm parameters



    This error will raise if you forgot to deploy the JCE patch. Make sure you are copying to the right location. Also, I found that I have to set the "JAVA_HOME" in my user profile in order to have the patch loaded properly.

  2. Why is the JDK version so specific? Can I use some other version like JDK 1.5?
    Trust me, you will save yourself a lot of time in using the version we request. We find that a method we rely on, has somehow been changed to a private method since 1.4.2_04, so you might experience issues like

    java.lang.IllegalAccessError: tried to access field
    org.apache.xpath.compiler.FunctionTable.m_functions from class org.apache.xml.security.Init



    For JDK 1.5, we have identified some code changes that need to be done before it can operate properly.
  3. Is the "wildcard" feature that was introduced in Hermes 1 still valid in Hermes 2?
    No, this feature has been taken away from Hermes 2, due to the change in principle from push mode to polling mode. You need to specify precisely on what are the messages you want to send or receive.
  4. OK, now everything is working, what if I want to write a client?
    To keep things simple, let's focus on ebms message delivery first. First of all, you need to create a "partnership" for sending out messages. You can do so by using the program in the loopback test, the program will read a "data" file which define the details of the partnership (think partnership to CPA in ebMS).
    After that, you develop your program and make a web service call to Corvus for message delivery. The web service call will include some of the key information you defined in the partnership, so that Corvus can pick up the rest (like where to send it to) from the database.
    The "end point" on Corvus that responsible for picking up the request is
    "http://127.0.0.1:8080/corvus/httpd/ebms/sender" and you need to supply the following information in the web service call,

    • cpaId
    • service
    • action
    • conversation id
    • from party id
    • from party id type
    • to party id
    • to party id type
    • ref to message id

    Also, you will want to create an "AttachmentPart" which carries the "payload" you want to send over to the recipient.
    Upon making the request, you should get a soap response. The body inside should contain an element called "message_id" and the value of this is a string. This is the "token" that Corvus generated for you. You can use this "token" to perform query.


I hope this episode can help you a bit in kicking start the installation. When you are busying in setting up the environment, I will prepare my next episode, focusing on the partnership thing and hope to bring you something more interesting. Stay tuned.