ServiceNow developer settings
Preferred minimum ServiceNow Version requirements: Tokyo patch 1
Set up a basic auth user
It is likely that the ServiceNow admin account has 2 factor authentication enabled and associated with that user. As a result, it cannot be used to gain admin access in CCAI Platform. You must create a new user account in ServiceNow for this purpose. Create a new basic user with credentials:
Go to User > New.
Fill in details, and select Web service access only.
Make note of the user ID and password.
Configure instance views
(Optional) Add favorites
Favorites are a quick way to find your most commonly used links within the ServiceNow instance. To add a favorite, select the star icon next to a field in the Navigator panel. If you want to later filter the navigator panel to only see your favorites, you can select the star icon directly below the filter navigator field in the Navigator panel.
Examples of useful Favorites:
- Incidents: Associations to records for Custom CRM.
- Users: Associations to accounts for Custom CRM.
- Rest API Explorer: A good way to test the API.
Add custom fields manually
Select the expander icon (3 horizontal lines) in the upper left hand corner inside the object view you would like to change. You can do this in Self Service View or Default View.
In the menu select Configure > Form Design to open the Form Designer.
In the left column, select the Field Types tab.
Drag and drop the type of custom field you would like to add.
Once you drop the field type into the section you want, select the cog icon to see Settings.
Inside the window popup, change the label and take note of the name. The name is what you use in CCAIP app settings.
Select Save in the upper right-hand corner of the screen.
Map session data to the CRM
You must map the appropriate session data from CCAIP using Dialogflow and use the following parameters:
Virtual Agent Data
{
"ujet": {
"session_variable": {
"capture_target": "payload",
"payload": {
"value_one": "$session.params.payload_value_one"
};
"capture_type": [ "comment", "field" ] // optional, default of ["comment"]
}
}
}
Metadata
https://INSTANCE.service-now.com/api/now/table/sys_dictionary?sysparm_query=name%3Dsys_user https://INSTANCE.service-now.com/api/now/table/sys_dictionary?sysparm_query=name%3Dincident
Label: column_label
API Key: element
Custom fields are same level as the standard fields in the response of
sys_user
or incident
.
Upload a file from CCAIP to the CRM
https://INSTANCE_URL.service-now.com/api/now/attachment/upload
Method: POST
Request data format: property
Response data location: data.result
Type: Multi-part form
Attachment type: Attachment Url
Attachment Url: download_link
Params: table below
Example request:
{ file: FILE_DATA, table_name: incident, table_sys_id: RECORD_ID }
Integrate agent adapters (custom forms)
The following steps walk you through the process of enabling agent adapters and the Click to Call function in the ServiceNow Instance.
Install and configure OpenFrame
Navigate to All > System Applications > All Available Applications > All.
Search for OpenFrame.
Install OpenFrame.
Once installed, navigate to All > OpenFrame > Configurations.
Create configuration with a URL. If you have multiple configurations within a Servicenow Instance, your user might not have access to a newly created configuration. Check your groups and the list of OpenFrame configuration orders to determine which configuration your user is using.
Type
sys_properties.list
into search.Edit
glide.ui.concourse.onmessage_enforce_same_origin_whitelist
.Add the new URL to the list of values.
Edit
sn_openframe.cross.origin.access
.Add
autoplay
to the list of values.
Add Click to Call to the top of the form
Navigate to System UI > UI Actions.
Select Create New Action.
In the form as illustrated below. Select the table that this Click to Call will be a part of.
For forms with a reference to a contact or user, use the
g_form.getReference
API to access the user's phone number. For custom tables, the Reference ID and the resulting attributes may differ. Communication to CCAIP will be the same, so the payload and data structure must remain identical to the following:function clickToDial() { var user = g_form.getReference('caller_id',function(res) { var phone = res.phone || res.mobile_phone; var payload = {"name": "clicktodial", "number": phone}; var data = {"payload": payload, "method": "openframe_communication" }; CustomEvent.fireAll("openframe_request", data); }); }
For forms with a number within the form to call, use the
g_form.getValue
API to retrieve the relevant values. This is an example from the UI action for the Users table. For custom tables, the form field names may differ. Communication to the CCAIP will be the same, so the payload and data structure must remain identical to the following:function clickToDial() { var phone = g_form.getValue('phone') || g_form.getValue('mobile_phone'); var payload = {"name": "clicktodial", "number": phone}; var context = {"payload": payload, "method" : "openframe_communication" }; CustomEvent.fireAll("openframe_request", context); }
Add Click to Call next to references
The call button next to references to contacts must be edited within the form. Right click on the field and navigate to Configure Dictionary. For attributes add either the value
show_phone
orshow_phone_customer_service
to theref_contributions
value.In UI Macros, edit
show_phone
andshow_phone_customer_service
.Replace the following:
Previous:
var task = {"entity": p.attr('data-task-table'), "query" :"sys_id="+p.attr('data-task-id')+"$[AMP]sysparm_view="+p.attr('data-task-view'),"value":p.attr('data-task-value'),"label":p.attr('data-task-label')}; var company = {"entity": p.attr('data-company-table'),"query":"sys_id="+p.attr('data-company-id')+"$[AMP]sysparm_view="+p.attr('data-task-view'),"value":p.attr('data-company-value'),"label":p.attr('data-company-label')}; var caller = {"entity": p.attr('data-caller-table'),"query": "sys_id="+p.attr('data-caller-id')+"$[AMP]sysparm_view="+p.attr('data-task-view'),"value":p.attr('data-caller-value'),"label":p.attr('data-caller-label')}; var callContext = []; callContext.push(task); callContext.push(company); callContext.push(caller); var metaData = {"phoneNumber":p.attr('data-caller-phone'),"taskId":p.attr('data-task-id')}; var data = {"metaData":metaData , "data": callContext}; var payload = {"type": "OUTGOING_CALL", "data" : data}; var createInteractionData ={}; createInteractionData.interactionSysId = -1; createInteractionData.direction = 'outbound'; createInteractionData.context_document = p.attr('data-task-id'); createInteractionData.context_table = p.attr('data-task-table'); createInteractionData.account = p.attr('data-company-id'); if(p.attr('data-caller-table') === 'customer_contact') createInteractionData.contact = p.attr('data-caller-id'); createInteractionData.opened_for = p.attr('data-caller-id'); var ga = new GlideAjax('sn_openframe.OpenFrameAjaxUtility'); ga.addParam('sysparm_name', 'createInteractionWithPropertyCheck'); ga.addParam('context', JSON.stringify(createInteractionData)); ga.getXML(function(serverResponse) { var result = serverResponse.responseXML.getElementsByTagName("result"); var output = JSON.parse(result[0].getAttribute("data")); if(output.status == "success"){ var interaction = {"entity": "interaction", "query" :"sys_id="+output.fields.interactionSysId, "value":output.fields.number, "label":"Interaction", "display":false}; payload.data.data.push(interaction); } var context = {"payload": payload, "method" : "openframe_communication" }; jslog("context with interaction : "+ JSON.stringify(context)); CustomEvent.fireAll("openframe_request", context); });
New:
var phone = p.attr('data-caller-phone') var payload = {"name": "clicktodial", "number": phone}; var data = {"payload": payload, "method": "openframe_communication" }; CustomEvent.fireAll("openframe_request", data);
CRM settings
The following steps illustrate how to connect the API to ServiceNow using the CCAIP Developer portal.
In the CCAIP Portal, go to Settings > Developer Setting s> CRM.
In the Agent Platform section, select ServiceNow.
Enter your ServiceNow domain information in the ServiceNow Domain field. This might be a developer instance or vendor instance as needed, but is a direct correlation to the instance and is the first part of the URL in the ServiceNow portal web address:
https://{your instance}.servicenow.com
.In the ServiceNow Cloud Selection field, select
Incident
for a basic ticket type. If you selectCustom
, additional options will appear. Incidents are extensions of task table; custom objects should be extensions of incidents.In the Authentication Credentials fields, enter your username and password.
If you selected
Incident
for the Cloud Selection Field type you will see the following fields:- Lookup Account Object includes three dropdown fields:
Object Type
,Phone Number lookup fields
, andPhone number primary field
.
- Lookup Account Object includes three dropdown fields:
If you selected
Custom
for the Cloud Selection Field type you will see the following fields:- Lookup Record Object:
- Base Record Object Type: Select either a
task
orincident
table type. - Record Object Type: This field will populate with data if an incident table has been extended, and you can select it if required.
- Base Record Object Type: Select either a
- Lookup Account Object includes three dropdown fields:
Object Type
,Phone Number lookup fields
, andPhone number primary field
.
- Lookup Record Object:
Custom User ID Fields: Check this box if you want to enable custom user lookup fields for Mobile/Web SDK sessions.
Phone Number Format: Allows you to select the format you would like to use for displaying phone numbers.
Session Metadata File: Check this box to attach session metadata to CRM records.
Click Save to save your selections. If you have checked the Custom User ID Fields box, you will have the option to create custom fields for records. This will add custom fields tabs to the bottom of each ServiceNow Incident below the resolution code and resolution notes sections of the page.
Custom fields for records
These are custom fields that have already been created for the ServiceNow Instance in the Form Designer. Instructions about how to create other custom fields can be found in the ServiceNow documentation under ServiceNow CRM Setup, section Add Custom Fields Manually.
Field | Type | Definition |
---|---|---|
u_ujet_custom_field_after_call_work |
String | After Call Work duration |
u_ujet_custom_field_call_duration |
String | Call Duration |
u_ujet_custom_field_comm_id |
Integer | Call or chat ID depending on contact type |
u_ujet_custom_field_rating |
Integer | CSAT score |
u_ujet_custom_field_email_via_web |
String | Email sent from web |
u_ujet_custom_field_feedback |
String | Feedback |
u_ujet_custom_field_from_phone_number |
String | Phone number of caller |
u_ujet_custom_field_hold_duration |
String | Total hold time |
u_ujet_custom_field_menu_path |
String | Menu Selection |
u_ujet_custom_field_queue_name |
String | Queue Name |
u_ujet_custom_field_session_type |
String | Session Type |
u_ujet_custom_field_verification |
True/False | Confirm verification completed |
u_ujet_custom_field_wait_time |
String | Total wait time |
Custom field mapping for Virtual Agent
If using Virtual Agent, configure this field in the Custom Field Mappings screen. This allows the Virtual Agent variables to transfer over from the Virtual Agent session payload to ServiceNow. Variable names can be any string, the field labels listed here are an example.
In the Custom Field Mappings screen, configure the connection between the variables created by the payload definitions you used in the initial Virtual Agent configuration and the relevant variable within ServiceNow.
Field Mapping Title | CRM Field Label | Custom Data Field Label |
---|---|---|
Virtual Agent Feedback | ccaip_custom_field_incident_feedback |
va_feedback |
Configure other Settings
You will find the other settings that will allow you to properly integrate CCAIP into your ServiceNow Instance under the Settings drop-down menu. Refer to the links in the following list for additional information about configuring each section.
- Languages and Messages
- Operations Management
- Users and Teams
- Virtual Agent
- Campaigns
- Surveys
- Queues
- Calls
- Chat
- SMS
- Consumer Management
- Developer Settings
Test outputs
You can now verify the functionality of your call and chat flows by clicking on the relevant buttons at the top of the screen of the CCAIP Portal. It is important to ensure your pop-up blocker is disabled when running this test.
You should expect an Incident to be created in ServiceNow, with the call or chat contact listed in the Activities section of the Incident. This should show up as a Work Note, rather than an Incident Comment, so that this backend activity is not visible to customers.
The case description will auto-populate with "Call via CCAIP" or "Chat via CCAIP" and might need to be updated by agents.
Once you are satisfied with the outputs of your call or chat you can enter a resolution code and note (if ServiceNow resolution code and notes fields have been configured), then close the case.
To verify that the case has closed, you might need to click the back
navigation button on your browser. It is expected behavior in the ServiceNow
Instance that after resolving the case it automatically closes and advances you
to a customer record page.