Hello community,
here I will share some of my learnings about creating a custom CTI (Computer Telephony Integration) script for the HR Case form.
When this is successfully implemented, it means that an HR employee who gets a phone call will automatically be redirected to an HR Case form pre-filled with the calling user.
First let me explain the basics to set this up:
By default when you open a url like https://yourinstance.service-now.com/cti.do an empty incident form will open. By passing some parameters in the URL you can also specify which incident to open or which user to select. The official documentation from ServiceNow can be found here.
There is also a comment about defining your own CTI script but it is very short and even a bit confusing, that is why I am creating this more detailed explanation here. I had to go through some trial and error myself and want to share my learnings.
Creating the Business Rule
If you do not want to open the incident form but another link in the instance then you need to define your own CTI script. You could overwrite the existing script (which can be found in the Business Rule "CTI Processing") but that is not recommended. Instead, you should create a new Business Rule for your own usecase.
I know that it is a bit confusing that you have to write the script in a Business Rule. But that is how the architects at ServiceNow decided to do it. The trick is to create the Business Rule for the table "Global" and to make it client callable (you need to display that field in the list layout and set the value to true there). For my example the Business Rule is created as follows:
- Name: CTI for HR Case
- Scope: Global
- Table: Global [global]
- Accessible from: This application scope only
- Active: true
- Advanced: true
- Client callable: true
Writing the Script
What comes next is your script in the advanced tab of the Business Rule. What you definitely need in there is a function that at least assigns a value to the answer variable and returns the same value. The simplest example would be this:
function createHrCase() {
var url = 'sn_hr_core_case_creation.do';
answer = url;
return url;
}
When you have come this far you can already start your first test: Open the URL https://yourinstance.service-now.com/cti.do?sysparm_cti_rule=createHrCase and you will be redirected to the HR Case form.
The parameter “sysparm_cti_rule” tells the CTI processor which function to execute. If it is the name of the function in your Business Rule then this will be called. If the name you provided is unknown it will default to opening an incident form.
Now that we can open an HR Case form we can take the next step and pre-populate a user. Let’s extend our script to the following:
function createHrCase() {
var userSysId = '';
// get url parameter
if(typeof sysparm_user_id != 'undefined'){
userSysId = sysparm_user_id.toString();
}
// build url to redirect to
var url = 'sn_hr_core_case_creation.do?sysparm_user=' + userSysId;
answer = url;
return url;
}
After saving this you can for example open the URL https://yourinstance.service-now.com/cti.do?sysparm_cti_rule=createHrCase&sysparm_user_id=62826bf03710200044e0bfc8bcbe5df1. If you provide a valid sys_id for a user, it will pre-populate that user in your HR Case form. That is because the page https://yourinstance.service-now.com/sn_hr_core_case_creation.do is also listening for certain parameters.
Please note the following points:
- Your parameter must start with sysparm_ otherwise it will not work
- You need to check if the parameter is really provided, otherwise if not an error will be thrown and the whole script will abort (defaulting to the incident form)
- Do this with typeof ... != 'undefined'
- You need to convert the parameter to a String, otherwise it will be an object and might not behave as you want (this caused me some headache)
In most cases you will not know the sys_id and want to provide a different parameter. That is no problem either because you are completely free to use anything you have access to in the script. For example if you only know the username of the user why not find the sys_id using a GlideRecord? The script would then look as follows:
function createHrCase() {
var username = '';
var userSysId = '';
// get url parameter
if(typeof sysparm_user_name != 'undefined'){
username = sysparm_user_name.toString();
}
// get user record
var grUser = new GlideRecord('sys_user');
if(username != '' && grUser.get('user_name', username)){
userSysId = grUser.getValue('sys_id');
}
// build url to redirect to
var url = 'sn_hr_core_case_creation.do?sysparm_user=' + userSysId;
answer = url;
return url;
}
This example can be tried out by opening the URL https://yourinstance.service-now.com/cti.do?sysparm_cti_rule=createHrCase&sysparm_user_name=abel.tuter
This is already it. Not too complicated but you need to know how to do it. I hope my little tutorial will help some people.
Hey Paul Kunze,
Greetings.
Scenario:
Need to open a case record whenever an incoming call is attended from the open frame window.
Current Situation:
A new IMS record is getting displayed upon answering the call.
I've created a new Client Callable Business Rule, now could you please let me know where I should be calling this business rule? Is it in the screenpop_url system property or should I configure it in my client application ( Cisco Contact Center )? I've added images of the system property and the Business rule.
Below is the image of the system property:
Below is the image of Business Rule:
Thank you!
