Best Practices from Oracle Development's A‑Team

Using Business Events in Fusion-based SaaS with Oracle Integration Cloud Service - Part 3: Event Filter Expressions

Stefan Koser
Consulting Solutions Architect

In the previous two posts, Part 1 and Part 2, we gave an overview which Business Events are available in R13 and how you can subscribe to events with external applications using Oracle ICS/OIC. In this part, we will show how to filter events using XPath expressions.

Use Cases for Filtering Business Events

The approach on sending a message in case of every creation/update/deletion of a Business Object is not what might be required in a specific use case. In our previous example we showed how to publish an "Item Creation" event in case an new item has been created in SCM Cloud.

One use case could be that an external system needs to have this information - but only for a specific ItemClass only. In our example we will send the "Item Creation" event only in case the item class is "Smartphones"  (using a Vision demo instance of R13 GSI).

Some examples of other potential use cases:

  • In a multi-national organization with subsidiaries, events should be sent only to specific countries/regions. For example, an organization could have Oracle Sales Cloud as world-wide CRM solution, but regional different fulfillment systems, for example different for US and EMEA.

  • In a Customer Data Management solution (using Oracle Customer Data Management Cloud) you want to send updates to all other participating system - but one external system covers only a subset of customers - for example business customers (B2B).

  • Similar use case in a Product Master Data Management solution (using Oracle Product Master Data Management Cloud)

In the next chapter, we will show two examples - for filtering Item Creation events (in SCM) and for filtering Contact Creation Events (in CRM/Sales Cloud).

Defining a Filter for Business Events in Integration Cloud Service

As first step, deactivate the integration previously created in Oracle Integration Cloud Service to enable editing:

1 - Edit Integration

Then edit the ERP Cloud Adapter connection on the left side and navigate to the "Request" settings.

Enter the following XPath expression for Item Create Event:

<xpathExpr xmlns:ns_0="http://xmlns.oracle.com/adf/svc/types/"

Be sure to enclose string literals in single or double quotes. We will in explain in the following chapter how to construct this XPath expression. This is how the Request page should look like:

2 - Edit Event Request

After "Next", ICS will verify the XPath expression - if no error is reported, then finish editing the connection by "Done", save and close the integration and activate it.

How to Derive the Correct XPath Expression

Business events in Fusion-based SaaS are processed like this

  • If a business object is created, updated or deleted, an event is triggered inside SaaS if there is a subscription. This event payload contains only some core elements of the business object.

  • An enrichment service is called to get the complete data of this business object

  • This enriched payload is sent to the external system which has been registered to receive the event (in our case ICS/OIC)

The payload in most cases is identical to the findXXX web service response payload.

Let's look at our example - the "Item Creation" event. The corresponding event payload is based on the findItemResponse structure of the findItem operation in web service ItemServiceV2. You can find a documentation of the SCM web service structures in der SCM Cloud API Documentation.

The structure looks like this:

3 - XML structure

The XPath expression needs to start with the "result" level - and needs to have the correct namespaces:

So for "ns_2:result/ns_0:Value/ns_1:ItemClass", the namespaces need to be derived from above response payload as.

  • ns_2: "http://xmlns.oracle.com/apps/scm/productModel/items/itemServiceV2/types/"

  • ns_0: "http://xmlns.oracle.com/adf/svc/types/"

  • ns_1: "http://xmlns.oracle.com/apps/scm/productModel/items/itemServiceV2/"

The root path for the XPath expression starts with the variable $eventPayload - this references the variable which stores the result after calling the enrichment service.

Testing the Event Filter

After activation of the integration, create a new item in SCM Cloud "Product Development". If you create one of item class "Smartphones" it should trigger the integration - if you create an item with a different Item Class - then no integration should be started.

If the result is different, the first check the event subscription via the FA Cloud instance endpoint https://XXX.oraclecloud.com/soa-infra/PublicEvent/subscriptions

The event subscription JSON should include the "filter" XPath definition as below:

[ {"csfKey":"a112325", 
   "filter":"<xpathExpr xmlns:ns_0='http://xmlns.oracle.com/adf/svc/types/' xmlns:ns_1='http://xmlns.oracle.com/apps/scm/productModel/items/itemServiceV2/' xmlns:ns_2='http://xmlns.oracle.com/apps/scm/productModel/items/itemServiceV2/types/'>$eventPayload/ns_2:result/ns_0:Value/ns_1:ItemClass=Smartphones</xpathExpr>", 

Another Example for Contact Creation

The structure for filtering contact creation events can be derived easily the same way:

First look at the response payload of findContact: (you can find the documentation of Sales Cloud SOAP Conatct Web Service here)

4 - XML structure FindContact

Comparing the namespaces, the XPath Expression to filter "Contacts" should look like the following. I have used a filter which allows only contacts from Germany using element "Country":

<xpathExpr xmlns:ns_0="http://xmlns.oracle.com/adf/svc/types/" 

You can test the filter by creating a new lead in Sales Cloud and adding new contacts. In case of a new contact with German address, you will see an instance created via ICS/OIC Monitoring

5 - Instance of Contact Created


Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha