Customer Context Gadget Control Library

The Customer Context Gadget Control library allows custom applications and third-party gadgets in Cisco Finesse to display activities in the Finesse Customer Context gadget.

Activities in Context Service represent different customer interactions. For example, an activity could be a customer chat or an email.

The Gadget Control library works by sending messages using the Cisco Finesse OpenAjax Hub that control the Customer Context gadget. As a result, the Gadget Control library uses your Cisco Finesse authentication information and does not require any additional authentication to use.

You can use the Customer Context Gadget Control library to:

• Search Context Service for an activity by using podId. If an activity is found, the activity is added to the Customer Context gadget and displayed as the current activity.

• Search Context Service for an activity by using specific activity data. If an activity is found, the activity is added to the Customer Context gadget and displayed as the current activity.

What is the Customer Context Gadget?

The Customer Context gadget uses Context Service to display the customer journey in Cisco Finesse. Agents use the Customer Context gadget to update customer information, add request and activity details, and move activities to different customers or different requests. The Customer Context gadget is available in the Manage Customers tab of the default Cisco Finesse agent desktop layout. For more information on the Customer Context gadget, see the Customer Context gadget documentation.

When a customer interaction occurs in a registered Cisco Customer Collaboration product, the activity data is automatically stored in Context Service and displayed by the Cisco Finesse Customer Context gadget. This includes customer interactions in:

• Cisco Finesse
• Cisco SocialMiner
• Cisco Enterprise Chat and Email
• Cisco Unified Customer Voice Portal
• Unified CCX Engine Service

If the activity is associated with a customer, the Customer Context gadget automatically displays the available customer information.

You can also configure custom applications or third-party Cisco Finesse gadgets to automatically create an activity in Context Service when a customer interaction occurs. For more information on registering an application with Context Service and creating activities, see Registering your Application with Context Service and Create Context Service Objects in the Context Service SDK Guide. After you have configured your custom application or third-party Cisco Finesse gadget to create activities, you can use the Context Service Gadget Control library to display the activities in the Customer Context gadget.

Example Customer Context Gadget Control Library Workflow

1. A customer named Michael Littlefoot sends an email asking for "Help with a faulty motorcycle battery".
2. Your third-party Finesse gadget creates a new activity in Context Service for this customer interaction.
3. The Customer Context Gadget Control library searches for the activity using podId (podId is the activity identifier).
4. The Customer Context gadget automatically displays this new activity.
5. If the activity is associated with a customer record, the Customer Context gadget displays the available customer information. This includes information captured by UCCE components, UCCX components, and any custom applications configured for Context Service. The customer is displayed as an unknown customer if the activity is not associated with a customer record.

Prerequisites for using the Customer Context Gadget Control Library

Before you can use the Context Service Gadget Control library, you must:

1. Register your organization with Context Service. For more information, see the Enable Context Service chapter of either the Unified Contact Center Enterprise Features Guide or the Unified Contact Center Express Features Guide.

2. Register and configure your Unified CCE or Unified CCX components with Context Service. For more information, see the Component Configuration and Registration chapter of either the Unified Contact Center Enterprise Features Guide or the Unified Contact Center Express Features Guide.

3. Configure your application or third-party gadget to automatically create an activity in Context Service when a customer interaction occurs. For more information on registering an application with Context Service and creating activities, see Registering your Application with Context Service and Create Context Service Objects in the Context Service SDK Guide.

Import the Customer Context Gadget Control Library

In order to use the Customer Context Gadget Control library, import it into your application or third-party gadget using one of the following methods:

• Include as a script element
• Include using dynamic script loading
• Include using an AMD library

If you use a downloaded version of the library, you may not have the latest supported version. Include the library using one of the above methods to ensure that you are using the latest version of the library.

Include the Library as a Script Element

1. Configure your gadget's content-rewrite feature to exclude contextgadget.ciscoccservice.com. In your gadget's ModulePrefs node, enter:

   Code Snippet

   Copy<Optional feature="content-rewrite”> <Param name="exclude-url">contextgadget.ciscoccservice.com</Param> </Optional>

2. Include the library as a script element in your gadget's HTML:

   HTML

   Copy<script src="https://contextgadget.ciscoccservice.com/control/ContextServiceGadgetControl.js"></script>

