Lauren Palmer
Tera Contributor

Hi Folks, 

I've done some research and looked into adding a UI Macro button onto our incident form for our technicians to start a new Teams chat with that specific caller. I drew information from a previous post on the community. I'll walk you through the steps I took to add in more content to the chat integration. I am a SN Admin, self-taught developer. If you're sitting in a similar seat as me, you can most definitely tackle this small project and add in a cool integration for your team! 

We will be using a Microsoft Deep Link to create a Teams chat. If you haven't heard of this, take some time to read the Microsoft doc. The basics of the Deep Link is to pass parameters through a URL to open a new Teams chat (in browser or on your desktop client - this is set by users). I will be using the "users" and "message" parameters to auto-open a chat with a specific user and prepopulate the message content of that chat. 

Don't forget to create an update set for the changes you're about to make!

Adding Icon to System UI Images:

Add the Teams Icon to ServiceNow (or create your own icon). 

  1. Go to System UI > Images
  2. Create a new Image and call it "teams.png", make sure the image is active and tagged under the appropriate category.
  3. Note the height/width of your image - you will want something smaller for the icon size

find_real_file.png

 

Create New UI Macro:

We will create a new UI Macro that will generate the Deep Link URL based off the parameters we want to pass through to Teams. 

  1. Navigate to System UI > UI Macros and create a new UI Macro
  2. Name the UI Macro "teams_chat"
  3. In the script section, enter the following:
<?xml version="1.0" encoding="utf-8" ?>
<j:jelly trim="false" xmlns:j="jelly:core"
xmlns:g="glide" xmlns:j2="null" xmlns:g2="null">
<a class="btn-default;" id="${jvar_n}" onclick="invokeChat('${ref}');">
              <img src="teams.png" width="30"  title="Teams Chat" alt="${gs.getMessage('Click to open Teams chat')}" />
</a>
<script>
function invokeChat(reference) {

var prefix = 'https://teams.microsoft.com/l/chat/0/0?users=';
var firstname = g_form.getReference('caller_id').first_name;
var user = g_form.getReference('caller_id').email;
var subject = '&amp;amp;message=Hi ' + firstname + ', this is regarding your Incident ' + g_form.getValue('number') + ': ' + g_form.getValue('short_description');

var w = getTopWindow();
var url = prefix + user + subject;
w.open(url);
}
</script></j:jelly>

A couple of notes about the code:

  • In the first section within the <a> tag we create our button. The title tag is the text that displays when you hover over the button. 
  • Within the <script> tag, we execute creating the URL through gathering the incident attributes we want to pass through.
  • For my personal use case, I only wanted to create a chat with the singular Caller on the Incident. The "g_form.getReference('caller_id').first_name" looks at the current form, gets the caller information and then uses the reference to gather the first name from the sys_user table. I used the same method for the email address. 
  • For the subject, if you look back at the composition of the Deep Link URL, you'll notice that you will need to append the URL with a "&message=Your message text" to add in the prepopulated content in your Teams chat. I found this part a little troublesome, but realized the ampersand needed to be converted to "&amp;amp;" to pass it through the XML.  That's why you see it in the "var subject = '&amp;amp;message=Hi ' + firstname + '," variable. 
  • If you want to add/remove information from the message text, continue appending the "subject" variable until you're satisfied. 

find_real_file.png

 

Edit the Caller field Dictionary Entry

We'll now go to the Incident form and edit the attributes for the Caller (caller_id) field on the Incident table to show our new UI Macro Teams button.

  1. Navigate to Incidents, open the form, right click on the Caller label and go to Dictionary Entry. You can also go to System Definition > Tables, open the Incident table and select the Caller field.
  2. In the Attributes box, add the name of our new UI Macro to the "ref_contributions=" list. (For more info on the Reference Contribution Attribute, check out Dictionary Attributes). 

find_real_file.png

 

Once we've added the UI Macro to our Attributes list on the Dictionary Entry, we should now be able to access our new button on our Incident form. 

To test your new form, open an Incident record and click your button. You may have to set some defaults upon initial use (to use the web app or local desktop app). 

find_real_file.png

find_real_file.png

Good luck, and if anyone knows how to bypass keeping the URL windows open, let me know!

Comments
praveenKumar2
Kilo Expert

Hi Lauren,

Thank you for an amazing article. 

