Getting Started with the Context Service SDK

Cisco Context Service is a cloud-based omnichannel solution for Cisco Contact Center Express and Contact Center Enterprise. The service provides flexible storage of interaction data across channels, enabling you to capture customer interaction history or the customer's journey.

You can view service status for Context Service and subscribe to updates at https://status.ciscospark.com.

In this document you will learn about the Context Service Components and learn how to:

• Create a New Project
• Register with Context Service
• Connect to Context Service

Context Service Components

The Context Service Java SDK is built with Maven and provides:

• Static SDK jar file—The static or base SDK jar file in your application class path. The Static SDK jar contains all classes and methods used to integrate with Context Service. Your application has a compile-time dependency on this file.
• Dynamic SDK extension jar file—The extension SDK jar file is stored outside the application class path, and is dynamically updated at application runtime.
• connector.property file—Property file specifying the name and location of the extension jar file.
• Context Service SDK POM file—POM file that lists maven dependencies for the SDK.

For more information on the SDK components, see the Context Service SDK Guide.

Create a New Project

This example shows you how to set up the Context Service SDK components and create a new Maven project.

Prerequisites

• The Context Service SDK requires the Java Development Kit (JDK) version 1.8.0_151 or higher. Make sure your system has a JDK (not JRE) that is Java version 1.8.0_151 or higher.
• This guide assumes you are using Maven for build and dependency management. This example assumes you have Maven version 3.3 or higher.

Set-up SDK Components

1. Create a new directory for your project. The directory name should be the same as the name you use as the project ArtifactId. This example uses cs-example as the directory name, the ArtifactId name, and the project name.

2. Download the Context Service SDK and unzip the contents to your project directory. The download contains:

   • context-service-sdk-2.x.x.jar
   • context-service-sdk-pom.xml
   • context-service-sdk-extension-2.x.x.jar
   • connector.property
   • LICENSE.txt
   • README.txt

   Where x is the current version of the SDK.

3. Create a new directory inside your project named plugin. Make sure that the plugin directory is not in your java class path. Move context-service-sdk-extension-2.x.x.jar into the plugin directory. This is the extension jar file that is dynamically updated at application runtime.

Create a New Maven Project

The SDK includes a pom file to help manage its dependencies. This example uses IntelliJ IDEA (Version 14.1) to create a new project based on the Context Service SDK POM file. Though this example uses IntelliJ, you can use any Java IDE that supports Maven projects such as Eclipse.

1. In IntelliJ IDEA, open a new project window by selecting File > New > Project.

2. Select Maven as the project category.

3. In the Project SDK list, select a Java JDK version 1.8.0_151 or higher. Click Next.

4. Enter org as the GroupId and cs-example as the ArtifactId. Click Next.

5. In the Project location field, select your chosen project directory. The Project name field is automatically populated based on your input for ArtifactId. Click Finish.

   A new maven project opens with the cs-example project.

6. In IntelliJ IDEA, select File > Other Settings > Default Settings.

   The Default Preferences window opens.

7. In the Default Preferences window, select Build, Execution, Deployment > Built Tools > Maven > Importing. Check "Import Maven projects automatically".

8. Import the Context Service SDK Jar into your Maven project:

   • Move context-service-sdk-2.x.x.jar and context-service-sdk-pom.xml into src/main/resources.

   • Run the following command in the root of your project directory to load the Context Service SDK and POM into your Maven project. Replace x with the current SDK version:

     mvn install:install-file -Dfile=src/main/resources/context-service-sdk-2.x.x.jar -DgroupId=com.cisco.thunderhead -DartifactId=context-service-sdk -Dversion=2.x.x -Dpackaging=jar -DpomFile=src/main/resources/context-service-sdk-2.x.x-pom.xml

9. Edit your pom.xml file to add dependencies for the static SDK and the base logging system. Replace 2.x.x with your current SDK version. Insert this code after the </version> tag:

   xml

   Copy<dependencies>
    <dependency>
        <groupId>com.cisco.thunderhead</groupId>
        <artifactId>context-service-sdk</artifactId>
        <version>2.x.x</version>
    </dependency>
    <dependency>
        <groupId>commons-logging</groupId>
        <artifactId>commons-logging</artifactId>
        <version>1.2</version>
    </dependency>
   </dependencies>

Include any other Maven dependencies that your application requires after the commons-logging dependency.

Register with Context Service

Before you can connect to Context Service using your application, you must register to obtain a connection data string. The connection data string contains encoded login details that your application uses to authenticate with Context Service.

Prerequisites

• A callback URL.
• A Cisco Webex Control Hub account that is entitled for Context Service.

The callback URL is an address for a hosted service you use to automatically capture the connection data sent from Cisco Webex Control Hub. If you are testing Context Service, you do not need to host a web server at the callback URL. Instead, you can use a URL like https://localhost:7443/productCallback. During the registration process, Context Service prompts you to confirm that you want to be redirected to your callback URL. After the registration process is complete, Context Service redirects your browser to the callback URL with the connection data string appended to it. Copy the connection data string after ?connectiondata= in the URL and and save it in your source code.