After you include the library as a script element, the library is available globally as window.ContextService.GadgetControl.

Include the Library Using Dynamic Script Loading

Use dynamic script loading to load the Gadget Control library into the DOM dynamically.

1. Include the library as a dynamic script in your gadget's HTML:

   HTML

   Copy<script type="application/javascript"> var el = document.createElement("script"); el.type = "application/javascript"; el.src = "https://contextgadget.ciscoccservice.com/control/ContextServiceGadgetControl.js"; document.body.appendChild(el); </script>

After you include the library using dynamic script loading, the library is available globally as window.ContextService.GadgetControl.

Include the Library using an AMD Library

You can include the Gadget Control library in your application by using an Asynchronous Module Definition (AMD) library. This JavaScript example shows how to include the Gadget Control library using requireJS and how to search for an activity using podId:

Copy  require(['https://contextgadget.ciscoccservice.com/control/ContextServiceGadgetControl.js'], function (GadgetControl) { GadgetControl.showPodById('12345'); });

After you include the Gadget Control library by using an AMD library, the Gadget Control library is available globally as window.ContextService.GadgetControl.

Customer Context Gadget Control Library Methods

showPodById

Use the showPodById static method to display an activity in the Customer Context gadget that matches the specified podId query.

Ensure that all applications using Context Service in your organization are using the same mode. If your application is in Production mode, it cannot search or access data created in Lab mode. If your application is in Lab mode, it cannot search or access data created in Production mode. For more information on setting the Context Service mode, see Connect to Context Service in the Context Service SDK Guide.

Usage

GadgetControl.showPodById('podId')

Inputs:

Successful Query Output:

The Customer Context Gadget Control library does not return a value with a successful query.

• If there is an activity that satisfies the query parameters, the Customer Context gadget displays the found activity as the current activity.
• If no activities or multiple activities satisfy the query parameters, the Customer Context gadget does not display anything.

Query Errors:

• If there is a failed network request, the method throws Gadget hub is not connected as a string. The browser console displays the error.
• If there is no podId value provided, the method throws Must provide Pod ID as a string. The browser console displays the error.

This JavaScript example shows how to display an activity using podId:

CopyGadgetControl.showPodById('589c5697-fe4c-4fbf-9a12-1919a60dfb13');

showPodByQuery

Use the showPodbyQuery static method to display an activity in the Customer Context gadget matching the specified query.

Ensure that all applications using Context Service in your organization are using the same mode. If your application is in Production mode, it cannot search or access data created in Lab mode. If your application is in Lab mode, it cannot search or access data created in Production mode. For more information on setting the Context Service mode, see Connect to Context Service in the Context Service SDK Guide.

Usage

GadgetControl.showPodByQuery(parameters, operation)

Inputs:

Possible search parameters include:

• The activity object properties.
• Any of the Context Service base fields.
• Any custom fields created for your organization.

Successful Query Output:

The Customer Context Gadget Control library does not return a value with a successful query.

• If there is an activity that satisfies the query parameters, the Customer Context gadget displays the found activity as the current activity.
• If no activities or multiple activities satisfy the query parameters, the Customer Context gadget does not display anything.

Query Errors:

• If there is a failed network request, the method throws Gadget hub is not connected as a string. The browser console displays the error.
• If there are no search parameters provided, the method throws Must provide query parameters as a string. The browser console displays the error.

This JavaScript example shows how to search for and display an activity that contains the specified customerId AND the specified POD activity link:

Copyconst params = {
  customerId: "ed526094-368d-42fe-a587-8d17475b16f4",
  Context_POD_Activity_Link: "http://example.com/1234"
};

const operation = GadgetControl.SEARCH_OPERATIONS.AND;

GadgetControl.showPodByQuery(params, operation);

This JavaScript example shows how to search for and display an activity that contains the specified source email OR the specified source phone:

Copyconst params = {
  Context_POD_Source_Email: "myname@email.com",
  Context_POD_Source_Phone: "555-555-5555"
};

const operation = GadgetControl.SEARCH_OPERATIONS.OR;

GadgetControl.showPodByQuery(params, operation);