Saturday, October 31, 2009

How to use composite sensors to enable end-to-end tracking of B2B messages in SOA Suite 11g

Prior to the 11g release of the SOA Suite end-to-end trackig&tracing of messages send out from OESB or BPEL via Oracle Integration B2B 10g, was not supported out-of-the box, because Oracle Integration B2B 10g was/is not part of the 10.1.3.x SOA Suite Suite. You always had to build custom code to enable end-to-end tracking & tracing of messages in such environments.

Because B2B is now fully integrated into the SOA Suite, it becomes possible to easily end-to-end B2B messages using composite sensors.

How to use composite sensors in common is described here by the Oracle SOA Suite PM team. Ok..but how can you use this feature to end-to-end track B2B messages that are submitted from a composite to Oracle B2B or vice-versa? Actually, it's quite simple. Below I will describe what you have to do at design-time and run-time to track B2B messages using the B2B message id as an example.

At the B2B adapter in JDeveloper composite editor we define a composite sensor named order_msgid (assuming you are using the example that I have given in a previous posting on this blog) and assign it the value of the b2b property b2b.messageId.  In my example I use an outbound scenario, so to make it work I have to set the message id in the composite instead of delegating the creation of the message id to B2B. In the mediator component I set the value of the b2b.messageId to the compositeInstanceId. At design time, we are finished deploy your sensorized composite to the server.

At run-time we have to add a search field for the defined sensor to be able to search on message ids in the composite instances tab. Go to the instances tab of the composite and click on 'Add fields' and select 'order_msgid'. It will be added to the search form. Note that the SOA engine automatically detects composite sensors! The instances tab should look as follows:

Test the composite by using the EM test screen. Select the new instance and open the instance flow. Unfold the payload of the B2B adapter message and verify that the b2b.messageId property has been set in the properties header:

Log in to the b2b management console (my B2B url: http://localhost:8001/b2b) and open the reports tab and select the business message tab. Select the details of the corresponding B2B message and discover that it has used the message id that has been set by the composite :)

You now can search in the EM composite instances tab for a specific instance using the B2B message id. This becomes very useful when the number of composite instances becomes very large in a production environment and maintenance team quickly wants to track down the flow of a specific B2B message in case of issues with that message..

Tuesday, October 27, 2009

Easy binding of Oracle Fusion Middleware B2B 11g with a SCA composite using the B2B adapter

In my previous posting,I have described how to set up a simple XML document exchange configuratation in Oracle Fusion Middleware B2B 11g. In this posting I will show how to use the new B2B adapter part of SOA Suite 11g to easily send out XML orders from a SCA composite.

The SCA that we are going to build will consist of a simple SOAP interface that accepts new orders. A mediator component will route the order directly to Oracle Fusion Middleware B2B using the B2B adapter. For simplicity, we will use the same XSD structures.

JDeveloper Project and the mediator component
The first step is to create a new JDeveloper SOA project. Start with an empty composite. Drag and drop a new mediator component from the component onto the component panel of the composite diagram. Name the component ProcessOrder. Select the one-way interface type and use the same XSD input structure for the order as used in the B2B document definition configuration. Also create a composite service with SOAP bindings (checkbox). Click on 'Ok' to create the mediator component. In a later step we will specify the necessary assign and transformation actions.

B2B adapter
In Oracle Fusion Middleware 11g the B2B adapter is introduced to make the  binding of the B2B component with a SCA composite more native. The B2B adapter wizard allows the developer to browse the B2B document repository to easily select the right document type for inbound or outbound messaging with a trading partner.

Drag a B2B adapter from the component palette and drop it onto the reference service swimlane. A wizard will automatically pop up. Name the service B2B_Order_Gateway. Click 'next' and choose default as the integration type. The integration type specifies how SCA will communicate with B2B. Default means that a WSDL file with a native B2B binding will be constructed. AQ means that a JCA AQ WSDL file will be constructed. Click next and select the Fusion middleware server connection for browsing the B2B repository and click next. Choose for the option 'Send', because the composite is going to send out orders and click on next and again on next in the following screen (we use the defaults in that screen :)). In the wizard-screen Document Definition you have to browse to the ComplexOrder_Def and select it as the document definition. Click on next and on finish to complete the wizard. The B2B binding reference service will now be created and added to the SCA composite and the required artifacts will be generated.

Figure 1

Wiring everything together
As one of the last steps, we need to wire the mediator component to the B2B binding reference. You can do this by selecting the orange arrow (will pop-up when you hover over the Mediator component) of the mediator component and hold the left mouse button pressed, drag the mouse to the B2B binding reference service and drop the line on the orange arrow of the B2B binding component. Figure 2 shows the end result.

Figure 2

Double click the mediator component and generate a standard XSLT transformation to transform the input order structure to the expected order structure of the B2B reference service (Note: that JDeveloper recognises that the B2B binding reference expects a specific XML structure. Magic, isn't it? :)). Instead of using XSLT, we could also use an Assign action here.
The last thing we have to do is to inform the B2B binding reference service that we want to send an order to Acme from the host MyComposite. We use the Assign values option of the mediator component and two of the available B2B properties for this. Assign:

Acme -> b2b.toTradingPartnerId
MyCompany -> b2b.fromTradingPartnerId

(See Figure 3 for assigning properties)

Figure 3

 Save your project and deploy it to your Oracle Fusion Middleware server and use the built-in composite test functionality of the EM console to test your SCA composite. If you have implemented the composite correctly and configured B2B correctly as well (as described in my previous posting) you will see an order in the Acme outbound file directory that you have chosen during B2B configuration after you have executed test.

'A child can do the laundry' as we name easy procedures like this in my country :)

Sunday, October 25, 2009

How to set up a XML document exchange configuration in Oracle Fusion Middleware B2B 11g

In the new 11g release of the Oracle SOA Suite,  B2B is fully integrated in Oracle's SOA stack. The engine and the UI console are enhanced and improved on several parts compared to the 10g release of Oracle Integration B2B.

In this blog posting, I show you how to set up a XML document exchange configuration. It will also let you experience the renewed B2B Console based on ADF Faces technology. The case will consist of a custom XML document (Order), a single trading partner Acme and an agreement that specifies that MyCompany (the default host) is capable of sending out XML orders to Acme.

Log on to the B2B console. If you are familiar with the 10g console, you will immediately notice the new look-and-feel and the way things are organized (see figure 1).

Figure 1

Trading Partner
First we have to create a new trading partner. Click on the green plus sign on top of the Trading Partner (TP) panel on the left side of the screen.  Name the new TP Acme and click on ok. The next thing we have to configure is the type of document that we want to exchange with Acme.

Document definition
Documents are managed in the Administration window. So click on the Adminstration link at the top of the screen and open the Documents tab on new page. The left panel shows the supported document protocols. Select the Custom protocol and click on the green plus sign to add a new Custom Revision. In the form set the name to Custom_1.0 and click on save. Select the Custom_1.0 revision in the left panel and again click on green sign to add a document type. In the form set the name to XMLDocumentType and click on save. In the left panel select the XMLDocumentType and click on the plus sign to add a document definition. In the form set the name to ComplexOrder_Def, the Identification Type to XML. In the Definition field you have to the set the xsd structure of the complexOrder. Can be anything and I assume you know how to define a XSD structure. Leave all the other fields untouched, because we don't need them for this simple case.  See figure 3 for an example of the protocol tree in the left panel and the completed Document definition form.


Ok, by know you have probably experienced the usability of the renewed B2B console. In my opinion the new Oracle Integration B2B 11g console enables you to keep a better overview of what you have configured and where you are in a specific configuration part, e.g. setting up new documents.

Document capability
Now we have to add a capability to the TP Acme to inform the B2B engine that Acme is capable of receiving XML orders from our side. Go back to the Partner page (Partner link at the top of the page). Select Acme in the trading partner and in the right panel select the Document tab and click on the green plus sign at the Documents overview to add new a document capability. In the Select document definition pop-up screen unfold the Custom tree and select the ComplexOrder_Def definition and click on Add. Make sure that only the receiver checkbox is checked; we are only going to send orders to Acme. Click on save to save the capability. B2B automatically adds a dual capability to MyCompany for the same document definition and the dual direction that you have specified at the trading partner side. Check it. Figure 3 shows the Trading Partner document screen

Figure 3

Delivery Channel
The next thing that we need to configure is the channel on which Acme wants to receive the orders. For simplicity, we use the file system as the transport protocol. Oracle B2B also supports e.g. FTP, JMS, Email, HTTP. Click on the channels tab in the right panel of Trading Partner Acme. Click on the green plus sign and set the protocol to file and the name to Acme_File_Channel. At the bottom of the page set the transport protocol parameters and the channel parameters to your own need. Note: you can use placeholders in the filename format field. I used this format:


More available placeholder can be found here.  Click on save when you are done.

Agreement and deployment
At this point we have set uo the exchange document type, TP capabilities and the Acme delivery channel. We are now ready to create an agreement. On the Partner page click on the green plus sign to add a new agreement. Figure 4 shows you how to fill in all the fields in the Agreement form.

Figure 4

After you have completed the form, save the agreement. Before we can deploy the agreement we first have to validate it; click on validate and finally on deploy to make the agreement active. We are now ready to send out orders to Acme :)

This blog has shown how to setup a simple document exchange configuration in Oracle Fusion Middleware B2B 11g. In a next posting I will describe how the new B2B adapter in 11g can be used to construct and send out orders from a composite using a BPEL or Mediator component.