Teams Integration with Incidents - Start new chat from Incident form using Microsoft Deep Link and UI Macros

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).

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

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.

Navigate to System UI > UI Macros and create a new UI Macro
Name the UI Macro "teams_chat"
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 tag we create our button. The title tag is the text that displays when you hover over the button.

Within the tag, we execute creating the URL through gathering the incident attributes we want to pass through.</li> <li>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.</li> <li>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;" to pass it through the XML. That's why you see it in the "var subject = '&amp;message=Hi ' + firstname + '," variable.</li> <li>If you want to add/remove information from the message text, continue appending the "subject" variable until you're satisfied.</li> </ul> <img src="https://community.servicenow.com/community/image/serverpage/image-id/89596i44EA415112F0A0D5/image-size/large?v=v2&px=999" alt="image"> 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. <ol> <li>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.</li> <li>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 <a href="https://docs.servicenow.com/bundle/newyork-platform-administration/page/administer/reference-pages/concept/c%5FDictionaryAttributes.html" target="_blank" rel="noopener">Dictionary Attributes</a>).</li> </ol> <img src="https://community.servicenow.com/community/image/serverpage/image-id/89594iD94A58DB4A744421/image-size/large?v=v2&px=999" alt="image"> 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). <img src="https://community.servicenow.com/community/image/serverpage/image-id/89599i0E67365BC27F8060/image-size/large?v=v2&px=999" alt="image"> <img src="https://community.servicenow.com/community/image/serverpage/image-id/89598i3A2F8DC8BE380530/image-size/large?v=v2&px=999" alt="image"> Good luck, and if anyone knows how to bypass keeping the URL windows open, let me know!