Introduction

This blog is part of the series of blogs the A-Team has been running on Oracle Service Cloud(Rightnow).

In the previous blogs we went through various options for importing data into Service Cloud. In this article I will first describe two main ways of subscribing to outbound events, as data is created/updated/deleted in Rightnow. These notifications are real-time and meant only for real-time or online use-cases.
Secondly, I will briefly discuss a few options for bulk data export.

This blog is organized as follows :

1. Event Notification Service (ENS) – The recently introduced mechanism for receiving outbound events
   • a. Common Setup Required – for using ENS
   • b. Registering a Generic Subscriber with ENS
   • c. Using Integration Cloud Service – the automated way of subscribing to ENS
2. Rightnow Custom Process Model(CPM) – The more generic, PHP-cURL based outbound invocation mechanism
3. Bulk Export
   • a. Rightnow Object Query Language (ROQL) and ROQL based providers
   • b. Rightnow Analytics Reports
   • c. Third-party providers

1. The Event Notification Service

Sincethe May 2015 release Rightnow has a new feature called the Event Notification Service, documented here .
This service currently allows any external application to subscribe to Create/Update/Delete events for Contact, Incident and Organization objects in Service Cloud. More objects/features may be added in upcoming releases.

I will now demonstrate how to make use of this service to receive events. Essentially there are two ways, using the Notification Service as is (the generic approach) or via Integration Cloud Service (ICS).

a. Common Setup

In order to receive event notifications the following steps have to be completed in the Rightnow Agent Desktop. These steps need to be completed for both generic as well as the ICS approaches below.

1. In the Agent Desktop go to Configuration -> Site Configuration-> Configuration Settings. In the Search page that comes up, in the ‘Configuration Base’ section select ‘Site’ and click Search.
2. In the ‘Key’ field enter ‘EVENT%’ and click Search.
3. Set the following keys:
   
   • EVENT_NOTIFICATION_ENABLED – Set it to ‘Yes’ for the Site. This is the global setting that enables ENS.
   • EVENT_NOTIFICATION_MAPI_USERNAME – Enter a valid Service Cloud username.
   • EVENT_NOTIFICATION_MAPI_PASSWORD – Enter the corresponding password.
   • EVENT_NOTIFICATION_MAPI_SEC_IP_RANGE – This can be used for specifying whitelisted subscriber IP Addresses. All IPs are accepted if kept blank.
   • EVENT_NOTIFICATION_SUBSCRIBER_USERNAME– Enter the Subscriber service’s username. ENS sends these credentials as part of the outgoing notification, in the form of a WS-Security Username-Password token.
   • EVENT_NOTIFICATION_SUBSCRIBER_PASSWORD – Enter the password.

b. Registering a Generic Subscriber

Now that the Event Notifications have been enabled, we need to create a subscriber and register it. The subscriber endpoint should be reachable from Rightnow, and in most cases any publicly available endpoint should be good.

For the purpose of this blog I defined a generic subscriber by creating a Node.js based Cloud9 endpoint accessible at https://test2-ashishksingh.c9users.io/api/test . It’s a dummy endpoint that accepts any HTTP POST and prints the body on Cloud9 terminal. It doesn’t require any authentication as well.

In order to register this endpoint, following steps must be followed :

