WhatsApp Integration with OSvC

One of the biggest and most exciting announcements made by Oracle in the Modern Service Experience event in Las Vegas last week, was the development of an integration with the leading messaging apps in the market – WhatsApp, WeChat and Facebook Messenger.

In the meantime, Customer Interactions Group – an Oracle partner based in the Netherlands – created the integration between OSvC and WhatsApp, certainly using the Chat API.

P.S. – The integration with WhatsApp can only be productised when there is a public API available, which is still not the case today.

CXDev Toolbox, by CXDeveloper

Some of you may have already noticed that one of the websites I have in the list of links is the CXDeveloper. This is a website where a couple of Oracle Service Cloud specialists (namely Andy Rowse and Ben Johns) share their extensive knowledge and experience on how to customise and extend Oracle Service Cloud.

They not only give some excellent advice and tips, but also provide to the Oracle Service Cloud community the CXDev Toolbox, an “extensible platform for tools and utilities that support the management, maintenance and development of an Oracle RightNow CX site”.

This toolbox connects to the Oracle Service Cloud environment and allows…

Single and multiple Account Import
Single and multiple Account Unlock
ROQL Testing
PHP Stub Generation

Andy and Ben are kind and generous enough to allow everyone to use these for free, and in the future they promise to offer more functionality, like…

PTA Testing
Object Cleaning
Contact Merging
CBO Copying
Meta Comparison

I would recommend all Oracle Service Cloud admins, developers and consultants to download the CXDev Toolbox as it may be very useful.

Google Maps for Organisations

A few weeks ago, in this post, I explained how to embed Google Maps on RightNow CX, in order to quickly see the Contacts’s address using the information in the RightNow database.

Some of you asked if this was possible to do with Organisations. The answer was: unfortunately it is not as straight forward as with Contact, and there is two reasons for that:

a) The Address field in Organisation – “Oaddr” – is different than that in the Contact. It is a collection of addresses that has two types: Billing and Shipping. These are controlled by objects “Organization Addresses” and “Organization Address Types”.

b) Address values in Organisation are not available to get directly. “Oaddr” is expressed as string XML data of the following form:

<Addr Street=”123 main st” City=”Bozeman” ProvId=”23″ PostalCode=”59718″ CountryId=”1″ />.

The suggestion to get this done was to use a Desktop Integration with RightNow Connect JavaScript API in 4 stages:

Get and parse the Organisation address
Retrieve the values (Street, City, Province, Postal Code, Country)
Build a Google Maps URL with the values
Navigate to Google Maps using “window.location”

The solution is then:

Step 1: Create an HTML file with the JavaSCript code to build the Google Maps URL

function getAddress()
{
var selection=document.getElementById(‘address_type’).value;
//0 for billing addr and 1 for shipping addr
var address = window.external.Org.OAddresses;
var org=window.external.Org;
var provinceName;
var countryName;

//Parsing the XML into object
var xmlDoc = new ActiveXObject(“Microsoft.XMLDOM”);
xmlDoc.async = “false”;
xmlDoc.loadXML(address);

//Retrieving all the fields of selected Organisation Address
var desiredAddress=xmlDoc.getElementsByTagName(“OAddresses”)[0];

var street=desiredAddress.getElementsByTagName(“Addr”)[selection].getAttribute(“Street”);
var city=desiredAddress.getElementsByTagName(“Addr”)[selection].getAttribute(“City”);
var provId=desiredAddress.getElementsByTagName(“Addr”)[selection].getAttribute(“ProvId”);

var postalCode=desiredAddress.getElementsByTagName(“Addr”)[selection].getAttribute(“PostalCode”);
var countryId=desiredAddress.getElementsByTagName(“Addr”)[selection].getAttribute(“CountryId”);

//Fetching Province Name corresponding to provinceID retrieved
var provLabels = org.GetNameValues(“ProvId”);
xmlDoc.loadXML(provLabels);
var x=xmlDoc.getElementsByTagName(“Item”);
for (i = 0; i < x.length; i++)
{
var provAttlist=x.item(i).attributes;
var provAtt=provAttlist.getNamedItem(“Id”);
if (provAtt.value==provId)
{
provinceName= provAttlist.getNamedItem(“Name”).value;
}
}

//Fetching Country Name corresponding to countryId retrieved
var countryLabels = org.GetNameValues(“CountryId”);
xmlDoc.loadXML(countryLabels);
var y=xmlDoc.getElementsByTagName(“Item”);
for (i = 0; i < y.length; i++)
{
var countAttlist=y.item(i).attributes;
var countAtt=countAttlist.getNamedItem(“Id”);
if (countAtt.value==countryId)
{
countryName= countAttlist.getNamedItem(“Name”).value;
}
}

//Building the google maps URL
var finalAddress=street+” “+city+” “+postalCode+” “+ provinceName+” “+countryName;
window.location=”http://maps.google.co.in/maps?hl=en&q=”+finalAddress;
}

