GIG: Embedding custom URI links in notifications

Ok, so you've got your Major Incident team all ready and waiting and you've gone over the plan and all the tools are hooked up and QA'd... now you wait.... and before long it happens. The P1 Incident comes in and you jump into action. The customer facing site is down and no one can login. But you're cool, calm and collected because this isn't your first rodeo and you've got all the cool tools hooked up and talking. The notifications all go out and the Database and Network teams are notified. But then it happens. They can't get into the Slack/Hipchat/Spark channel because there is no link in the notification so they have to open the app, scroll through the list of 1000 channels or rooms. OH NO! 😱

Fortunately, there's a solution. We can create a touchable/clickable link that will launch the correct app on a mobile device, or even a mac or PC. Check in after the break to see how this magic happens. 

We're going to use a concept of Deep Linking which is just a semi-fancy way of saying we're going to generate a link directly to the a room/channel. Apps can publicize their url schemes such that when clicked (or touched) they open a specific application instead of just the web browser. For critical notifications, this can help people get into the room and resolving issues faster when they don't have to hunt down the app, then hunt down the room. 

Slack and HipChat have their own schemes, doc'd here and here respectively. Searching the googles for "XYZ deep linking" or "XYZ uri scheme" will generally get you the info you need for a specific application. We'll just cover Slack and HipChat here. 

The format for Slack is:

slack://channel?team={TEAM_ID}&id={CHANNEL_ID}

 The TEAM_ID is a unique identifier for the Slack team and the CHANNEL_ID is the ID of the channel. Unfortunately, we can't just do slack://channel?team=myteamhere&id=p1-incidents-room, we need to get these ID from the Slack API. Fortunately, the Slack shared library on github has all the functions we need. Once you have this shared library saved in your Integration Builder, you can add these couple of lines to your script:

// Set the channel name. This could come from the incoming request
// as data.incident_number for example
// The encodeURIComponent helps make sure there aren't any invalid characters
var channelName = encodeURIComponent( 'p1-incidents-room' );

// Grab the Slack shared library, get the team details, then get the channel details
var Slack = require( 'Slack' );
var team = Slack.getTeam();
var channel = Slack.getChannel( channelName );

// Build a couple links. One is the standard web link, the other is the slack uri
trigger.properties.chat_link        = 'https://' + team.name + '.slack.com/messages/#' + channelName;
trigger.properties.chat_mobile_link = 'slack://channel?team=' + team.id + '&id=' + channel.id;

HipChat is actually a lot easier. This is the format for the HipChat scheme:

hipchat://[fqdn]/room/[room_id_or_display_name]

So to build a deep link:

var teamName    = 'myteam';
var channelName = encodeURIComponent( 'p1-incidents-room' );
trigger.properties.chat_link        = 'https://' + teamName + '.hipchat.com/chat/room/' + channelName;
trigger.properties.chat_mobile_link = 'hipchat://' + teamName + '.hipchat.com/room/' + channelName;

The final piece is to include these links in the notifications. In my testing I found the xMatters mobile app would not detect these as actual URLs, so I had to embed them in anchor (<a>) tags. So when I go and edit my message template, I dive into the source and add some anchor tags. I find it helpful to drag the properties to roughly where I want them so I just have to copy/paste the API reference. 

 <br><a href="${7044b852-d695-4c3b-bb95-abb4567e717a}">Chat Link</a>
 <br><a href="${7a485034-9621-4d01-ae97-0a1b52f555ad}">Mobile Link</a></td>

Where the value for Chat Link is the chat_link property and the value for Mobile Link is chat_mobile_link.

You can use this little trick for any application that publishes a URI scheme, the tricky part is gathering all the pieces and building the URI it self. Some quick googling and a little script fu will get you there. Post back in the comments if you find any others!