Implementing Ping Pong ebXML in Oracle B2B

One of the features described by the ebXML standard is sending ‘Ping’ messages. It enables one partner to determine if another is operating. It consists of:

• One partner sending a Ping message
• Another partner receiving the Ping, and responding with a Pong message

ebXML messaging services: up and running?

Not just verifying the physical connection (as we can check with a TCP ping), the ebXML Ping/Pong also verifies the ebXML messaging services are up and running on the other side, and that the agreement has been setup as expected. Oracle B2B also supports this part of the ebXML standard. In this article i'll show you how to implement it [3].

Setup in Oracle B2B

Prerequisite: first thing we have to do is make sure we already have a trading partner and channel setup. Without this there is no one to communicate with. In this example we are ‘Qualogy’, and our trading partner is called ‘OfficeSupplies’.

What are we going to do?

1. Define a Ping-OfficeSupplies document type
2. Define a Ping document definition
3. Add a Ping document definition to each trading partner (Qualogy and trading partner OfficeSupplies).
4. Setup inbound and outbound agreement for trading partner OfficeSupplies
5. Save and deploy agreements
6. Testing Ping

Define Ping document type

The first step is to define a document. Go to: administration -> documents and select ‘custom’. If not already defined, define a version '1.0'

For this version we add a new document type.

Fill in the following fields:

• Document type name: Ping-OfficeSupplies
• Action: Ping
• Service name: urn:oasis:names:tc:ebxml-msg:service

All bold values are mandatory, and should exactly match the example depicted here.

And now click save.

Define Ping document definition

Now click the ‘New Definition’ button (top right, next to the save button), and choose the following values:

• Document Definition Name: Ping
• XPath expression 1: /*[local­name()='Ping']

Click save to store the definition.

Add Ping document definition to each trading partner

First we check trading partner Qualogy. We should be sender and receiver of the Ping message. This newly added document type should by default show up at the ‘host’ trading partner.

Now, click trading partner OfficeSuppliesTP and check the documents tab. Here we expect no documents to be found. Now add the newly created Ping message by clicking the ‘plus icon' on the right top. Navigate to the Ping document and click add. Make sure to check both sender and receiver columns. Then click save.

Setup inbound and outbound agreements

Finally two agreements (inbound and outbound) need to be setup for trading partner OfficeSuppliesTP. Keep trading partner OfficeSuppliesTP selected and click the plus icon to add a new agreement.

1. Inbound

Just name the agreement in a way you prefer. The agreement ID however should match the agreement ID from the Collaboration Protocol Agreement (CPA). For more details check this blog.

Add a document to the agreement by clicking ‘Select Document Definition’.

Then select the Ping document which is inbound (arrow from OfficeSupplies towards Qualogy)

Choose a channel at OfficeSuppliesTP, and add the identifiers for each trading partner.

Which identifiers have to be used are also found in the CPA.

Now click 'save', then 'validate' and finally 'deploy':

2. Outbound

For outbound we do exactly the same except:

When selecting the 'Document Definition', we now select it the other way around (from Qualogy to OfficeSuppliesTP).

This agreement will be named ‘Outbound’.

Save, validate and deploy... and we are ready for business!

Agreement overview

Once deployed, you should see the following agreement overview. The ‘document icon' indicates the agreement is active and has been successfully deployed.

Testing Ping message

To invoke a Ping message from Qualogy to OfficeSuppliesTP, we can use a small database script. This script will put a Ping message on the B2B queue.

To check which database and credentials to use go to the Weblogic Console for this B2B server, for example: http://localhost:7001/console. Go to Services -> Data Sources

Look for a B2B Data Source, if there has been one defined by the DBA. By default the B2B schemas are installed in the same database as the soainfra. For the Oracle SOA Developer VM we’ve used the URL and credentials from the SOADataSource.

Add the connection details to your favorite SQL Editor and connect.

Use the script below to put a Ping message on the B2B queue. Modify the script accordingly if your trading partner names or document types are different.

DECLARE
    xml_message CLOB;
    lc_ping_message CLOB := '<?xml version="1.0" encoding="UTF-8" ?>
                                              <Ping>ebMS Ping Message</Ping>';
 
    PROCEDURE sendmessage( 
          p_xml_clob CLOB
        , p_from VARCHAR2
        , p_to VARCHAR2
        , p_doctype_name VARCHAR2
        , p_doctype_revision VARCHAR2 
    ) AS
        r_enqueue_options      DBMS_AQ.ENQUEUE_OPTIONS_T;
        message_properties    DBMS_AQ.MESSAGE_PROPERTIES_T;
        v_message_handle     RAW(16);
        ipmsg                           IP_MESSAGE_TYPE;
        xml_clob                      CLOB;
        msg_id                         NUMBER(10);
        subscribers                  dbms_aq.aq$_recipient_list_t;
    BEGIN
        xml_clob := p_xml_clob;
        subscribers(1) := SYS.AQ$_AGENT('b2buser', NULL, NULL);
        message_properties.RECIPIENT_LIST := subscribers;
 
        -- msgid, inreplymsgid, from, to, actionname, doctypename, doctyperev, msgtype, payload, attachment
        ipmsg := IP_MESSAGE_TYPE( msg_id, NULL, p_from, p_to, NULL
                , p_doctype_name, p_doctype_revision, 1, xml_clob, NULL);
 
        sys.dbms_aq.enqueue (
            queue_name         => 'IP_OUT_QUEUE',
            enqueue_options    => r_enqueue_options,
            message_properties => message_properties,
            payload            => ipmsg,
            msgid              => v_message_handle
        );
        commit;
    END sendmessage;
 
BEGIN
	sendmessage( lc_ping_message, 'Qualogy', 'OfficeSuppliesTP', 'Ping-OfficeSupplies', '1.0' );
 
END;
/

Login to Oracle B2B console

To verify the Ping message was actually picked up by B2B. Login to the Oracle B2B console and navigate to ‘Reports’.

Communicate with ebXML enabled trading partner

In our environment we have sent two Ping messages. The first attempt failed (MSG_ERROR) because we’ve set up the trading partner channel with an invalid URL.

The second attempt was performed after pointing the OfficeSuppliesTP channel towards a SOAPUI mock service running locally. Because SOAPUI did not send any response back, we see the status still being MSG_WAIT_ACK. An ebXML Acknowledgement is expected by B2B.

When we actually communicate with an ebXML enabled trading partner we would receive:

• ebXML Acknowledgment (from trading partner), indicating the Ping was received
• An ebXML Pong message, in which the trading partner returns the favor of sending a message back to us.
• Oracle B2B will respond to their Pong message with an ebXML Acknowledgement automatically.

If our trading partner would initiate this connectivity check by sending us a Ping message, B2B will respond accordingly with a Ping Acknowledgment, followed by a Pong message being sent to our trading partner.

References

[1] Building ebXML messaging with Oracle B2B 11g

[2] Doing EBMS PING PONG

[3] Message Service Specification OASIS ebXML Messaging Services Technical Committee

About the author Richard Velden

Oracle Fusion Middleware Developer at Qualogy. Specializes in integration and cloud development using Oracle technologies such as: SOA Suite, Service Bus, Integration and Process Cloud.

More posts by Richard Velden