Your Cisco Webex Control Hub account must be entitled for Context Service. See your account representative for details on obtaining the entitlement.

This example shows how to generate a Registration URL as well as how to register an application and obtain connection data:

1. In the IntelliJ Project Tool Window, right-click on src/main/java and select New > Java Class. Name the new class Register.

2. In Register.java, enter:

   java

   Copyimport com.cisco.thunderhead.connector.RegisteringApplication;
   import com.cisco.thunderhead.plugin.ConnectorFactory;
   
   public class Register {
   
        public static void main(String args[]) {
   
            RegisteringApplication registerApp = ConnectorFactory.getConnector(RegisteringApplication.class);
            try {
                String productCallbackUrl = "https://localhost:7443/productCallback";
                String APPLICATION_TYPE = "custom";
                String registrationURL = registerApp.createRegistrationRequest(productCallbackUrl, APPLICATION_TYPE);
                System.out.println("\n\n*** Generated Registration URL. Open Registration URL: " + registrationURL);
             }
             catch (Exception e) {
                System.out.println("Error generating Registration URL! The Error is: " + e);
             }
         }
     }

Set the productCallbackUrl as your chosen callback URL. If you are testing Context Service, you can use the dummy URL example of https://localhost:7443/productCallback as your Callback URL.

Set the APPLICATION_TYPE as your assigned application type. Use custom if you don't have an assigned application type.

3. Select Run > Run....

4. Select Register from the run dialog. The Register class runs. Take the registration URL from the output in the IntelliJ Run Tool Window and open it in a browser.

5. When prompted, confirm that you want Context Service to redirect you to your callback URL.

6. Sign into Cisco Webex Control Hub. Click Allow to allow your application to access Context Service.

Context Service redirects your browser to your callback URL with the connection data string appended to it.

7. Copy the connection data string after ?connectiondata= in the URL. Save the connection data string in your source code and use it for all connections to Context Service.

Connect to Context Service

To connect to Context Service, create a new connection class in your project. This example code shows you the minimum required parameters to create a new connection class. Make two connections:

• Management Connection—The management connection provides Cisco Collaboration Management services details about your client connection and keeps the connection to the service alive while your application runs. It periodically (and automatically) refreshes authentication tokens so that the connection stays alive.

• Client Connection—The client connection allows you to interact with Context Service to create and update Context Service data objects (Activities, Customers, and Requests).

1. In the IntelliJ Project Tool Window, right-click on src/main/java and select New > Java Class. Name the new class Connect.

2. In Connect.java, enter:

   java

   Copyimport com.cisco.thunderhead.connector.ManagementConnector;
   import com.cisco.thunderhead.connector.info.ConnectorInfoImpl;
   import com.cisco.thunderhead.client.ContextServiceClient;
   import com.cisco.thunderhead.errors.ApiException;
   import com.cisco.thunderhead.plugin.ConnectorFactory;
   
   public class Connect {
   
        public static final String CONNECTIONDATA = "Your_Connection_Data";
   
        public static void main(String args[]) {
   
            String configFilePath = "connector.property";
            try {
                ConnectorFactory.initializeFactory(configFilePath);
            }
            catch(Exception e) {
                System.out.println("Error Initializing Factory! The Error is: " + e);
            }
   
            final String hostname = "myhost.example.com";
   
            // Initialize Management Connector
            ManagementConnector mgmtConnector = ConnectorFactory.getConnector(ManagementConnector.class);
            ConnectorInfoImpl connInfo = new ConnectorInfoImpl(hostname);
            try {
                mgmtConnector.init(CONNECTIONDATA, connInfo);
                System.out.println("\n\n*** Management Connector Connected ***\n\n");
            }
            catch(ApiException e) {
                System.out.println("Error! Could not init management connector: " + e);
            }
   
            // Initialize Client Connection
            ContextServiceClient contextServiceClient = ConnectorFactory.getConnector(ContextServiceClient.class);
            try {
                contextServiceClient.init(CONNECTIONDATA, connInfo);
                System.out.println("\n\n*** Client Connector Connected ***\n\n");
            }
            catch (ApiException e) {
                System.out.println("Error! Could not init client connector: " + e);
            }
   
            // Do some things with Context Service...
   
            // Close Connections
            mgmtConnector.destroy();
            contextServiceClient.destroy();
            System.out.println("\n\n*** Finished ***\n\n");
        }
   }

   Replace Your_Connection_Data with the connectionData string you obtained from registering your application.

3. Select Run > Run… and then select Connect from the run dialog. View the output in the IntelliJ Run Tool Window.

See the Context Service SDK Guide for more information on the classes and methods available in the Context Service SDK.