Announcing AS2 Plus

Background

Hermes2 AS2 plugin gained interoperability certification from Drummond Group in 2005. Literally, several additional features are suggested to be supported in AS2 . To retain the Drummond Group certificate, we decided to split out an enhanced version of AS2 plugin and name it as AS2 Plus. The certified one will remain untouched but you could find new features in AS2 Plus.

What are the difference between AS2 and AS2 Plus?

In AS2 Plus, we have introduced additional features and enhancement. They are listed as below,

  • In Memory Operation
  • Filename Preserved During Transfer
  • Removed the dummy column "principal-id" from table and column

In Memory Operation

Under the original architecture, payload of AS2 message will be persisted under the AS2 file repository. This architecture lowers the memory consumption, but in turns require several disk reading throughout the lifecycle (persist to disk, read from disk and then insert into DB). In the new approach, these steps are eliminated and reduced required active module from 3 to 2. These help to shorten the execution path and increase the efficiency of the operation. Below are the two modules that remain.

as2.module.core.xml of AS2 as2.module.core.xml of AS2 Plus

Filename Preservation

Preserving the filename of the payload is now an optional profile in AS2 specification. You may found the background information from this Drummond Group page. We received Hermes users enquiry about offering this feature. Therefore, we implemented according to the draft of "Filename Preservation for EDIINT". According to the draft specification, a MIME header name "Content-Disposition" will be attached on the MIME header of AS2 payload.


Here is the AS2 Message sent by AS2 Plus:
POST /corvus/httpd/as2/inbound HTTP/1.1
Date: 8 Jan 2010 11:57:19 GMT
From:
Message-Id: <20100108-195719-86300@147.8.178.168>
Subject:
AS2-Version: 1.1
AS2-From: as2loopback
AS2-To: as2loopback
Content-Type: application/XML
Content-Transfer-Encoding: binary
Content-Disposition: attachment; filename=testpayload
Cache-Control: no-cache
Pragma: no-cache
User-Agent: Java/1.6.0_17
Host: 127.0.0.1:8081
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
Content-Length: 1524

This is an sample message.
. . .
. . .
. . .

This is an sample message.


However, there are several limitation on this feature.

  1. ASCII character only
  2. If there is non-ascii character on the filename, it may raise an exception and corrupt the whole filename. And there is no clear consent/specification about the methodology of non-ascii encoding. Therefore, hermes will put the ASCII filename directly to the MIME header without encoding.

  3. Length of filename
  4. According to RFC2822 , each line of message SHOULD NOT exceed 78 characters. Therefore, after deducting the character taken by "disposition-type", there are only 56 characters left for the filename. In short, make sure the filename of your payload does not exceed 56 characters.

Installation

Running hermes installer again would be the best option to install the new AS2 Plus plugin or upgrade from AS2. Please obtain the latest installer from the download page.

If you want to upgrade to AS2 Plus, the original AS2 plugin(named "hk.hku.cecid.edi.as2plus") and AS2 Admin plugin (named "hk.hku.cecid.edi.as2plus.admin") should be removed from the plugin directory (<hermes_directory>/plugins/) first. Moreover, as the column "principal-id" has been removed, we suggest you to check the re-create table option in the installer. Be reminded that all data will be destroyed, thus backup the data before you do the upgrade!


image

What if I want to upgrade to AS2 Plus but preserving my data? If you want to preserve the data, currently, you may just remove the column "principal_id" in message table. (This alternative method work on current build hermes_20100108). After that, you can run the installer normally, but NOT to CHECK the re-create table option.

Usage of AS2 Plus

Once AS2 Plus installed, you may find two new plugins in the plugin directory.
  • hk.hku.cecid.edi.as2plus
  • hk.hku.cecid.edi.as2plus.admin

Web Services

The service endpoint for AS2 Plus remains the same, the end point provided are as follows,


Message Sender Service: /corvus/httpd/as2/sender
Message Receiver List Service: /corvus/httpd/as2/receiver_list
Message Receiver Service: /corvus/httpd/as2/receiver
Message Status Query Service: /corvus/httpd/as2/status
Message History Query Service: /corvus/httpd/as2/msg_history


You can follow the article "Communicating Hermes through WS" to learn more about the operation.

AS2 Plus Admin Pages

Apart from the change in the name of the plugin, there are no functional difference between AS2 and AS2 Plus, on both message history and partnership maintainace page. The procedures to create, update and delete partnership are descripted on this article. If you want to learn more about the parameters of AS2/AS2 Plus partnership. Please go to the article AS2 Partnership Reference.


image

Web Servce Sample

The web service sample has been updated to support the new feature - file name preservation. Hence, the updated web service sample can work well with both AS2 and AS2 Plus. The program parameter are same as usual.

Sender Sample

In order to provide filename information to hermes, the sample will store the filename value in the MIME header.



------=_Part_0_14158819.1262952792784
Content-Type: application/octet-stream
Content-Disposition: attachment; filename=testpayload

This is an sample message.
. . .
. . .
This is an sample message.
------=_Part_0_14158819.1262952792784--

As the soap message shows, a header "Content-Disposition" has been attached to pass the filename value to hermes. It can simply implement by adding the header to AttachementPart of the soap request message.



Hence, there is no change on the program parameters, and the configuration xml. Please refer to this paragraph for detail.

Receiver Sample

As stated above, the filename information is preserved. The receiver service will save the payload according to the filename value comes with the MIME header.



HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Accept: text/xml, text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Content-Type: multipart/related; type="text/xml"; boundary="----=_Part_0_2773785.1262953514606"
Transfer-Encoding: chunked
Date: Fri, 08 Jan 2010 12:25:14 GMT


------=_Part_0_2773785.1262953514606
Content-Type: text/xml; charset=utf-8
. . .
. . .
------=_Part_0_2773785.1262953514606
Content-ID: null
Content-Type: application/XML
Content-Disposition: attachment; filename=testpayload

This is an sample message.
. . .
. . .
. . .

This is an sample message.
------=_Part_0_2773785.1262953514606--

You may now found "Content-Disposition" are defined in the SOAP response. Under some circumstances, the filename value will be overridden by hermes. E.g., if the filename contain non-ascii characters or was empty, the filename will be replaced. In the AS2MessageReceiver class, we have implemented a logic to retrieve filename value from the AttachementPart.





The payload is now saved as "testpayload" which the name of the payload comes with installer.


image

If you forgot how to execute web service sample, please refer to this paragraph.



Discuss this in our forum

Posted by Ronnie Kwok on 01/08 at 08:35 PM