function ondataupdated(obj)
{
getAddress();
}

</script>
</head>
<body onload=getAddress()>
</body>
</html>

Step 2: Upload the HTML file to a server via FTP (I normally use FileZilla).

Step 3: Add a new tab to the Organisations Workspace and drag and drop a browser control into the tab

Step 5: Select the browser control, go to the Design tab > Options section, and put the URL path of the HTML file into the URL field.

Step 6: Select the browser control, go to the Design tab > Options section, and un-check the Delay Page Load check box.

Now, whenever you open an Organisation, and navigate to the “Map” tab, you will automatically see the Organisations’s address on the map.

Thank you to Bhagwan Singh Mer (Lead Consultant at Wipro Technologies) and Jens Lundell (Oracle RightNow Workflow Development Manager) for their help on this requirement. Special thank you to Saurabh Gupta (Consultant at Wipro Technologies) as it was him that scripted the JavaScript code.

Outlook Smart Tags for Incident Reference #

Besides synchronizing contacts, tasks, and email between Outlook and Oracle RightNow CX, you can also implement a Microsoft smart tag in Outlook to open incidents directly from an email.

Staff members who are using Outlook 2007 must enable smart tags through Tools > Options > Mail Format > Editor Options > Proofing > AutoCorrect Options > Smart Tags.

Outlook recognizes certain types of data in your email, such as an address, and lets you perform actions on that data. In addition, Oracle RightNow CX lets you install a smart tag that recognizes incident reference numbers contained in email messages. When you right-click the reference number in an email message, the incident automatically opens in RightNow CX.

To install RightNow CX SmartTag:

1. Close Outlook.

2. In RightNow CX, click the CX button and select Links > Install Incident Reference Number Smart Tag. The SmartTag Setup Wizard opens.

3. Click the Next button to open the Select Installation Folder window.

4. To install SmartTag in a different location, click the Browse button, select the folder where you want to install SmartTag, and click the OK button.

5. To see a list of the drives where SmartTag can be installed, click the Disk Cost button. Click the OK button when you are finished.

6. Click the Next button to open the Confirm Installation window.

7. Click the Next button to begin the installation. After the installation is complete, the Installation Complete window opens.

8. Click the Close button to complete the installation.

To open an incident using RightNow CX SmartTag in Outlook:

1. Hover over the incident number smart tag in the email message. The smart tag indicator appears.

2. Click the smart tag indicator and select Open Incident within CX Console.

Note: If you are using Outlook 2010, you must right-click the reference number and select Additional Actions to view smart tag options

If the CX Console is already open, the incident opens. If the CX Console is not open when you select Open Incident, you must log in to Oracle RightNow CX for the incident to open.

Important Note 1: After the RightNow up-grade IT faces huge issue with the installation of the new version of outlook integration: Outlook Integration MSI Data cannot be installed centrally and the IT needs to do it locally, on every User Stations. Therefore it takes some time before all users gain installed the Outlook Integration and meantime the Outlook sync is not available on user’s stations.

Important Note 2: Prevent users from creating contacts via Outlook Sync using profile permissions: Even though the profile only has Read permissions for Contacts using the outlook sync facility allows them to create contacts.

Configuring Outlook Integration

Microsoft Outlook can be integrated with Oracle RightNow CX Cloud Service, enabling you to share your contacts and tasks and synchronize your email. Using Outlook integration, your data will be more complete and up-to-date, and you’ll no longer need to switch back and forth between applications. You can also create contacts and incidents when syncing Outlook email with Oracle RightNow CX.

Outlook integration is comprised of the following components.

Contact synchronization: Enter contact information one time, in either Oracle RightNow CX or Outlook, and have that information shared in both applications.
Task synchronization: Enter task information one time in either application and have that information shared in both applications.
Email integration: Append Outlook email, including attachments, to existing contacts, organizations, opportunities, and incidents in Oracle RightNow CX.

The following actions must be taken to use Outlook integration.

Step 0: Enable Outlook integration on your site: Contact your Oracle account manager.
Step 1: Add or update profiles to include Outlook integration permission.
Step 2: Install Outlook integration software on agent workstations.

Step 1: Adding Outlook integration permissions to profiles

You can be assigned full Outlook integration permissions (contact and task synchronization, email integration) or any combination of the three permissions.

To add Outlook integration permissions to a profile:

1. Click the Configuration button on the navigation pane and double-click Profiles under Staff Management.

2. Open the profile you want to edit.

3. Click the Permissions button on the ribbon and then the Outlook Integration tab.

4. To allow staff members to append Outlook email to contacts, organizations, opportunities, and incidents in RightNow, select the Email Integration check box.

5. To allow staff members to share contacts between Outlook and RightNow, select one or more of the Contact Synchronization check boxes.

To share contacts that are in the Opportunities state, select the Opportunities Contacts check box.
To share contacts that are in the Service state, select the Service Contacts check box.
To share Outlook contacts with RightNow, select the Outlook to Server check box.
To share RightNow contacts with Outlook, select the Server to Outlook check box.

6. To allow staff members to share tasks between Outlook and RightNow, select one or both of the Task Synchronization check boxes.

To share Outlook tasks with RightNow CX, select the Outlook to Server check box.
To share RightNow CX tasks with Outlook, select the Server to Outlook check box.

7. To select different email synchronization reports for determining the contacts, opportunities, and incidents to return during email synchronizations, click the Search button to the right of the report you want to change. The Select Report window opens and the Outlook Integration folder expands by default.

Step 2: Install Outlook integration software

After Outlook integration has been enabled and you have been assigned the correct profile permissions, you must install the necessary components on your workstation. When you install Outlook integration, RightNow CX checks your profile to see which components (email, contact, and task) you have permission to share and synchronize. The installation process adds Share and Sync buttons to your Outlook toolbar.

To install Outlook integration:

1. Close Outlook.

2. From RightNow CX, click the CX button and select Links > Install Outlook Integration. The RightNow Outlook Sync Setup wizard opens.

3. Click the Next button to open the Select Installation Folder window. (It is recommended that you install Outlook integration at the default location of C:\Program Files\Oracle RightNow Outlook Sync).

4. To install Outlook integration in a different location, click the Browse button, select the folder where you want to install Outlook integration, and click the OK button.

5. To see a list of the drives where Outlook integration can be installed, click the Disk Cost button. Click the OK button when you are finished.

6. If you are the only staff member who uses your workstation, select the Just Me radio button.

7. If other staff members have accounts on your workstation and must also use Outlook integration, select the Everyone radio button.

8. Click the Next button to open the Confirm Installation window.

9. Click the Next button to begin the installation. After the installation is complete, the Installation Complete window opens.

10. Click the Close button to complete the installation.

With the proper components installed, you’ll want to review and possibly customize your sync options before using Outlook integration.

Important Note: RightNow currently does not support integration with Microsoft Outlook 2010 64-bit. You can use Outlook 2003, 2007 and 2010 32 bit. 64-bit is NOT supported.

Calculated field using JavaScript API

I have created a “Date of Birth” Custom Field (Type: Date) on the Contact object, and my requirement was to create a field that would display the Age of the Contact, based on the “Date of Birth” field.

For that I used the Connect Desktop Integration (JavaScript API), and did the following:

Step 1: Create a Custom Field (Type: Integer) in the Contact object with the name “Age”, and add the field to the Contact workspace.

Step 2: Create an HTML file with code to calculate the Age and set the “Age” field.

<html>
<head>
<script type=“text/javascript”>
function SetAge()
{
var dobInt = window.external.Contact.GetCustomFieldByName(“c$date_of_birth”);
if (dobInt == –1)
{
var textna = “N/A”;
window.external.Contact.SetCustomFieldByName(“c$age”, textna);
return;
}
var dob = new Date(dobInt * 1000);
var now = new Date();
var yearAge = now.getFullYear() – dob.getFullYear();
var monthNow = now.getMonth() + 1;
var monthDob = dob.getMonth() + 1;
if (monthNow < monthDob || (monthNow == monthDob && now.getDate() < dob.getDate()))
yearAge–;
window.external.Contact.SetCustomFieldByName(“c$age”, yearAge);
}
function ondataupdated(obj)
{
SetAge();
}
</script>
</head>
<body onload=SetAge()>
</body>
</html>

Step 3: Upload the HTML file to a server via FTP and take the URL.

Step 4: Add a new tab to the Contact Workspace and drag and drop a browser control into the tab

Step 5: Select the browser control, go to the Design tab > Options section, and put the URL of the HTML file into the URL field.

Step 6: Select the new tab, go to the Design tab > Behavior section, click the Hidden button and make the tab hidden “On New” and “On Open“.

Step 7: Select the browser control, go to the Design tab > Options section, and un-check the Delay Page Load check box.

Now, whenever you open a contact that has “Date of Birth” populated, the script will calculate the Age and set the “Age” Custom Field with the right value.

You might also want to make the “Age” field read only so that its value is only set by the script and not by the user.

Important Note: The date fields only allow to go back to 1970, which in this case of Date of Birth is a bit limited.

Thank you to Jens Lundell (Oracle RightNow Workflow Development Manager) for his help on this requirement and to Mark Kehoe (Independent Oracle RightNow Consultant) for raising the date limitation issue.

Connect Web Services for SOAP: Create a Contact

After retrieving the WSDL and be aware of the API Operations you are ready to get, create, update and delete RightNow records through Web Services.

In this post an example will be presented on how to create a Contact. On the documentation available (Connect Web Services for SOAP) we can see the sample code and then adapt to our case.

To create a Contact we shall use the “Create” API Operation. The request message shall have:

An Envelope;
A Header;
A Body;

Envelope

<soapenv:Envelope xmlns:soapenv=“http://schemas.xmlsoap.org/soap/envelope/” xmlns:v1=“urn:messages.ws.rightnow.com/v1_2” xmlns:v11=“urn:base.ws.rightnow.com/v1_2”>
[Include here the Header and the Body]
</soapenv:Envelope>

Header

Notice the AppID tag with the Operation name “Basic Create”

<soapenv:Header>
<ns7:ClientInfoHeader xmlns:ns7=“urn:messages.ws.rightnow.com/v1_2” soapenv:mustUnderstand=“0”>
<ns7:AppID>Basic Create</ns7:AppID>
</ns7:ClientInfoHeader>
<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>Username</wsse:Username>
<wsse:Password Type=“http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText”>Password</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>

Body

Notice the Create tag and the RNObjects tag with the xsi:type = “Contact”

