Americas Headquarters
Cisco Systems, Inc.
170 West Tasman Drive
San Jose, CA 95134-1706
USA
https://www.cisco.com
Tel: 408 526-4000
800 553-NETS (6387)
Fax: 408 527-0883
Enterprise Chat and Email Administrator’s
Guide to Data Adapters, Release 12.5(1)
For Unified Contact Center Enterprise
First Published: January, 2020
THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL
STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT
WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.
THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT
SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE
OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.
The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB's public
domain version of the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.
NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED “AS IS" WITH
ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT
LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF
DEALING, USAGE, OR TRADE PRACTICE. IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL,
OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR
INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display
output, network topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in
illustrative content is unintentional and coincidental.
Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this
URL: https://www.cisco.com/go/trademarks. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a
partnership relationship between Cisco and any other company. (1110R)
Enterprise Chat and Email Administrator’s Guide to Data Adapters: For Unified Contact Center Enterprise. January 7, 2020
© 2016-2020 Cisco Systems, Inc. All rights reserved.
Contents
Preface .................................................................................................................................................5
About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Communications, Services, and Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Cisco Bug Search Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Field Alerts and Field Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Document Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Chapter 1: Data Adapters Basics....................................................................................................8
Do You Need Data Adapters?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
How Do Data Adapters Work? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Where and How Can You Use Data Adapters? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Workflows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Advisor Desktop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Elements of the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Chapter 2: Authentication for Data Adapters ..............................................................................12
Configuring Basic Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Configuring OAuth 2.0 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Deleting Authentication Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Chapter 3: Data Access Links ........................................................................................................16
About Data Access Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Creating Web Service - RESTful Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Editing JDBC Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Testing Access Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4 Enterprise Chat and Email Administrator’s Guide to Data Adapters
Deleting Access Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Chapter 4: Data Usage Links ..........................................................................................................23
About Data Usage Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Creating Usage Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Creating Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Configuring Display of Results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Assigning Permissions for Usage Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Testing Usage Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Deleting Usage Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Chapter 5: Data Usage Link Groups ..............................................................................................29
About Usage Link Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Creating Usage Link Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Configuring the Display of Results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Assigning Permissions for Usage Link Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Deleting Usage Link Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Chapter 6: Sample Data Access Links..........................................................................................33
Example One – Get Weather Information for a City . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Example Two – Extract Stock Information From a Website . . . . . . . . . . . . . . . . . . . . . . 35
Configure Basic Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Create the Access Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Example Three – Shorten URLs Using Google API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Configure OAuth 2.0 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Create the Access Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
6 Enterprise Chat and Email Administrator’s Guide to Data Adapters
Welcome to the Enterprise Chat and Email (ECE) feature, which provides multichannel interaction software
used by businesses all over the world as a core component to the Unified Contact Center Enterprise product line.
ECE offers a unified suite of the industry’s best applications for chat and email interaction management to
enable a blended agent for handling of web chat, email and voice interactions.
About This Guide
Enterprise Chat and Email Administrator’s Guide to Data Adapters introduces the Data Adapters and shows
how to set up data links to connect to external sources.
Related Documents
The latest versions of all Cisco documentation can be found online at https://www.cisco.com
Communications, Services, and Additional
Information
To receive timely, relevant information from Cisco, sign up at Cisco Profile Manager.
To get the business impact you’re looking for with the technologies that matter, visit Cisco Services.
To submit a service request, visit Cisco Support.
To discover and browse secure, validated enterprise-class apps, products, solutions and services, visit Cisco
Marketplace.
To obtain general networking, training, and certification titles, visit Cisco Press.
To find warranty information for a specific product or product family, access Cisco Warranty Finder.
Cisco Bug Search Tool
Cisco Bug Search Tool (BST) is a web-based tool that acts as a gateway to the Cisco bug tracking system that
maintains a comprehensive list of defects and vulnerabilities in Cisco products and software. BST provides you
with detailed defect information about your products and software.
Subject Link
Complete documentation for Enterprise
Chat and Email, for both Cisco Unified
Contact Center Enterprise (UCCE) and Cisco
Packaged Contact Center Enterprise (PCCE)
https://www.cisco.com/c/en/us/support/customer-collaboration/cisco-
enterprise-chat-email/tsd-products-support-series-home.html
Field Alerts and Field Notices 7
Field Alerts and Field Notices
Cisco products may be modified or key processes may be determined to be important. These are announced
through use of the Cisco Field Alerts and Cisco Field Notices. You can register to receive Field Alerts and Field
Notices through the Product Alert Tool on Cisco.com. This tool enables you to create a profile to receive
announcements by selecting all products of interest.
Log into www.cisco.com and then access the tool at https://www.cisco.com/cisco/support/notifications.html
Documentation Feedback
To provide comments about this document, send an email message to the following address:
We appreciate your comments.
Document Conventions
This guide uses the following typographical conventions.
.
Document conventions
Convention Indicates
Italic Emphasis.
Or the title of a published document.
Bold Labels of items on the user interface, such as buttons, boxes, and lists.
Or text that must be typed by the user.
Monospace
The name of a file or folder, a database table column or value, or a command.
Variable User-specific text; varies from one user or installation to another.
Data Adapters Basics 9
The Data Adapter module provides you with a quick and easy method to integrate with external sources of
information residing within your enterprise, or on the web. It is a flexible integration tool for accessing data from
external sources.
External information is accessed and processed though two-way connections called data links. Data links can be
used to display and process external information in the application, as well as to extract and present information
in external applications.
Do You Need Data Adapters?
The benefits of using the Data Adapter is manifold, but consider the following factors to evaluate the need to set
up data links.
Who owns the data?
If an external system controls the reading and writing of data or if important data is in an external database,
you are likely to need data links.
How do you access the data?
If access to external data is through defined APIs, URLs, or web services, or if the protocol for information
transfer is not open, you are likely to need data links.
What is the nature of the data required in customer interactions?
You are likely to need data links if interactions with customers require information that:
Is very customer-specific and not “global.”
Ages quickly, so that agents have to access data in real time.
Is used frequently, so agents have to access the information for each customer interaction.
How Do Data Adapters Work?
Data links are of two types:
1. Access links, which connect to the external source and fetch data. Access links are discussed in detail in
“Data Access Links” on page 16.
2. Usage links, which use the fetched data either in displays within the application, or as input criteria for
making decisions about processing information within the application. Usage links are explained in “Data
Usage Links” on page 23.
A working data-link connection typically involves:
Creating a data access link to fetch data from the external source.
Creating data usage links, which are made available to users to process the data extracted from the external
source. Multiple usage links can be grouped to create a single display. Usage link grouping is discussed in
detail in “Data Usage Link Groups” on page 29.
10 Enterprise Chat and Email Administrator’s Guide to Data Adapters
Where and How Can You Use Data Adapters?
Once data links are created, they can be used in the following modules.
Workflows
Data retrieved from usage links can be used in “IF” conditions to make routing decisions or to update
attributes of business objects.
Knowledge Base
Usage links can be embedded in Knowledge Base articles, like quick responses for chats. Once a working
link is embedded in an article, external information is retrieved and included in the article body when the
article is used by agents, or by the workflow engine for auto-acknowledgements.
Advisor Desktop
Usage links that can be executed by the agent are displayed in the Links section in the Agent Console.
Agents can add the output of usage links to responses by clicking the Add to Reply button.
Data Adapters Basics 11
Elements of the User Interface
The Administration Console user interface can be divided into five functional areas.
Elements of the Administration Console user interface
1. Console toolbar: The main toolbar of the console appears at the top of the screen. Each button on this
toolbar allows you to perform a specific function. Some of these are: navigate to other consoles, send and
receive internal messages, log out of the system, and access the online help for the Administration Console.
2. Tree pane: The Tree pane lists all the business objects in the application, allowing you to select the node
(folder) that you wish to work in. When you select a folder, its first-level contents are displayed in the List
pane.
To expand all first and second level nodes with a single click, press SHIFT and click the plus [+] button next
to the topmost node. The contents of all first and second level nodes are displayed in the Tree pane.
3. List pane: The List pane displays first-level contents of the folder selected in the Tree pane. You can view
the name, description, date of creation, etc., of the displayed items. In this pane, you can create items or
select existing ones to modify or delete them.
4. Properties pane: The Properties pane displays the contents of the business object selected in the List pane.
In this pane, you can edit the properties of the selected item.
5. Status bar: The status bar is present at the bottom of every screen. It displays the following information:
The user name with which the user has logged in the system.
The language currently in use.
The status of the system (Loading, Ready, etcetera).
1
2
3
4
5
Authentication for Data Adapters 13
While some web services have publicly available APIs and links that data adapters can use, there are plenty of
services out there that require security clearance. Thus, it may be necessary to configure data adapters to use
these services with the required authentication details. There are two options for the type of authentication
configurations: Basic and OAuth 2.0. Create your authentication configurations before configuring the access
links.
Configuring Basic Authentication
Basic authentication uses standard fields in the HTTP header, removing the need for handshakes. Data adapters
authenticate to basic authentication enabled web services with a username and password combination - the
username and password are joined and passed in the Authorization HTTP header.
To create a basic data adapter authentication configuration:
1. In the Tree pane, browse to Administration > Department > Department Name > Integration > Adapters
> Authentication.
2. In the List Pane toolbar, click the New button.
3. In the Properties pane, on the General tab, provide the following details:
Name: The name for the configuration.
Description: A brief description of the configuration.
Authentication type: Select Basic.
Provide name and select authentication type
4. In the Properties pane, under the Configuration tab, provide the following details:
User name: The user name for the account the data adapter will use for authentication.
Password: The password for the account the data adapter will use for authentication.
Provide user name and password
14 eGain Administrator’s Guide to Data AdaptersEnterprise Chat and Email Administrator’s Guide to Data Adapters
5. Click the Save button to save your configuration. This configuration can now be used when creating
data links. For more information, see. “Data Access Links” on page 16.
Configuring OAuth 2.0 Authentication
OAuth 2.0 configuration is required for web services that need authorization to allow its resources to be accessed
by a third-party client. OAuth generated Access Token is passed in the web services Authorization HTTP
header.
Keep the OAuth 2.0 configuration up-to-date in the application as it changes based on the web services provider
access and authorization policies.
To create an OAuth 2.0 data adapter authentication configuration:
1. In the Tree pane, browse to Administration > Department > Department Name > Integration > Adapters
> Authentication.
2. In the List Pane toolbar, click the New button.
3. In the Properties pane, on the General tab, provide the following details:
Name: The name for the configuration.
Description: A brief description of the configuration.
Authentication type: Select OAuth 2.0.
Provide name and select authentication type
4. In the Properties pane, under the Configuration tab, provide the following details:
OAuth2 ClientId: The unique string representing the registration information provided by the service
provider.
OAuth2 ClientSecret: The unique string provided by the service provider that acts as a means of
authorizing a client that is requesting an access token.
Refresh Token: Credentials used to obtain new access tokens when the current access token expires.
Token Request URL: Click the Assistance button. In the window that appears, provide the access
token request URL and click OK to close the window. This field is required.
Method: Select the method in which the access token is retrieved. Select either Post or Get. The
method selected depends on what the client authentication server supports.
Headers: Click the Assistance button. In the window that appears, provide any necessary additional
values to include in the response header by entering a Name and Value for the field. When you have
entered all the necessary header values, click OK to close the window.
Authentication for Data Adapters 15
Token Request Params: Click the Assistance button. In the window that appears, provide the
parameters for the token request body. Format the parameters string property with variables and values
to ensure that correct information is sent in the request.
For example:
client_id=<client_id>&client_secret=<client_secret>&refresh_token=<refresh_t
oken>&grant_type=refresh_token
Access Token JSON Path: The JSON query path of an attribute in the returned JSON response. For
example,
$.access_token
.
Access Token: If you wish to provide a current access token, click the Assistance button and enter
the string in the field. Click OK to close the window. Leave this field blank if you do not have an
Access Token. New token will be requested by the application using the provided details.
Provide configuration details
5. Click the Save button to save your configuration. This configuration can now be used when creating
data links. For more information, see. “Data Access Links” on page 16.
Deleting Authentication Configuration
Authentication configuration cannot be deleted if it is used in a data access link.
To delete an authentication configuration:
1. In the Tree pane, browse to Administration > Department > Department_Name > Integration > Adapters
Authentication.
2. In the List pane, select an authentication configuration.
3. In the List pane toolbar, click the Delete
button.
4. A message appears asking to confirm the deletion. Click Yes to delete the authentication configuration.
Data Access Links 17
About Data Access Links
Access links connect to the external source and fetch data.
The following access link type can be created:
Web service - RESTful link: A web service link provides the mechanism to connect to a web service using
representation state transfer (REST) operations. With these type of data access links, the web service APIs
of third-party applications can be used to perform necessary functions, instead of developing custom
applications to perform the same actions. To configure a RESTful link, you need the API request URL
(HTTP/HTTPS) with the desired method (Get, Post, Put, Delete), along with any necessary authentication
details. If necessary, a header and body can be provided as well.
JDBC link: The JDBC link can be used to connect to the Archive database to extract or to update data. No
other database data link types are supported. The JDBC link type is only available in the application if the
installation was upgraded from an installation of 11.6(1) on MSSQL Standard 2014. The application comes
with the following links pre-configured:
Archived Activity Details by Case ID
Archived Case Details by Customer
Working on access links involves:
Configuring authentication details: If the data links you are creating require authentication, you can
configure the authentication format and details. For more information, see “Authentication for Data
Adapters” on page 12.
Creating access links: Creating access links is the first step in creating data adapters. Access links extract
the data from the source.
Testing access links: After creating the access links you can test them to ensure that they are working
properly.
Creating Web Service - RESTful Links
To create a web service link:
1. In the Tree pane, browse to Administration > Department > Department_Name > Integration > Adapters
> Data > Access > Links.
2. In the List pane toolbar, click the New button.
3. In the Properties pane, on the General tab, provide the following details.
Name: Type the name of the web service link.
Description: Type a brief description.
Type: The value in the field is set to Web Service - RESTful link and cannot be changed.
Method: Select the method for the request. The options available are:
Important: You can only view, edit, or delete pre-existing JDBC access links. Creating new
JDBC links is not permitted.
18 Enterprise Chat and Email Administrator’s Guide to Data Adapters
Get
Post
Put
Delete
Set the general properties of the access link
4. In the Properties pane, on the Input tab, provide the following details.
URL: Provide the request URL.
Authentication type: If you have created an authentication configuration for this data link, select the
appropriate configuration from the dropdown list. For more information, see “Authentication for Data
Adapters” on page 12. If authentication is not required, select None.
Accept: Select the format you expect the output of the data link to use: application/json or
application/xml.
Content-type: Select the format of the content that web services link expect as an input Options are:
application/json, application/xml, or application/x-www-form-urlencoded.
Body: Provide the body for the response.
Header: Provide the name and value for any additional response header fields.
Set the input properties
5. In the Properties pane, on the Output tab, provide the following details.
Extract Or Filter: Select Extract to fetch the attribute or an object from the original web services
response. Select Filter to filter an attribute or object from the above extracted object. Extraction and
filters work based on the XPATH and JSON query.
Data Access Links 19
PATH: Provide the path for the response. XPATH query when expected output is in XML format. Or
enter JSON query when expected output is in JSON format.
Example for JSON Output:
{
"firstName": "John",
"lastName" : "Bell",
"age" : 26,
"address" : {
"streetAddress": " 1252 Borregas Avenue ",
"city": " Sunnyvale ",
"postalCode" : " 94089 " }
}
JSON Query to fetch fist name from the above output:
Extract or Filter : Extact
PATH
: $.firstName
Internal Field Name: Provide the response field name.
Field Order: Provide the response field order.
Decoding: Provide the decoding format if necessary. The data extracted can be decoded to map the
output values to user defined strings. For example, if the values returned are 1 and 0, then they can be
mapped to Yes and No respectively by entering the following string: 0=No,1=Yes.
Click the Return button or press Enter on the keyboard to add the output path.
Set the output properties
6. Click the Save button.
20 Enterprise Chat and Email Administrator’s Guide to Data Adapters
Editing JDBC Links
This data adapter uses SQL queries or stored procedures to update or extract data from a database. Queries to be
executed can be generated at runtime using application specific input fields. The raw data fetched is in a Results
Set format. This data adapter can access information residing in a JDBC-compliant data store.
To edit a JDBC link:
1. In the Tree pane, browse to Administration > Department > Department_Name > Integration > Adapters
> Data > Access > Links.
2. In the List pane toolbar, click one of the following query links:
Archived_Activity_Details_By_CaseID_AL
Archived_Case_Details_By_Customer_AL
3. In the Properties pane, on the General tab, you can edit the following details.
Name: Type the name for the JDBC query link.
Description: Type a brief description.
Type: This is set to JDBC query.
Subtype: Select is the subtype.
Set the general properties
4. In the Properties pane, on the Input tab, provide the following details.
DSN: The data source name (DSN), provides all the connection information (server name, port number,
user name, password, driver) to successfully connect to the database. From the dropdown, select the
DSN.
Maximum number of rows: Specify the maximum number of rows the query should extract.
Data Access Links 21
Query: You can edit the query text that is already provided. If you are accessing unicode data (for
example, Japanese, Chinese, Western European etc), you must make sure that you use the N prefix in
the queries. For example,
select * from Customer_Data where C_Name like N'‚Ђ낵'
Set the input properties
5. In the Properties pane, on the Output tab, the following details have already been provided and can be
edited.
External Field Name: Type the exact names of the columns in the database table.
Field Type: This filed is disabled.
Internal Field Name: Type the display name for the field in which the data is to be extracted.
Decoding: The data extracted can be decoded to map the output values to user defined strings. For
example, if the values returned are 1 and 0, then they can be mapped to Yes and No respectively.
Set the output properties
6. Click the Save button.
Important: The Output tab is disabled for update type of JDBC queries.
22 Enterprise Chat and Email Administrator’s Guide to Data Adapters
Testing Access Links
After creating the links, you can test them to see if they are created properly.
To test an access link:
1. In the Tree pane, browse to Administration > Department > Department_Name > Integration > Adapters
> Data > Access > Links.
2. In the List pane, select the link you want to test.
3. In the Properties pane toolbar, click the Test button.
4. In the Test Data Access Link window that appears, enter the values for the input parameters of the link.
The Result pane is enabled and here you can view the results. If the access link is not configured properly, an
error message is displayed.
For some sample links, see “Sample Data Access Links” on page 33.
Deleting Access Links
To delete an access link:
1. In the Tree pane, browse to Administration > Department > Department_Name > Integration > Adapters
> Data > Access > Links.
2. In the List pane, select an access link.
3. In the List pane toolbar, click the Delete
button.
4. A message appears asking to confirm the deletion. Click Yes to delete the usage link group.
Important: The Test Data Access Link window appears only if any input parameter needs to be
provided.
Important: If an access link is used in a usage link, it cannot be deleted. To be able to delete it,
first remove it from the usage link.
24 Enterprise Chat and Email Administrator’s Guide to Data Adapters
About Data Usage Links
After you have created access links, you can define the display format of the data that is fetched by the access
link. This is done using usage links. Similar to knowledge base articles, usage links support macros, making
them simple to use in workflows, and by agents and KB authors.
Creating Usage Links
To be able to create usage links, you need to first create the data links. For details, see “Data Access Links” on
page 16.
To create a usage link:
1. In the Tree pane, browse to Administration > Department > Department_Name > Integration > Adapters
> Data > Usage > Links.
2. In the List pane toolbar, click the New button.
3. In the Properties pane, on the General tab, provide the following details.
Name: Type the name of the usage link.
Description: Type a brief description.
Set the general properties
4. In the Properties pane, on the Data Access Links tab, select the data access links.
Select the data access links
5. In the Properties pane, the Input tab shows all the input parameters configured for the data access links
selected for the usage link. Here, you can pre-determine values for some or all available parameters. If you
are planning to create a macro for the usage link, make sure that you provide the parameter values.
Data Usage Links 25
You can create different usage links from the same access link, and just change the value of the input
parameters here, to get different answers.
Set the input properties
6. In the Properties pane, on the Output tab, provide the following details.
Data Access Link: From the dropdown list, select the data access link.
Field Name: From the dropdown list, select the field name.
Display Name: Type the display name for the field in which the data is to be extracted.
Field Width: Specify the width of the field.
Hyperlink: Set the hyperlink.
Set the output properties
7. Click the Save button.
After creating the usage links, create macros for the usage links (page 25), configure the display of results
for the Agent Console (page 26), assign permissions to users so that they can access the usage links
(page 27), and test the usage links (page 27).
Creating Macros
Usage links support macros, making them simple to use in workflows, and by agents and KB authors.
To create a macro:
1. In the Tree pane, browse to Administration > Department > Department_Name > Integration > Adapters
> Data > Usage > Links.
2. In the List pane, select a usage link.
3. In the Properties pane, on the General tab, provide the following details.
Important: Macros can be configured only for usage links that do not require any input
parameters.
26 Enterprise Chat and Email Administrator’s Guide to Data Adapters
Macro name: Type a name for the macro.
Macro default value: Type the default value of the macro. When the macro is expanded, and no
content is found, the default content of the macro is used. This content should be adequate enough to
represent the original content.
Macro exception article: In the field, click the Assistance button. The Select Article window appears.
In the window, select the exception article and click the OK button. If an error occurs while expanding
the macro, the exception article is used. It ensures that if the macro does not expand, the customer is
shown some alternate text, and not an error message.
4. Click the Save button.
Configuring Display of Results
After you have created the usage link, you can configure how the results should appear in the Agent Console.
To configure the display of results:
1. In the Tree pane, browse to Administration > Department > Department_Name > Integration > Adapters
> Data > Usage > Links.
2. In the List pane toolbar, select a usage link.
3. In the Properties pane, on the Formatting tab, provide the following details.
Header: Specify a header for the results.
Footer: Specify a footer for the results.
Include column headers in response: Use this option to add the header and footer information in the
Reply pane when the agent adds the results in the reply. By default it is disabled. Select Yes to enable it.
Set the formatting
4. Click the Save button.
Important: A macro name cannot contain spaces, or any of the following characters: < ` , . ? : ; &
" ' !
Data Usage Links 27
Assigning Permissions for Usage Links
After creating data usage links, the next most important step is to give permissions to users to access the data
usage links. All users (that includes administrators, authors, and agents) who need to use the data usage link or
the macro of the link, must be given the Execute permission on the link. The user who creates the data usage link
does not get the execute and delete permissions automatically.
To assign permissions:
1. In the Tree pane, browse to Administration > Department > Department_Name > Integration > Adapters
> Data > Usage > Links.
2. In the List pane, select the usage link on which you want to give permissions.
3. In the Properties pane, on the Permissions tab, assign the following permissions to users and user groups:
Own
View
Edit
Delete
Execute: Only users with execute permission can use usage links. You must give this permission to all
users who need access to the usage link.
4. Click the Save button.
Testing Usage Links
After creating the usage links you can test them to see if they are created properly. You should test your links
after creating them.
To test the usage link:
1. In the Tree pane, browse to Administration > Department > Department_Name > Integration > Adapters
> Data > Usage > Links.
2. In the List pane, select the usage link you want to test.
3. In the Properties pane toolbar, click the Test data usage link button.
The Test Data Usage Link window appears, where you enter the values for the input parameters of the link.
The Result pane is enabled and here you can view the results.
Important: The Test Data Usage Link window appears only if any input parameter needs to be
provided.
28 Enterprise Chat and Email Administrator’s Guide to Data Adapters
Deleting Usage Links
To be able to delete a usage link, you need to have delete permissions on it.
To delete a usage link:
1. In the Tree pane, browse to Administration > Department > Department_Name > Integration > Adapters
> Data > Usage > Links.
2. In the List pane, select a usage link.
3. In the List pane toolbar, click the Delete
button.
4. A message appears asking to confirm the deletion. Click Yes to delete the usage link.
Important: If a usage link is used in a usage link group, it cannot be deleted. To be able to delete
it, first remove it from the usage link group.
Important: The Delete button is enabled only if you have the delete permission on the usage link.
30 Enterprise Chat and Email Administrator’s Guide to Data Adapters
This chapter describes procedures to help you configure and manage usage link groups.
About Usage Link Groups
A data usage link group is a combination of two or more data usage links. To be able to create usage link groups,
you need to first create the usage links. For details, see “Data Usage Links” on page 23.
Creating Usage Link Groups
To create a link group:
1. In the Tree pane, browse to Administration > Department > Department_Name > Integration > Adapters
> Data > Usage > Link Groups.
2. In the List pane toolbar, click the New button.
3. In the Properties pane, on the General tab, provide the following details.
Name: Type the name of the usage link group.
Description: Type a brief description.
Set the general properties
4. In the Properties pane, on the Data Usage Links tab, select the data usage links.
Select the data usage links
5. Click the Save button.
After creating the usage link groups, configure the display of results for the Agent Console (page 31) and
assign permissions to users so that they can access the usage link group (page 31).
Data Usage Link Groups 31
Configuring the Display of Results
After you have created the usage link group, you can configure how the results should appear in the Agent
Console.
To configure the display of results:
1. In the Tree pane, browse to Administration > Department > Department_Name > Integration > Adapters
> Data > Usage > Link Groups.
2. In the List pane toolbar, select a usage link group.
3. In the Properties pane, on the Formatting tab, provide the following details.
Number of rows: Specify the number of rows to be displayed in the results page.
Number of columns: Specify the number of columns to be displayed in the results page.
Orientation: From the dropdown list, select the orientation. The options available are:
Fill rows and then fill columns
Fill columns and then fill rows
Header: Specify a header for the results.
Footer: Specify a footer for the results.
Set the formatting
4. Click the Save button.
Assigning Permissions for Usage Link Groups
After creating data usage link groups, the next most important step is to give permissions to users to access the
data usage link groups. All users (that includes administrators, authors, and agents) who need to use the data
usage link groups must be given the Execute permission on the link. The user who creates the data usage link
group does not get the execute and delete permissions automatically.
To assign permissions:
1. In the Tree pane, browse to Administration > Department > Department_Name > Integration > Adapters
> Data > Usage > Link Groups.
2. In the List pane, select the usage link group on which you want to give permissions.
32 Enterprise Chat and Email Administrator’s Guide to Data Adapters
3. In the Properties pane, on the Permissions tab, assign the following permissions to users and user groups:
Own
View
Edit
Delete
Execute: Only users with execute permission can use usage link groups. You must give this permission
to all users who need access to the usage link group.
4. Click the Save button.
Deleting Usage Link Groups
To be able to delete a usage link group, you need to have delete permissions on it. For information on how to
give permissions, see “Assigning Permissions for Usage Link Groups” on page 31.
To delete a usage link group:
1. In the Tree pane, browse to Administration > Department > Department_Name > Integration > Adapters
> Data > Usage > Link Groups.
2. In the List pane, select a usage link group.
3. In the List pane toolbar, click the Delete
button.
A message appears asking to confirm the deletion. Click Yes to delete the usage link group.
Important: The Delete button is enabled only if you have delete permission on the usage link group.
34 Enterprise Chat and Email Administrator’s Guide to Data Adapters
Example One – Get Weather Information for a City
In this example, we describe how to create Web Services- RESTFul link to look up weather using the weather
report API available from www.openweathermap.com. This example does not use any authentication.
To create a link:
1. Before creating the link, sign-up at http://www.openweathermap.com and get the API key to be used for the
data adapter.
2. In the Properties pane, on the General tab, provide the following details.
Name: Type a name.
Type: Type is set to Web Services - RESTful and cannot be changed.
Method: Set the method as Post.
3. In the Properties pane, go to the Input tab and provide the following details.
URL: Type the URL
http://api.openweathermap.org/data/2.5/weather?q=<%city%>&APPID=
c854f43c700fa17b
1729367c9e0648e9
<%city%>
sets up the dynamic variable that needs a value every time this access link is executed.
Replace the value of
APPID
in the URL with the API key value generated at
http://www.openweathermap.com
Authentication: Set as None.
Accept: Set as application/json.
Content-type: Set as application/x-www-form-urlencoded.
Sample link for getting weather information
4. In the Properties pane, go to the Output tab and provide the following details:
Extract Or Filter: Select Extract.
Note: Users creating this link should be familiar with REST Web services and JSON.
Sample Data Access Links 35
PATH: Set as $. weather[0]['description']
Internal Field Name: Provide the name as Weather.
Field Order: Set the value as 1.
5. Click the Save button.
6. Click the Test button. The Test Data Access Link window appears.
7. In the Test Data Access Link window, type the city name as Sunnyvale.
8. In the Result tab, you will see the weather information for Sunnyvale.
Example Two – Extract Stock Information From a
Website
In this example, we describe how to create a data access link to look up asking price for stocks using the API
from https://intrinio.com. This example uses basic authentication.
Configure Basic Authentication
To create authentication:
1. Sign-up at https://intrinio.com and get the API username and password to be used for the data adapter.
2. In the Administration Console, browse to Administration > Department > Department Name >
Integration > Adapters > Authentication.
3. Configure Basic Authentication using the username and password generated from https://intrinio.com.
Create the Access Link
To create a link:
1. In the Properties pane, on the General tab, provide the following details.
Name: Type the name as Stock rates.
Type: Type is set to Web Services - RESTful and cannot be changed.
Method: Set the method as Get.
2. In the Properties pane, go to the Input tab and provide the following details.
URL: Type the URL
https://api.intrinio.com/data_point?identifier=<%ticker_sym%>&item=ask_price
The
<%ticker_sym%>
sets up the dynamic variable that needs a value every time this access link is
executed.
Authentication: Select the basic authentication created for https://intrinio.com.
Accept: Set as application/json.
36 Enterprise Chat and Email Administrator’s Guide to Data Adapters
Content-type: Set as application/x-www-form-urlencoded.
Sample link for getting stock rates
3. In the Properties pane, on the Output tab, provide the following details.
Extract Or Filter: Select Extract
PATH: Set as $.identifier
Internal Field Name: Provide the name as Stock Symbol
Field Order: Set the value as 1.
Click the Return button or press Enter on the keyboard to add the output path.
Extract Or Filter: Select Extract
PATH: Set as $.value
Internal Field Name: Provide the name as Ask Price
Field Order: Set the value as 2.
Click the Return button or press Enter on the keyboard to add the output path.
Configure the output
4. Click the Save button.
5. Click the Test button. The Test Data Access Link window appears.
6. In the Test Data Access Link window, type the ticker_sym as IBM.
7. In the Result tab you will see the stock price extracted from the website.
Sample Data Access Links 37
Example Three – Shorten URLs Using Google API
In this example, we describe how to create a data access link to create short URLs using the Google API. This
example uses OAuth authentication.
Configure OAuth 2.0 Authentication
To configure authentication:
1. Sign-up and enable OAuth2.0 for Short URL API at https://developers.google.com/apis-explorer/#p/ From
the Google API Manager, note down the client ID, client secret, and refresh token to be used for the data
adapter.
2. In the Administration Console, browse to Administration > Department > Department Name >
Integration > Adapters > Authentication.
3. Configure OAuth 2.0 Authentication using the client ID, Secret, and refresh token generated from
https://developers.google.com. For the rest of the fields, provide following details:
Token Request URL: Set as
https://www.googleapis.com/oauth2/v4/token
Method: Set as Post
Headers: Set as
Content-Type, application/x-www-form-urlencoded
Token Request Params: Set as
client_id=<client_id>&client_secret=<client_secret>&refresh_token=<refresh_t
oken>&grant_type=refresh_token
Access Token JSON Path: Set as
$.access_token
Access Token: Leave this field blank.
Configure OAuth authentication
4. Click the Save button.
38 Enterprise Chat and Email Administrator’s Guide to Data Adapters
Create the Access Link
To create a link:
1. In the Properties pane, on the General tab, provide the following details.
Name: Type the name as Short URLs.
Type: Type is set to Web Services - RESTful and cannot be changed.
Method: Set the method as Post.
2. In the Properties pane, go to the Input tab and provide the following details.
URL: Type the URL
https://www.googleapis.com/urlshortener/v1/url
Authentication: Select the OAuth authentication created for Short URL API (page 37)
Accept: Set as application/json.
Content-type: Set as application/json
Body: Set the body as
{"longUrl": "<%URL%>"}
<% URL%>
sets up the dynamic variable that needs a value every time this access link is executed.
Sample link
3. In the Properties pane, go to the Out tab and provide the following details.
Extract Or Filter: Select Extract
PATH: Set as $.id
Internal Field Name: Provide the name as Short URL
Field Order: Set the value as 1.
Click the Return button or press Enter on the keyboard to add the output path.
4. Click the Save button.
5. Click the Test button. The Test Data Access Link window appears.
6. In the Test Data Access Link window, type any URL.
7. In the Result tab you will show the short URL returned by the Google API.
