Using Twitter For Service Outage Awareness

Emily Clasper of the Suffolk County Library posted about some work she had done to embed status messages in the catalog using Twitter. This sounded like a really great idea because it is an out-of-band (e.g. something that doesn't rely on OhioLINK infrastructure for reporting downtimes) way to get messages to member staff and users. But I didn't get a chance to work on my implementation for a while, so for over a year ideas have bubbled around in my head about ways to apply this technique and improve on it. I finally carved out some spare time to actually work on it, and came up with my take on the concept. The result is the OhioLINK Status-Via-Twitter service.

In Emily's approach to putting messages on public pages, the staff would first post a message to the public status Twitter account which would then be turned into a block of HTML inserted into the public catalog page via JavaScript. The JavaScript would query the feed for the public status Twitter account and insert any tweets found there into the page. When the information in the tweet is no longer needed, the library staff would delete the tweet.

In my conceptualization of this service, there would be individuals or agents other than the catalog JavaScript code that would be looking to the tweet stream for updates on services. Those individuals and agents won't know when a tweet is deleted, so an "all-clear" message needs to be posted to the tweet stream for those consumers. And, of course, we wouldn't want an "all-clear" tweet to be posted ad infinitum (or at least until the next service message) on public web pages.

I would also like to include the tweeted service messages on all pages on our site, not just the homepage. But if we do that, then every page hit for one of our users would hit the Twitter API to get the tweets from the public status Twitter account...with possible privacy and capacity overloading concerns. So there would need to be a way to cache messages from Twitter for a period of time.

In bulleted-point form, what I was looking for was:

• A bit of JavaScript that would dynamically insert HTML into a
  tag that contains the text of tweets.
• The script would not display tweets that contain a set phrase (e.g. "returned to normal") or were older than a pre-defined period.
• The script would cache messages as cookies and only read new messages from Twitter after a pre-defined period of time.
• The script had to be compact and self-contained (e.g. not rely on external JavaScript libraries) for speed and simplicity.

The Implementation

What I ended up doing was adapting JavaScript code by Remy Sharp from his twitterjs project. Modifications include the ability to pass a parameter to limit the number of hours a tweet will be shown before it is ignored (the ignoreOlderThan parameter) and to truncate the display of tweets if a particular string is used (the stopIfSeen parameter) as well as the caching function. The code is posted on GitHub at http://github.com/dltj/twitterjs.

The bottom of 'twitter.js' in the OhioLINK-Prod branch of the twitterjs project has an example of how to configure the JavaScript function. It looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

getTwitters('ohiolinkstatus', {       // <div> to insert text
  id: 'OhioLINKstatus',               // Twitter id
  count: 20,                          // Maximum number of tweets to show
  ignoreReplies: true,                // Ignore @-replies (true or false)
  ignoreOlderThan: 36*60*60,          // Ignore tweets older than this (in minutes)
  stopIfSeen: 'returned to normal',   // Stop display tweets if this text is in tweet
  cookiePrefix: 'TwitterJS',          // Preface cookies with this prefix
  cookieDomain: 'dltj.org',           // Cookies stored for this domain
  cookieRefresh: 5                    // How often to check tweets (in minutes)
});</div>

To make this work on your pages, you'd need to follow these steps:

1. Download the twitter.js file from GitHub. At the end of this file, add the configuration to match your needs. At a minimum, change cookieDomain to match the domain of your website, or this won't work. You probably also want to change the id unless you want to monitor OhioLINK services. ((Note that at the time this is being posted, OhioLINK is not using this in production so don't rely on this Twitter ID for actual outage messages.))
2. Download the CSS file for twitterjs and modify to your tastes.
3. (Optional Step) Run your JavaScript through JSMinify to reduce its size to increase website performance. Do the same for the CSS file.
4. Upload the JavaScript and CSS files to your website.
5. Add these lines to the section of any page you want to use this:

   1 2	<link rel="stylesheet" href="http://your.host.name/your.directory/twitter.css" type="text/css" media="screen" charset="utf-8" /> <script src="http://your.host.name/your.directory/twitter.js" type="text/javascript" charset="utf-8"></script>

6. Add this line to the section of the document where you want the tweets to appear:

   1	<div class="twitters" id="ohiolinkstatus"></div>

   Be sure the id attribute value matches the first parameter of the getTwitters() function call in the first step.

getTwitters() will run the main body of code after the page is finished loading. If it finds a twitterjs cookie for the current domain, it replaces whatever is inside the