1. Rightnow manages subscriptions by using an object called ‘EventSubscription’. By instantiating this object an ‘endpoint’ can be registered as a subscriber, to listen to an object(Contact/Organization/Incident) for a particular operation(Create/Update/Delete). The object also tracks username/password to be sent out to the endpoint as part of the notification.
2. In order to create an EventSubscription object the usual Connect Web Services Create operation can be used. Below is a sample XML request payload for the Create operation, that registers a Contact Update event to the Cloud9 endpoint.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v1="urn:messages.ws.rightnow.com/v1_3" xmlns:v11="urn:base.ws.rightnow.com/v1_3">
   <soapenv:Body>
      <v1:Create>
         <v1:RNObjects xmlns:ns4="urn:objects.ws.rightnow.com/v1_3" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns4:EventSubscription"> <!--specify the subscription object-->
			<ns4:EndPoint>https://test2-ashishksingh.c9users.io/api/test</ns4:EndPoint> <!--endpoint info-->
			<ns4:EventType>
				<ID id="2" xmlns="urn:base.ws.rightnow.com/v1_3" /> <!--1=Create,2=Update,3=Delete-->
			</ns4:EventType>
			<ns4:IntegrationUser>
				<ID id="1" xmlns="urn:base.ws.rightnow.com/v1_3" /> <!--1 = the seeded SUSCRIBER_USERNAME and PWD above-->
			</ns4:IntegrationUser>
			<ns4:Name>TestContactSubscription</ns4:Name>  <!--Name of the subscription-->
			<ns4:ObjectShape xsi:type="Contact"/>   <!--Name of the object to subscribe-->
			<ns4:Status>
				<ID id="1" xmlns="urn:base.ws.rightnow.com/v1_3" /> <!--1=Active,2=Paused,3=Inactive-->
			</ns4:Status>
         </v1:RNObjects>
      </v1:Create>
   </soapenv:Body>
</soapenv:Envelope>

 
Note : The OWSM security policy username_token_over_ssl_client_policy can be used to invoke the web service, passing valid Rightnow credentials. However, the SOAP Security Header shouldn’t contain a TimeStamp element. Rightnow will discard the requests containing a Timestamp element in the SOAP Header.

3. That’s it. The endpoint is now registered, and whenever a contact is updated, Rightnow will invoke the registered endpoint with details. The message sent out is an XML SOAP message that contains object/event details and conforms to the Rightnow Event WSDL available at https:///cgi-bin/.cfg/services/soap?wsdl=event . This message also contains the SUBSCRIBER_USERNAME/PWD in the SOAP Header, in the form of a WS-Security UsernameToken. For now our Cloud9 endpoint doesn’t care about validating the Username token.
4. In order to test, let’s update a Contact in Agent Desktop
5. Voila! We see the corresponding EventNotification XML message in the Cloud9 console.

For reference I have attached the formatted XML message here.

c. Using ICS Service Cloud Adapter

The Oracle Integration Cloud Service (ICS), the tool of choice for SaaS integrations, automates all of the steps in 1.2 above into a simple GUI based integration definition.
Below are the steps for receiving Rightnow events in ICS. It is assumed that the reader is familiar with ICS and knows how to use it.
Please note that the steps in 1.1 still need to be followed, and this time the SUBSCRIBER_USERNAME/PWD ‘Configuration Setting’ should be the ICS account’s username/password.

1. Create and save an Oracle Rightnow connection in ICS.
2. Create an Integration by the name ‘receive_contacts’. For this blog I chose the ‘Publish to ICS’ integration type.
3. Open the integration and drag the Rightnow connection on the source-side. Name the endpoint and click ‘Next’
4. On the ‘Request’ page select ‘Event Subscription’ , and select the desired event. Click Next.
5. On the ‘Response’ page select ‘None’. Although, you could select a callback response if the use-case required so. Click Next.
6. Click ‘Done’. Complete the rest of the integration and activate it.
7. During activation ICS creates an endpoint and registers it as an EventSubscription object, as described in 1.2 above. But all of that happens in the background, providing a seamless experience to the user.
8. If a Contact is updated in Agent Desktop now, we’d receive it in ICS.

2. Rightnow Custom Process Model

As discussed above, the Event Notification Service supports only Contact, Organization and Incident objects. But sometimes use-cases may require Custom Objects or other Connect Common Objects. In such cases Service Cloud’s Custom Process Model feature can be used for outbound events. I will now describe how to use them.

First, a few key terms:

• Object Event Handler : A PHP code snippet that is executed whenever Create/Update/Delete events occur in the specified Rightnow objects. The snippet is used to invoke external endpoints using the cURL library.
• Process Designer / Custom Process Model (CPM) : A component of the Rightnow Agent Desktop that is used to configure Object Event Handlers.

Below are the steps :

1. Using any text editor, create a file called ContactHandler.php (or any other name) with the following code. The code basically defines a Contact create/update handler, loads the PHP cURL module and invokes a web service I wrote using Oracle BPEL. I have provided explanation at various places in the code as ‘[Note] :’

