GIG: Shared Libraries are here!

Master Chef loves presents. Especially presents coming from the xMatters engineering elves in the great white north. The xMatters elves were hard at work this past quarter packing stuff into the Rogue One release, and one such gem was the Shared Libraries. Oooo, Ahhh. Let's explore these libraries in a little more detail and see what kinds of cool stuff we can do with them. 

One of the biggest challenges in working with JavaScript is in dealing with dates and times. Anyone who's done anything related to formatting, adding, validating dates or times or dealing with timezone offsets will know how much "fun" it is to deal with dates and times. 

Fortunately, there is hope. Moment.js is a fully blown library complete with everything we need to do anything you can think of with dates. 

To give some context, we'll take Jordan's script for Text to Speech friendly date/times over on the Script Cookbook and see what it looks like using moment.js instead. Take a moment to check out the script over there. Jordan did a lot of work to parse out a date/time value from XML and spit out something a text to speech engine can reliably pronounce. So you can copy and paste all that code into all your integration scripts, or you can use moment.js and Shared Libraries once and wash, rinse, repeat.

Navigate over to your favorite Communications Plan and click the Integration Builder tab. You'll notice there is a new section below the Inbound and Outbound Integrations for Shared libraries. You can click the Add button here, but I find the shared libraries are much easier to work with from within an inbound or outbound integration. So let's jump into an existing Outbound integration and open the Script Editor. On the lower right side, there is a new button for adding a shared library. Click that and you'll see a fresh new Shared Library in a new pane, next to the existing script. Like so:

The comments have some very helpful information on how to work with shared libraries, but for now, we'll just overwrite them. Open up the minified version of moment.js by clicking here. Copy the entire contents of that page and paste it into your new shared library. Then click in the My Shared Library title at the top and change the name to moment. Then hit save. When you're done, it should look like this:

You can hide that Shared Library now, as once the script is saved, we'll just reference it. 

At the top of the integration script add this line:

var moment = require('moment');

This makes the entire moment.js library accessible as moment. Moment has taken all the work Jordan did and all we have to do is parse the XML date and then format. We can even do this in one line:

var spokenDate = moment( "2016-08-14T11:58:24-05:00", "YYYY-MM-DDTHH:mm:ss-HH:mm" ).format('MMMM Do YYYY [at] h:mm:ss a');

Not bad! 

One of the other common things to do is to change timezones of a particular date/time value. The Moment Timezone library can handle this pretty well. Just paste this file into a new script library and name it moment-timezone. Then, after the require line for moment, add another line to make it look like this:

var moment = require('moment');
require('moment-timezone');

The moment-timezone library adds functionality to the moment library, so we shouldn't set it to a variable. Now, you can have any date/time value displayed in a different timezone. For example, to show the current time inPacific and Eastern:

moment().tz('America/Los_Angeles').format();
moment().tz('America/New_York'   ).format();

Pretty slick! To see the rest of the cool stuff you can do with moment.js head over to momentjs.com and scroll down. They have all kinds of examples, and even have the moment variable available in the browser console. So you can test out snippets right in the browser!

These shared libraries will also let you reuse code across inbound and outbound integrations. For example, bolting on a couple of HipChat or Slack libraries can quickly add functionality to create a room or send messages to any parts of any Communications Plan. 

Have you found a good use for Shared Libraries? Any cool reusable code snippets you want to share? Post in the comments and we can discuss!

Thanks for reading! 

Update: What about Flow Designer?

As of the end of 2020, Flow Designer doesn't allow "nested" Library scripts, meaning Library scripts that invoke other Library scripts.  Since the Moment timezone library depends on moment.js, this means that the instructions above will work only with Integration Builder scripts and not with Flow.

However, we have been able to combine the timezone code into the main moment.js script, so you can add timezone functionality into your Flows.  Just use the above instructions in your Flow Designer script, with the following changes:

1. When creating your moment Library in Flow Designer, use the contents of the attached "momentjs-with-timezone.js" file.
2. Omit the

   require('moment-timezone');

   instruction from your script.

That's it!

You can learn more about Flow Designer Libraries here.

Keep in mind that "momentjs-with-timezone.js" is a static file, so any bug fixes or features that get added to the online moment.js won't get added to the attachment.