PagerDuty Blog

Hack Your On-Call Status with PagerDuty's API

Knowing your on-call status is more important than knowing if it’s raining outside. Unlike dealing with the drizzle that’s passed over San Francisco recently, if I’m on-call you need leave the house with more than an umbrella.

Your on-call status is an integral part of PagerDuty’s iOS and Android apps. We’ve also created a few new endpoints on our REST API that make getting your current on-call status more straightforward. Full documentation of these new endpoints, as always, is on our developer documentation site.

To stayed informed of my current on-call status, I’ve hammered out a couple shell script one-liners and a JavaScript bookmarklet. You will need a PagerDuty API key to try the scripts out. These were written for a Mac OS X environment with node installed, but can be easily modified to run in other environments.

Send an Inspiration Email Reminder

Sometimes it’s useful to treat an escalation policy as a mailing list. For a particularly rough on-call rotation, this script will send an inspirational email to everyone on-call for a particular escalation policy. Animal videos are always appreciated.

A Pleasant Voice Reminder

amioncall_terminal

When you have over 50 tabs open in Chrome, more text on the screen is the last thing you need. I’ve created an alias of this script so when I type “amioncall” in the terminal Mac OS X will speak my on-call status in a pleasant voice.

Bookmarklet for your Toolbar

javascript_toolbar

I have on-call handoff notifications configured for all of my accounts, but sometimes it’s useful to know how long you have left until your shift ends. I wrote a tiny JavaScript bookmarklet that’s in my toolbar that pops up my on-call status on any page.

Hooking it All Up!

# Send an inspirational email to people on-call for an escalation policy.
# Node required, tested on Mac OS X.
ESCALATION_POLICY_ID=<enter id> ACCOUNT=<enter account> API_TOKEN=<enter token> && curl –silent -H "Authorization: Token token=${API_TOKEN}" "https://${ACCOUNT}.pagerduty.com/api/v1/escalation_policies/${ESCALATION_POLICY_ID}/on_call" | xargs -0 node -e "console.log('mailto:' + JSON.parse(process.argv[1]).escalation_policy.on_call.map(function(oc) { return oc.user.email }).join(',') + '?subject=\"Keep calm and carry on.\"')" | xargs open

// Create an on-call overlay with a user's on-call status.
// Designed to be used as a bookmarklet.
(function() {
var el = null, d = document, id = "pd-widget";
var account = "", apiKey = "", userId = "";
function createWidget() {
el = d.createElement("table");
d.body.appendChild(el);
el.setAttribute("id", id);
el.setAttribute("style","position:fixed;top:20px;right:20px;padding:20px;background:#fff;font:12px/20px monospace;z-index:99999;max-height:100%;overflow:auto;border-radius:10px;border:2px solid #000");
el.innerHTML = "<p>Loading…</p>";
el.style.display="block";
}
function render(onCall) {
var widget = document.getElementById(id);
var onCallHTML = "<h3>When am I off-call?</h3>";
onCall.forEach(function(oc) {
onCallHTML += "<p>" + oc.escalation_policy.name + " (level " + oc.level + "): " + ((oc.end && new Date(oc.end)) || "never") + "</p>";
});
widget.innerHTML = onCallHTML;
}
function fetch() {
var request = new XMLHttpRequest();
request.open("GET", "https://" + account + ".pagerduty.com/api/v1/users/" + userId + "/on_call" , true);
request.setRequestHeader("Authorization", "Token token=" + apiKey);
request.onreadystatechange = function() {
var done = 4, ok = 200, json = "";
if (request.readyState == done && request.status == ok) {
if (request.responseText) {
json = JSON.parse(request.responseText);
console.log(json.user.on_call);
render(json.user.on_call);
}
}
};
request.send(null);
}
createWidget();
fetch();
})();

view raw
on-call.js
hosted with ❤ by GitHub

# Have Mac OS X 'speak' your on-call status
# Node required.
USER_ID=<enter id> ACCOUNT=<enter account> API_TOKEN=<enter token> && curl –silent -H "Authorization: Token token=${API_TOKEN}" "https://${ACCOUNT}.pagerduty.com/api/v1/users/${USER_ID}/on_call" | xargs -0 node -e "if(JSON.parse(process.argv[1]).user.on_call.length > 0) { console.log('You are on-call') } else { console.log('You are off-call.') }" | xargs say

view raw
speak-my-on-call.sh
hosted with ❤ by GitHub