<?php
/**
 * CPMObjectEventHandler: ContactHandler // [Note] : Name of the file.
 * Package: RN
 * Objects: Contact // [Note] : Name of the object.
 * Actions: Create, Update // [Note] : Name of the operations on the object above for which the PHP code will be executed
 * Version: 1.2 // [Note] : Version of the Rightnow PHP API
 * Purpose: CPM handler for contact create and update. It invokes a web service.
 */
use \RightNow\Connect\v1_2 as RNCPHP;
use \RightNow\CPM\v1 as RNCPM; 
/**
 * [Note] : Below is the main code, defining the handler class for the CPM . Like java, the class name should match the file name, and it implements the ObjectEventHandler class. The 'use' statements above define aliases for the \RightNow\Connect\v1_2 'package' .
 */
class ContactHandler implements RNCPM\ObjectEventHandler
{
    /**
     * Apply CPM logic to object.
     * @param int $runMode
     * @param int $action
     * @param object $contact
     * @param int $cycles
     */
// [Note] : Below is the actual function that gets executed on Contact Create/Update.
    public static function apply($runMode, $action, $contact, $cycle)
    {
        if($cycle !== 0) return ;
		// [Note] : The snippet below declares the URL and the XML Payload to be invoked
            $url = "http://10.245.56.67:10613/soa-infra/services/default/RnContact/bpelprocess1_client_ep?WSDL" ;
            $xml = '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
        <soap:Header>
                <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" mustUnderstand="1">
            <wsse:UsernameToken>
                <wsse:Username>HIDDEN</wsse:Username>
                <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">HIDDEN</wsse:Password>
            </wsse:UsernameToken>
        </wsse:Security>
        </soap:Header>
        <soap:Body>
                <ns1:process xmlns:ns1="http://xmlns.oracle.com/Application6/RnContact/BPELProcess1">
                        <ns1:input>'.$contact->Name->First.' '.$contact->Name->Last .'</ns1:input>
        </ns1:process>
    </soap:Body>
</soap:Envelope>' ;
  

            $header[0]= "Content-Type: text/xml;charset=UTF-8";
            $header[1]= 'SOAPAction: "process"';
			
			// [Note] :The invocation requires and makes use of the cURL module.
            load_curl();
            $curl = curl_init();
            curl_setopt_array($curl,array(
              CURLOPT_URL => $url,            
              CURLOPT_HEADER => 0,
              CURLOPT_HTTPHEADER => $header,  
              CURLOPT_FOLLOWLOCATION => 1, 
              CURLOPT_RETURNTRANSFER => 1,
              CURLOPT_CONNECTTIMEOUT => 20,
              CURLOPT_SSL_VERIFYPEER => 0,
              CURLOPT_SSL_VERIFYHOST => 0,
 
            ));
            curl_setopt($curl,CURLOPT_POST,TRUE);
            curl_setopt($curl,CURLOPT_POSTFIELDS, $xml);
            $content = curl_exec($curl);
    }
}
/**
 * CPM test harness
 */
// [Note] : These are unit test functions, needed by the RN PHP framework.
class ContactHandler_TestHarness
        implements RNCPM\ObjectEventHandler_TestHarness
{
    static $contactOneId = null,
    static $contactTwoId = null;
    /**
     * Set up test cases.
     */
    public static function setup()
    {
        // First test
        $contactOne = new RNCPHP\Contact;
        $contactOne->Name->First = "First";
        $contactOne->save();
        self::$contactOneId = $contactOne->ID;
        // Second test
        $contactTwo = new RNCPHP\Contact;
        $contactTwo->Name->First = "Second";
        $contactTwo->save();
        self::$contactTwoId = $contactTwo->ID;
    }
    /**
     * Return the object that we want to test with. You could also return
     * an array of objects to test more than one variation of an object.
     * @param int $action
     * @param class $object_type
     * @return object | array
     */
    public static function fetchObject($action, $object_type)
    {
        $contactOne = $object_type::fetch(self::$contactOneId);
        $contactTwo = $object_type::fetch(self::$contactTwoId);
        return array($contactOne, $contactTwo);
    }
    /**
     * Validate test cases
     * @param int $action
     * @param object $contact
     * @return bool
     */
    public static function validate($action, $contact)
    {
        echo "Test Passed!!";
        return true;
    }
    /**
     * Destroy every object created by this test. Not necessary since in
     * test mode and nothing is committed, but good practice if only to
     * document the side effects of this test.
     */
    public static function cleanup()
    {
        if (self::$contactOneId)
        {
            $contactOne = RNCPHP\Contact::fetch(self::$contactOneId);
            $contactOne->destroy();
            self::$contactOneId = null;
        }
        if (self::$contactTwoId)
        {
            $contactTwo = RNCPHP\Contact::fetch(self::$contactTwoId);
            $contactTwo->destroy();
            self::$contactTwoId = null;
        }
    }
}
?>

2. Log on to Agent Desktop. Click on Configuration-> Site Configuration-> Process Designer, and click ‘New’.
3. Upload the ContactHandler.php file. Check the ‘Execute Asynchronously’ checkbox, the lib_curl module is available for async CPMs only.
4. Click ‘Save’ on the Home Ribbon , and then click on the ‘Test’ button. On clicking test the ‘validate’ function in the code is executed. Make sure it executes fine, and that the output looks OK.
5. Click OK, followed by clicking ‘Yes’, and then Save again. Now go to the Contact object under OracleServiceCloud, and assign the newly created ContactHandler to the Create and Update events. Then Save again.
6. Now click ‘Deploy’ on the Ribbon to upload and activate all the changes to the RN Server
7. In order to test, create a new contact called ‘John Doe’ in Service Cloud, and the BPEL process gets instantiated.

This ends our discussion on configuring and consuming outbound real-time events. Before moving on to bulk data export, it must be noted that the Rightnow event subscribers and CPMs are inherently transient. Thus, durable subscriptions are not available, although for error scenarios Rightnow does have a retry mechanism with exponential back-off.
If durability is a key requirement then the subscriber must be made highly-available and durability must be built in the subscriber design, such as by persisting messages in a queue immediately upon receiving them.

3. Bulk Export

So far we have discussed various ways of receiving real-time events/notifications from Rightnow. These can be used for online integration scenarios, but not for bulk-export use-cases.
We’ll now discuss a few options for bulk export:

a. ROQL

ROQL, or Rightnow Object Query Language is the simplest tool for extracting data, using SQL-like queries against Rightnow.
ROQL can be executed using Connect Web Services, Connect REST Services, and Connect PHP Services.

ROQL comes in two flavors, Object Query and Tabular Query:

• Object Query : This is when Rightnow Objects are returned as response to the query. This is the simpler form of queries, available in SOAP API as the QueryObjects operation, or in REST API as the ?q= URL parameter.
• Tabular Query : Tabular queries are more advanced queries, which allow operands like ‘ORDER BY’, USE, aggregate functions, max returned items, pagination, etc. These are available in SOAP API as the queryCSV operation, or in REST API as the queryResults resource.

Between the two, Tabular Query is the more efficient way of extracting data, as it returns the required dataset in a single database query. Two great resources to get started on tabular queries are the A-Team blogs here and here. They explain how to use SOAP and REST-based Tabular queries to extract data from Service Cloud and import into Oracle BI Cloud Service.

b. Analytics Report

For more advanced querying needs Rightnow Analytics Reports can be defined in the Agent Desktop, and they can be executed using the SOAP RunAnalyticsReport operation, or REST analyticsReportResults resource.

c. Third Party Providers

A number of third party providers, including the Progress ODBC and JDBC Drivers also allow bulk extract of Rightnow data. These providers internally use the same ROQL based approach, but provide a higher layer of abstraction by automating pagination and other needs.

Conclusion

In this blog we looked at a couple of ways to receive outbound events from Service Cloud, and how ICS can be used to seamlessly receive the events in a UI-driven fashion.
We also saw how PHP-based Rightnow Custom processes can be used as object triggers.
Finally, we saw a few options available for bulk data export from Rightnow, using ROQL, Rightnow Analytics and third-party providers.

All content listed on this page is the property of Oracle Corp. Redistribution not allowed without written permission