Currently the teams pop up is shown in a new page, Can the pop-up be shown on the same page? Also can the conversation for the incident be updated to the incident ticket ?

 

Please let me know if it is possible.

Thanks in advance 🙂

pK

Servicenow10
Kilo Guru

very helpful post.

also if possible kindly share reverse integration without plugin.

Lauren Palmer
Tera Contributor

Hi PK!

 

One of the limitations with using a Microsoft Deep Link was the "one-way" integration. I couldn't figure out a way to prompt opening the conversation straight in the Teams desktop application or in the current browser window. 

 

As for updating the conversations back to the incident, I believe this is more suited for the Virtual Agent in ServiceNow. That's something on my company's roadmap for future state. I believe you can use the Virtual Agent with a Teams integration to get a seamless experience between IM updates to your users, with automatic updating of the Incident's activity. 

 

Good luck!

 

Lauren

Lauren Palmer
Tera Contributor

Hi Dell, I am not sure what you mean for the reverse integration without a plugin. Could you tell me more? 

Thanks,

Lauren

Servicenow10
Kilo Guru

hi lauren,

 

actually am working on one task where am trying to log an incident in service-now through teams and your post was very helpful.

 so in my scenario if end user interacts with servicenow teams id and if that user wants to raise an incident in servicenow through so how to achieve this.

 

with chatbot plugin is possible but i have to achieve this without plugin so not sure how to proceed.

 

thanks.

Paul Curwen
Giga Sage

To get it to go straight into a Teams call replace line 10 in the UI Macro with this:

 

var prefix = 'msteams:/l/chat/0/0?users=';

 

This way opens straight into the conversation 🙂

Lauren Palmer
Tera Contributor

Amazing, worked perfectly in my test instance! Thank you, Paul!!

Jai11
Kilo Contributor

We tried it in our instance. The only problem I am getting is, it does not open a new chat window in MS teams with the Subject etc. Has anyone else faced this issue?

rajeev17
Mega Guru

Hi Jai

Try this script in your UI macro

var subject = '&amp;amp;message=Hi ' + firstname + ', this is regarding your Incident ' + g_form.getValue('number') + ', Short Description : ' + g_form.getValue('short_description');

var w = getTopWindow();
var url = prefix + user + subject;
w.open(url);

Thanks

Rajeev

 

Jai11
Kilo Contributor

Hi Rajiv, Thank you for replying but I see this code is same as provided above. I dont see you have provided value for prefix variable. Is that something different. I have tried this and does not open a new chat window still. Thanks Jai

ABSG-001
Tera Expert

I tried it on my instance with incidents and it worked like magic, thanks.

However when I tried to implement on my instance with service catalog(requests), it works on some requests and doesn't work on some.

Any suggestions please?

ABSG-001
Tera Expert

Thanks Paul

neelarajesh
Kilo Contributor

Hi,

Do we have a similar type of integration with slack? If so ,could any post the UI macro code  

MT247
Tera Expert

This is really great!

Is there a way to enhance the code to check for the caller_id preferred language and compose a message in the user preferred language?

 

Mr John
Tera Contributor

Does this require an integrationhub transaction - If SN makes a call/transaction to an external system it uses up one of our licences.

What was the original scope? Just to put it on incident records? We may use it on a wider scale.

Paul Curwen
Giga Sage

No this does not require an integration hub transaction.

If you are on Quebec, or moving to Quebec then there area load of great new Teams features OOTB including the ability to instigate a MS Teams chat from the form (subject of this post) and also bring in the Teams chat content to your ServiceNow record. For info see: 

https://docs.servicenow.com/bundle/quebec-employee-service-management/page/product/sn-teams/concept/...

Bharath40
Giga Guru

I'm able to open teams chat from ServiceNow for user that I have chat already created but not for any new

user. I get below error. What am I missing here

find_real_file.png

keshavsingh
Tera Contributor

@Lauren Palmer Thanks for the post, but can we start new chat window with the user where old chat history is not there in stead of opening the existing chat window with old chat history. 

Please let me know if you have a solution for this.

 

Thanks

Keshav

Sreedhar Mamill
Giga Expert

@Lauren Palmer  I tried the same on my PDI, but unfortunately it is not working at all. I'm not even getting the image. Any help/advice would be appreciate.

Version history
Last update:
‎01-08-2020 10:00 AM
Updated by: