Sunday, March 11, 2012

Handling Custom XML documents in Oracle B2B

With Oracle B2B which is a part of Oracle SOA Suite 11g R1 you can handle / interchange all kind of messages between partners. Oracle B2B supports many Documents Protocols like off course your own, EDIFACT,  HL7, RosettaNet and many more. Besides this it also supports many interchange channel protocols like AS2, Email , FTP , File etc.
B2B can listen on those channels and tries to identify the document together with the sender and the receiver. For this you need to register the document and create an Agreement between the two parties.  On the partner level you need to register some identifiers like a common name or an email address.
When the document is identified it will be translated to xml and this document can send this to an output channel, this can be a JMS Queue on which Oracle SOA Suite can listen.

In this blogpost I made a small example in which we have an employee xml message which is delivered to an folder, B2B has a listening Channel on this folder and tries to identify it ( uses xpath and examine the file name ). This particular Agreement says it has to deliver the message to a Queue.
This Queue is read by Oracle SOA Suite and the composite generates an employee response message and uses a B2B adapter to deliver it back to Oracle B2B.
The document is identified by Oracle B2B and this Agreement has email as output and the response message is delivered as an attachment in the email.

Off course this xml use case can also be done in Oracle SOA Suite but in my next blogpost we will make it more interesting by doing the same but then with an EDIFACT message where B2B can validate and transform the EDIFACT and even send an Acknowledgement based on the input message.

We start with the employee and the response schemas.

The employee schema

The employee response schema

I will use the user weblogic for all the B2B Administration so I need to assign the IntegrationAdministrators role to the weblogic user ( this can be done in the myrealm security realm).

We start by register these XSD documents in the Administration menu of the B2B application.
this is the url of the B2B application located on the soa server http://soa_server:8001/b2bconsole/faces/login.jspx

Select the Custom Document Protocol and click on the green plus button where we create a new Document Protocol Version called Employee_XSD

Save and click on the new Type button where we create a Document Type Name.

On this screen we can define our Defintion and where we need to upload the XSD.
Important for the identification of the message is that we need to provide the Identification Expression.

In this case I search for the element called type and see if it has employee2 as value.

We do the same steps for our employee response message.

Now we can move to the Partners registration part of the B2B application. Here we will create a partner, add some identifiers, register which documents can be handled by this partner and at last the output communication channel where we can define where the message will be send to.

First click on MyCompany, this is the master partner ( basically this is you, the owner of the B2B server ).

We need to define some Identifiers which can be used in the Partner Agreements.
First a Generic Identifier with MyCompany as value and an other one with as email address.

The Document and the roles this partner can handle, for EmployeeSchema de-select Sender and for the Response de-select Receiver.

The employee message will be delivered to a JMS Queue so we need to define an output channel. Define a JMS channel and provide the JNDI names of the Connection Factory and the JMS Queue.

We also need a Trading Partner so I created a Partner called CorpA. Here we also need to define some Generic Identifiers like CorpA and

The documents, in this case CorpA is the sender of the Employee message and receiver of Response message.

The CorpA want to receive the response as an email attachment so we need to define an email channel where we define the mail server details.

Next we need to define agreements between CorpA and MyCompany and back.
Select the CorpA Partner and create an Agreement

The incoming employee message agreement.

Here we need to select the Employee document and on the MyCompany side we need to choose the JMS channel. Click Save and Deploy the agreement.

In the response message agreement we need to use the Response document and on the CorpA side, select  the email channel.  Also on the the MyCompany side add the Email identifier so B2B knows who is the sender of the email.  Click Save and Deploy the agreement.

The next part is Oracle SOA Suite which receives the employee message and creates the response message.

Drag the B2B Adapter to the Exposed Services side of the composite.

  • Choose JMS as B2B integration type. 
  • Select your AppServer Connection -> The weblogic domain which hosts the SOA & B2B software.
  • Receive
  • Click Next on the Basic Tab
  • Open the Custom Document Definition and select the EmployeeSchema
  • Select Oracle WebLogic JMS in OEMS
  • Select your AppServer Connection -> The weblogic domain which hosts the SOA & B2B software.
  • Lookup the Queue in the Destination name.
  • Create an EIS connection with this name in the JMS Resource Adapter plan.

Drag the B2B Adapter to the External References side of the composite.

  • Choose Default as B2B integration type.
  • Select your AppServer Connection -> The weblogic domain which hosts the SOA & B2B software.
  • Send
  • Click Next on the Basic Tab
  • Open the Custom Document Definition and select the ResponseSchema

    Add an Mediator and wire the two adapters to this mediator.

    • Add a transformation where we will create the response message.
    • Add the B2B Assign Values so B2B can detect the agreement. 

    You need to provide the following Assigns

    b2b.fromTradingPartnerId -> MyCompany
    b2b.fromTradingPartnerType -> Name

    b2b.toTradingPartnerId -> CorpA
    b2b.toTradingPartnerType -> Name
    b2b.documentTypeName -> EmployeeResponseType
    b2b.documentProtocolName -> Custom

    b2b.documentProtocolVersion -> Employee_XSD

    Deploy the composite

    Back to B2B

    The last part before we can test this B2B example is to configure a listening channel which polls for new messages.

    We need to go back to the Administration Tab of the B2B application.

    Add a file channel and provide the Folder name. 
    Important we need to define a filename format so B2B can detect the sender. ( my custom document does not have an identification part )

    Now we can add a xml document to this MyCompany in folder and must be called CorpA.xml

    This is the example document with employee2 as value for the element type (else the document won't be detected).

     We can see the messages and the progress in the Reports part of the B2B Application.

    And the final result where we got an email with the employee response.

     In the next blogpost we will add some EDIFACT messages to B2B. 


    1. Excellent article. I liked it. Everything worked except the response message to CorpA. The response message looks same as CorpA.xml. I did the assign values as shown by you. Where does mediator add result to response message?

      1. Hi,

        Did you register the result XSD and switched sender , receiver in the mediator, set all the B2B assign properties in the mediator . The result will be filled in the XSLT of the routing rule.


      2. Yes it worked now. Appreciated your help.

    2. Hi,

      i have done entire set up for sending mail to given mail id but i am getting transport error .

      Transport error: [MsgCannotBeSent] SMTP message cannot be sent.

      Do while setting up channel we have to give incoming server details or outgoing server details of the email to which i want to send email.


      1. Hi,

        did you add email addresses to the sender and receiver of the agreements. and maybe put it in debug mode to see all the trace data.


    3. Hi Biemond,

      Great post.. thank you..
      Do you have source code for the above example?? It will help us a lot.

      1. Hi,

        that will be hard, cause almost everything configured in the B2B console.


    4. Hi Edwin,

      This is a very good example,you have made the b2b learning easy.


    5. Hi Edwin,

      Great Post, Thanks.
      I have one requirment to convert EDI 214(X12) document object to XML.
      Can you please help me here?


    6. Hi Edwin,

      How do I test this? Should I just add the CorpA.xml in the folder? Nothing is happening so far.

      Thank you!

    7. Hi Edwin,

      After the CorpA file has been consumed via listening channel, it doesn't seem to be published in the JMS Queue. Am I missing a step?


    8. Hi Edwin,

      I want to test the inbound and we are using SOAP based inbound channel.

      I am trying to send a soap request using SOAP UI to B2B. I have configured the generic identifier as of my sender system IP address and tried with sender name as an identifier too. But B2B is rejecting the inbound message and throwing "Document Protocol Identifier Error". Can you please let me know if we can test B2B using SOAP UI ? and if yes , where I should send identifier value ?