How to modify CTI integration to create an interaction record instead of new call record and open it in agent workspace ?

[Subrahmanyam2]

Hi Everyone,

I came across a scenario where end users calls help desk numbers and goes through IVR (Integrated voice response) menu and chooses options to reach out service desk. 

Service desk agents accepts calls in customer telephony software systems (Desktop apps) and the requirement is these apps need to open ServiceNow instance and create interaction record (have to prepopulate opened for, assigned to, type fields). And the ServiceNow browser window should automatically present interaction record in the agent workspace.

These telephony systems can open a ServiceNow URL in agents browser in their desktop or laptop if we can provide the URL which acts as processor to generate and present interaction form.

If any of you are familiar with CTI integration for new call, they were different. I will not go into specifics, but for new call we need not create new call record before presenting agent with new "New call" record creation form.

Since OOB agent workspace new interaction creation URLs will not let us specify parameters which can auto-populate fields on form, we have a need to insert the interaction record through processor script with desired field values and then redirect user to that page. Due to this reason, we have to implement the requirement the way I specified above.

If you tried to implement this, you would have come across two problems.

1) The CTI processor script from the global "CTI Processing" business rule will not let us insert or update the records in any table via script. Reason: The cti.do java processor executes the global business rule cti() function script in a sandbox. You will not be able to create or update new records or not even be able to execute log statements.

2) Even if you are able to workaround point 1, the next issue you will face is cti.do processor executes the script even before user logs in. System uses guest account and creates the records. So if someone gets hold of these URLs, they can repeatedly access the URL in the browser and would be able to create records.

To tackle second issue, I used a little trick. 

Guest accounts will not have any roles, where as service desk agents have some role say "itil" or "u_service_desk_user" (For example if you created a custom role and grant all agents this role).

Since I know all the agents will have a role, but guest will not have the same role, we can modify the processor script to generate interaction records if the current user has expected role.

This will solve part of the problem where only intended users can create interactions using this approach.

Now we have one more problem we need to solve, when the desktop app opens the ServiceNow URL for the first time or when no other ServiceNow sessions are available, system will not create interactions and agent has to spend more time logging in and manually creating interaction records even though necessary info is available to system.

If I am able to make sure that system will get to processor only after user logs in, I will be able to solve the problem.

This is solved using a simple trick.

Instead of providing below kind of URL to IVR system:

https://<instance_name>.service-now.com/cti.do%3Fsysparm_caller_id%3DXXXXX

I asked the team external team to configure below URL.

https://<instance_name>.service-now.com/nav_to.do?uri=cti.do%3Fsysparm_caller_id%3DXXXXX

The reason why the second URL solves our problem is:
nav_to.do page requires user to be authenticated.
Hence by enclosing cti.do under nav_to.do page, we make sure that by the time processor executes the cti() function code, agent is already logged into the system.

One more point to note is: The part of the URL from cti.do is an encoded URL.

The reason for this is in Sandiego and Tokyo versions when Polaris or Next experience UI is enabled, if we do not encode the URL, it will not get converted properly and our processor will not get all necessary parameters.

Now I am adding an update set which you can apply to your fresh personal dev instance and check the business rule and script include code which is used to make this happen.

And in order to make this work, in the personal dev instance disable the "CTI Processing" out of the box global business rule.

After doing these two steps, make sure that at least some of the user profiles in your instance has Employee number field filled, and utilize below URL (replace XXXXX with employee number) to see it auto route you to newly created interaction form.

https://<instance_name>.service-now.com/nav_to.do?uri=cti.do%3Fsysparm_caller_id%3DXXXXX

Check the description field in "Custom - CTI Processor" business rule to see relevant description.

Thanks and regards,

Subrahmanyam

[Aswathigm]

@Subrahmanyam2 : Thank you for posting this.

I need to search the user with phone number and instead of employee id and create an interaction and opens the record in agent workspace. What would be the changes in the business rule to achieve this. 

Appreciate your input.

[Subrahmanyam2]

Hi Aswathigm,

In the Custom_CTI_Processor script include from update set, where ever i am calling UserGetSysId function you should make sure that you pass proper field name and the value. Then script should work. 

You may define new param like sysparm_phone and ask the team utilising cti url to send the phone in the url. And in the above pointed script include just change the logic to use new parameter instead of caller related parameter. And it should work as intended. 

Thanks and regards,

Subrahmanyam

[jiral]

This opens a new instance of the agent workspace instead of opening a new tab on already existing agent workspace instance on the agent's side. I understand that this is more of a client side but is there a way to open it in a new tab on open workspace?

[Nilofer Hasan M]

Hi, I have also similar kind requirement. Instead of Interaction, I need to open Incident record associated with User. Will this URL work for same? Thanks Nilofer

[mikeaskewacorio]

It appears when Polaris is enabled (glide.ui.polaris.experience), using the above, a duplicate interaction record is created.  One interaction record with application global and the other in Polaris app shell.  Tried this in two different PDIs and same result.  Disable Polaris and no duplicate.

[SravanKumarT]

Hi Subrahmanyam2,

I am observing 2 interactions were created with this logic. In service operation workspace page, one interaction was opening and in list view in interaction table other interaction was creating at same time.

can you help me , why it was creating like this. Thank you.

[SravanKumarT]

Hi  mikeaskewacorio,

yes when we disable this glide.ui.polaris.experience, it was creating only one interaction. 

But as we are already enabled next experience UI to all users, we can't make it active false.

Have you find alternate solution for this ?

[mikeaskewacorio]

Hi @SravanKumarT 

Short answer, using above method I NEVER did explore trying to fix duplicate issue. The requirements were quite dynamic and very short runway to turn around solution so we ended up with:

step 1: IVR would call API endpoint to create interaction record (scripting not shown). API would return interaction sysid to IVR.

step 2: The interaction sysid from step 1 would be passed into url and dropped into browser and it would redirect using CTI business rule logic below.

(Example url:

https://devXYZ123.service-now.com/nav_to.do?uri=cti.do%3Fsysparm_int_sysid%3D2eb815011be20e10895d2f4...)

CTI business rule:

====

function lookupInteraction(sysId) {

    var grInteraction = new GlideRecord('interaction');

    grInteraction.addQuery('sys_id', sysId);

    grInteraction.query();

    return grInteraction.next();

}

function cti() {

    var url = '/nav_to.do',

          interactionSysId = sysparm_int_sysid,

          isValid = false,

          isAgent = gs.hasRole('interaction_agent');

    if (interactionSysId != null && interactionSysId != '') {

      if( isAgent ){

        isValid = lookupInteraction(interactionSysId);

        url = isValid ? '/interaction.do?sys_id=' + interactionSysId : 'interaction.do?sys_id=-1',

       }

   }  

    answer = url;

    return answer;

}

(note:  the requirement for this client was to use the platform UI and not either of the workspaces.  Also this is not the exact code, I stripped out some of the client specific items)