Query Data

Data lookup requests from the gadget to the ServiceNow platform may occur in different ways. The most frequent instances are associated with Directory Lookups (typing a value into the gadget's search field) or Participant Lookups (identifying a caller).

info

Please note that the logged in ServiceNow user must have read access to query the records defined by the configuration. If the user is not allowed to read these records, null will be returned.

Configuration for all features is almost identical. The only differences are in the parameters passed from the gadget to the ServiceNow platform.

b+s Connects for ServiceNow offers two modes to configure date lookup: simple and advanced.

Steps 1-3 below explain how to configure data lookups in a ServiceNow instance.

info

ServiceNow role required: admin, x_busag_cnx.CC Administrator or x_busag_cnx.CC Supervisor

Step by step instructions:

1. Login to ServiceNow Service Management as administrator.
2. Go to Service Layout by searching in the left panel. Then click New to create a new record or choose an existing Service Layout record.
3. Enter a Name and Description to help identify the data lookup being used.

Simple Data Lookup

The easiest way to query data is to configure one Lookup table (ServiceNow table) in which to search for information. The default table is sys_users, which contains records for every ServiceNow user. However, it is possible to search in any available table in ServiceNow.

Next configure a Lookup query string. This value contains the filter with which the records in a given table are queried. This value is known as an encoded query string, and is very similar to the ServiceNow URL schema. Useful information on generating query strings is available in the Tips & Tricks section.

For more information please visit the Generate an encoded query string through a filter guide in the ServiceNow documentation.

To complete the configuration, provide a "Lookup result" (this defines which fields to return). The correct format is similar to a standard URL: Key1=${fieldA}&Key2=${fieldB}, where Key is the identifier for the gadget, and ${fieldA} is the place holder for the resulting field value.

Advanced Data Lookup

To query information from more than one table, a custom lookup script is required. A custom lookup script offers the ability to query information using ServiceNow's Scoped GlideRecord.

For more information please visit the GlideRecord - Scoped guide in the ServiceNow documentation.

The resulting data must be written to the result object.

The following data from b+s Connects can be used in advanced lookup scripts:

Variable name	Description	Available for
search	Search string entered by the agent into the search field.	Directory Lookup
serviceLayout	Unique identifier (sys_id) of the used service layout. Can be used to query the correct directory numbers.	Directory Lookup
workitem.BAAccountNumber	Customer account number available in the import file (Campaign calls only)	Participant Lookup
workitem.BABuddyName	If available in the import file, contains the customers first and last name separated by commas (Campaign calls only)	Participant Lookup
workitem.BACampaign	Outbound option campaign to which the call belongs (Campaign calls only)	Participant Lookup
workitem.BACustomerNumber	Dialed customer phone number (Campaign calls and UCCX only)	Participant Lookup
workitem.BADialedListID	Unique key identifying a specific customer record within the Dialing List (Campaign calls only)	Participant Lookup
workitem.BAResponse	Multi-purpose placeholder for sending data (Campaign calls only)	Participant Lookup
workitem.BAStatus	Indicates mode and direction of the Outbound Option Dialer initiated call (Campaign calls only)	Participant Lookup
workitem.BATimeZone	Indicates the GMT offset, in minutes, for the customers time zone. Used to obtain customers local time (Campaign calls only)	Participant Lookup
workitem.callKeyCallId	Cisco Finesse Call Key Call ID -> Router Call Key (CCE only)	Participant Lookup
workitem.callKeyPrefix	Cisco Finesse Call Key Prefix -> Router Call Key Day (CCE Only)	Participant Lookup
workitem.callType	Cisco Finesse Call Type	Participant Lookup
workitem.callVariable1	Cisco Contact Center call variable 1	Participant Lookup
...
workitem.callVariable10	Cisco Contact Center call variable 10	Participant Lookup
workitem.classification	Call Classification Customer -> Call with customer or other external participant Consultation -> Consultation call Conference -> Conference call Transfer -> Call which was answered by a different agent and transferred to the current one. Internal -> Internal call. Identified using Internal number regex Monitor -> Supervisor monitoring a call. Only available for supervisor agents Unknown -> Call of an unknown classification. Campaign -> Campaign call CampaignPreviewReservation -> Campaign preview / direct preview reservation call CampaignPreview -> Campaign preview / direct preview call	Participant Lookup
workitem.dialedNumber	Cisco Finesse Dialed Number	Participant Lookup
workitem.DNIS	Cisco Finesse DNIS	Participant Lookup
workitem.mediaId	Cisco Finesse Media ID	Participant Lookup
workitem.outboundClassification	Cisco Finesse Outbound Classification	Participant Lookup
workitem.queueName	Cisco Finesse Queue Name	Participant Lookup
workitem.queueNumber	Cisco Finesse Queue Number	Participant Lookup
workitem.user.eccVariableName	Cisco Contact Center extended call variable. The name is dependent on the ECC variable name	Participant Lookup
workitem.wrapUpReason	Cisco Finesse Wrap-Up Reason	Participant Lookup

Example Scripts can be found under Advanced Script Examples.

Keyword based search

Most data query examples use CONTAINS or ENDSWITH operators in their WHERE clauses. The advantage is that these queries are very predictable and can specify exactly which fields are searched. But the disadvantage is, that these operators do not use an index, which can cause performance problems with large tables. In this case it is recommended using the keyword based search provided by ServiceNow for the data query.

Keyword based search can be used for all data queries in b+s Connects for ServiceNow and is available for both Simple Data Lookups and Advanced Data Lookups. One example:

GOTO123TEXTQUERY321=*${search}* | ${search}

For more information please visit the Zing text indexing and search engine documentation.

Possible Variables

The following variables can be displayed:

Value	Description
callVariable1	Cisco Contact Center call variable 1
...
callVariable10	Cisco Contact Center call variable 10
user.eccVariableName	Cisco Contact Center Extended call variable. The name is dependent on the ECC Variable name
callType	Cisco Finesse Call Type
DNIS	Cisco Finesse DNIS
dialedNumber	Cisco Finesse Dialed number
number	Cisco Finesse ANI. Number is displayed like it is received from Finesse
outboundClassification	Cisco Finesse Outbound classification
callKeyCallId	Cisco Finesse Call Key Call ID -> Router call Key (CCE only)
callKeyPrefix	Cisco Finesse Call Key Prefix -> Router call Key Day (CCE only)
mediaId	Cisco Finesse Media ID
queueName	Cisco Finesse Queue Name
queueNumber	Cisco Finesse Queue Number
wrapUpReason	Cisco Finesse Wrap-Up Reason
BACampaign	Outbound Option campaign to which the call belongs
BAAccountNumber	Customer account number available in the import file
BAResponse	Multi-purpose placeholder for sending data
BAStatus	Indicates mode and direction of the Outbound Option Dialer initiated call
BADialedListID	Unique key identifying a specific customer record within the Dialing List
BATimeZone	Indicates the GMT offset, in minutes, for the customer’s time zone and is used to obtain the customer’s local time
BABuddyName	Contains the customer’s first and last name separated by a comma, if available in the import file
BACustomerNumber	Contains the dialed customer phone number (UCCX only)

info

Refer to the Cisco Finesse documentation for more information about these variables.

info

For variables available in advanced lookup scripts, please refer to Advanced Data Lookup