EbXML is an international effort, led by the UN/CEFACT and OASIS standards groups, toward business-to-business communication using XML. It hopes to succeed the Electronic Data Interchange, an older and better established standard which has been deemed too cumbersome for modern standards. EbXML is based on SOAP, adding specific XML elements into SOAP's infrastructure to provide a "modular" system for representing business transactions. An introduction is here.
In basic terms, companies implementing EbXML services will publish their services to a common repository, which is also used to locate other available services. Once connected, applications can communicate using EbXML-compliant SOAP messages over the Internet. Such applications are known as "Web services".
EbXML defines a set of XML schema that extends the basic elements defined by SOAP: it is a SOAP extension, and the root elements of any EbXML document are the SOAP Envelope, Header and Body elements. Most of the EbXML-specific elements go into the Header element, including the sender and recipient, certain IDs, and the name of the service and "action" that the EbXML message means to invoke. The SOAP "Body" element contains an EbXML-defined "Manifest" child element. That element contains references to one or more "payload" elements, which are essentially SOAP attachments. A SOAP attachment can contain any data; but commonly, one of them will represent the main body of the EbXML message, which is likely another XML document.
An example of a complete EbXML message can be found here.
The primary Java API for processing EbXML is called "SOAP With Attachments", or "SAAJ". This library provides the building blocks for a SOAP XML message, to which you can add EbXML-specific elements as needed. An example that builds an EbXML message using SOAP is the first class listing ("SOAPUtil") on this page. (Please note, that source code listing includes an "import" statement for javax.xml.messaging, which is gratuitous: the class will compile without that import.)
Sun Microsystems has released a new messaging API called JAX-M, which provides asynchronous as well as "reliable delivery" of messages. It also provides (although apparently as an afterthought) a few "profiles", which are meant to facilitate the use of SOAP extensions and include a module for EbXML specifically. This author found the JAX-M EbXML profile only marginally useful. Moreover, for applications which require only simple, synchronous messaging, JAX-M offers nothing over SAAJ and is unnecessary.
An OXCI EbXML message, then, will include its legal filing XML document as a SOAP attachment. The main MIME part consists of the SOAP envelope, in which the SOAP "Header" element will contain an EbXML "MessageHeader" and the SOAP "Body" will contain an EbXML "Manifest" element, which identifies all message attachments. This MIME part might look like this:
------=_Part_0_33239569.1082052337669
Content-Type: text/xml
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xm
lns:eb="http://www.ebxml.org/namespaces/messageHeader" xmlns:xlink="http://www.w
3.org/1999/xlink">
<SOAP-ENV:Header>
<eb:MessageHeader SOAP-ENV:mustUnderstand="1" version="1.0">
<eb:To>
<eb:PartyId>mailto:openefm@counterclaim.com</eb:PartyId>
</eb:To>
<eb:From>
<eb:PartyId>mailto:sender@counterclaim.com</eb:PartyId>
</eb:From>
<eb:CPAId>123</eb:CPAId>
<eb:ConversationId>200002</eb:ConversationId>
<eb:Service>urn:services:FilingSubmission</eb:Service>
<eb:Action>Submit Filing</eb:Action>
<eb:MessageData>
<eb:MessageId>1082052337643</eb:MessageId>
<eb:Timestamp>Thu Apr 15 11:05:37 PDT 2004</eb:Timestamp>
</eb:MessageData>
</eb:MessageHeader>
<EFSPUsername>smeagol</EFSPUsername>
<EFSPPassword>gollum</EFSPPassword>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<eb:Manifest>
<eb:Description>A Legal XML Filing</eb:Description>
<eb:Reference xlink:href="xml-filing" xlink:type="simple"/>
<eb:Reference xlink:href="some-other-id" xlink:type="simple"/>
</eb:Manifest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Near the bottom, note the two xlink references to SOAP attachments (not shown here) in the "Manifest" element, the first of which refers to another MIME part containing a legal filing XML document. These are called "payloads" (for whatever reason) and can be attached to the SOAP message using the SAAJ library from Sun Microsystems or using Apache Axis. Just remember to add an xlink reference in the EbXML "Manifest" for each attachment. The first attachment must be the actual legal filing.
In the SOAP header element (but not within the EbXML header) are the elements "EFSPUsername" and "EFSPPassword". This is where the EFSP will place its own credentials for authentication at the EFM. These elements belong to neither SOAP nor EbXML. We have not found an appropriate element in those schemata to represent this login information, so we've just invented them.
The remaining EbXML elements you see defined above, such as the CPAId, do not matter to OpenEFM, yet they are required fields for an EbXML document. Not even the "Service" or "Action" arguments are currently used, since any SOAP message sent to OpenEFM's filing "endpoint" is assumed to be a legal filing submission.
OpenEFM provides a convenient Java client API for producing and submitting EbXML-formatted legal filings from another Java application to OpenEFM. This is class com.counterclaim.openefm.client.EbXMLClient. To use it, you must also create an instance of a com.counterclaim.openefm.model.lxml.LxmlFiling and be prepared to use a com.counterclaim.openefm.model.lxml.LxmlResponse.
Call the "setter" methods on the EbXMLClient object to ready it for use: and again, many of the exposed fields are not significant but are required nonetheless, so define them all. Set your EFSP's username and password for the EFM at which you are filing. Populate the LxmlFiling with appropriate data, and then pass it to EbXMLClient.submitFiling(), which returns an LxmlResponse object, which in turn can be used to output the result of the operation.
To add an attachment to the message, create a com.counterclaim.openefm.model.lxml.LxmlFilingAttachment and add it to the LxmlFiling object, prior to submission.
Here is an example:
LxmlFiling filing = getLxmlFiling(); // filing is built elsewhere
LxmlFilingAttachment attachment =
new LxmlFilingAttachment(new File("./sample-lxml.xml"), "text/xml");
filing.addAttachment(attachment, "some-other-id");
EbXMLClient client = new EbXMLClient();
client.setEndpoint(new URL("http://localhost:8282/receiver/efsp/ebxml")); // point to the EFM
client.setEFSPUsername("gollum");
client.setEFSPPassword("precious");
client.setSenderURI("mailto:client@counterclaim.com");
client.setRecipientURI("mailto:openefm@counterclaim.com");
client.setCPAID("123");
client.setConversationID("200002");
client.setService("urn:services:FilingSubmission");
client.setAction("Submit Filing");
client.setDescription("A Legal XML Filing");
LxmlResponse response = client.submitFiling(filing);
String reply = response.getResponseText();
Update Author: Jason Van Cleve
Version: 04.14.2004
Original Author: Jason Van Cleve
Version: 04.14.2004