Supporting multiple ebMS service versions in Oracle B2B

In recent years I've been involved in different Oracle B2B implementations and troubleshooting projects based on ebMS and AS2 protocols. Not so long ago, I came across a project that needed to support multiple versions of an ebMS service. Versioning is quite trivial for SOAP and RESTful Web Services using e.g. different namespaces, version indicators in endpoint locations, and so on. However, it is a bit different for ebMS-based services implemented in a B2B gateway.

Case

ebMS is one of the protocols supported by the Dutch government standard DigiKoppeling for exchanging information between governments such as municipalities, provinces, and departments. In this particular case, the existing integration flow that needed to support a new version of an ebMS service is as follows:

OLO (Omgevingsloket Online) is a government solution where companies and citizens can apply for permits. OLO routes those permit requests, using the ebMS protocol, to the applicable government agency based on the type of permit. In this case Oracle B2B is used by one of these government agencies to process these permit requests. B2B transforms and routes the inbound messages to Oracle Service Bus using JMS, while OSB forwards the requests to a backend application by invoking a SOAP Web Service. Vice versa, outbound messages are transformed by B2B to ebMS and send to OLO. You can read more about this case in a presentation I gave at OUGN.

Problem

OLO offers different versions of its service, among others the StUF LVO 3.05 and StUF LVO 3.11 version. The challenge was to add support for StUF LVO 3.11 while maintaining support for StUF LVO 3.05. In OSB we simply added a new service according to the StUF LVO 3.11 specification, alongside the existing service that processes 3.05 messages. The next section describes the solution for the B2B configuration.

Solution

First step is to define a new "Document Protocol Version" of type "Custom" in Oracle B2B and add the 3.11 "Document Types" to it. For StUF LVO 3.05 we already created a Document Protocol Version containing all of the 3.05 document types.

Next we add the 3.11 document types to the two existing trading partners: OLO and the government agency that processes the permit requests. We also specify if the document can be send or received by that particular trading partner.

To complete the B2B configuration we define the agreements. Here we can make sure that service versioning is supported:

Inbound messages from OLO to B2B to OSB

• ebMS requires a design-time contract between the service provider and the service consumer. This contract is called CPA (Collaboration Protocol Agreement) and CPP (Collaboration Protocol Profile). For the new version of the service that supports 3.11 a new CPA was created. This CPA has a different CPA identifier than the CPA we created for the 3.05 version. By assigning this new CPA identifier to the newly added agreements using the "Agreement Id" attribute, B2B can distinguish between 3.05 and 3.11 messages.
• Messages from B2B to OSB are delivered on a JMS queue using a partner channel that is defined for the government agency in B2B. Here we define a new JMS channel that points to a different queue, for example the StUF_LVO_311_Queue. The new OSB service that processes 3.11 messages is listening on this queue, while the existing service processes messages from the 3.05 queue.

Outbound messages from OSB to B2B to OLO

OSB can integrate with B2B by setting specific JMS headers that B2B uses to correlate JMS messages to specific agreements. One of these headers is the DOCTYPE_REVISION attribute. In the new OSB service, we can simply set the header value to the Document Protocol Version that was configured for the 3.11 messages. Now B2B receives both 3.05 and 3.11 messages but is able to differentiate between them using the header properties.

Summary

I'm not the biggest fan of ebMS, but if you need support for it then Oracle B2B is a good product. The ebMS protocol is a point-to-point protocol build upon SOAP. Due to its point-to-point nature and complexity, the ebMS protocol isn't as flexible and doesn't promote reuse the way that "plain" SOAP Web Services and RESTful Web Services do.

However, if ebMS is a constraint in your project than Oracle B2B offers a good out-of-the-box solution that helps you to implement ebMS-based integrations that also support versioning.