<soapenv:Body>
— <ns7:Create xmlns:ns7=“urn:messages.ws.rightnow.com/v1_2”>
——<ns7:RNObjects xmlns:ns4=“urn:objects.ws.rightnow.com/v1_2” xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance” xsi:type=“ns4:Contact”>
———<ns4:Emails>
————<ns4:EmailList action=“add”>
—————<ns4:Address>example.email@rightnow.com</ns4:Address>
—————<ns4:AddressType>
——————<ID xmlns=“urn:base.ws.rightnow.com/v1_2” id=“0” />
—————</ns4:AddressType>
————</ns4:EmailList>
———</ns4:Emails>
———<ns4:Name>
————<ns4:First>FirstName</ns4:First>
————<ns4:Last>LastName</ns4:Last>
———</ns4:Name>
——</ns7:RNObjects>
—</ns7:Create>
</soapenv:Body>

Connect Web Services for SOAP: API Operations

Operations represent specific calls invoked to perform specific tasks on the RightNow CX platform. Connect Web Services defines a number of operations which either accept or return one or more instances of RNObject.

CRUD – Create, Read, Update and Destroy

CRUD operations allow for the creation, reading, updating and deleting of objects contained in the RightNow CX system.

Return values:

Create and Get (Read) operations return a list containing 1 to N RNObjects.
Update and Destroy operations do not return a value upon success.
If a CRUD operation fails, a SOAP fault is returned.

API Operations

Listed bellow are the supported operations in Connect Web Services (that are included in the WSDL).

Batch: Sends a set of operations to the server in a single request.
ConvertGenericToObject: Converts a generic object to a typed object.
ConvertObjectToGeneric: Converts a typed object to a generic object.
Create: Creates one or more instances of objects which inherit from RNObject.
Destroy: Destroys one or more instances of objects which inherit from RNObject.
ExecuteMarketingFlow: Initiates a marketing campaign flow.
Get: Reads one ore more instances of objects which inherit from RNObject.
GetFileData: Obtains the binary data for a file attachment.
GetMetaData: Obtains all meta-data information for all classes.
GetMetaDataForClass: Obtains meta-data information for the specified class.
GetMetaDataLastChangeTime: Obtains the date and time of the last change to the meta-data.
GetValuesForNamedID: Obtains a list of ID-Name pairs for a specific NamedID field.
GetValuesForNamedIDHierarchy: Obtains a list of ID-Name pairs for a specific NamedIDHierarchy field.
QueryCSV: Processes a ROQL query string and returns data in a CSV result.
QueryObjects: Processes a ROQL query string and returns one or more objects.
ResetContactPassword: Invalidates a contacts password and emails a link to the contact that can be used to reset the password.
RunAnalyticsReport: Executes a RightNow Analytics report reurnning the data in a CSV result.
SendMailingToContact: Sends a transactional mailing to a contact.
Update: Updates one or more instance of objects which inherit from RNObject.

Connect Web Services for SOAP: WSDL Retrieval

Connect Web Services for SOAP is an open and standards-based integration API enabling developers to build integration solutions with RightNow CX that leverage industry leading standards such as WSDL 1.1 and SOAP 1.1.

Connect Web Services for SOAP is RightNow’s leading data integration API, providing broad out-of-the-box tooling support for a wide variety of languages, platforms, and tools.

Connect Web Services should be used to extend the functionality offered by RightNow CX and the ability to access data stored in the RightNow CX platform.

WSDL Retrieval

There are two WSDL files that provide access to Connect Web Services:

Standard WSDL – This WSDL should be used by application developers building integrations specific to their Oracle RightNow CX instance. The typed WSDL is a strongly typed representation of the Connect Common Object Model. The strongly typed WSDL can be accessed from the following URL:

http://<host_name>/cgi-bin/<interface>.cfg/services/soap?wsdl=typed

Partner WSDL – This WSDL should be used by application developers building integrations that function across multiple instances of Oracle RightNow CX. It provides the ability to work with Generic Objects that can be used across multiple instances of Oracle RightNow CX. The generic WSDL can be accessed from the following URL:

http://<host_name>/cgi-bin/<interface>.cfg/services/soap?wsdl=generic

(e.g. host name: interfacename.rightnowdemo.com)
(e.g. interface: interfacename)