1. xMatters
  2. Products & Documentation
  3. Integrations

Embedding group schedules in notifications

Updated
Product Communications

Do your managers have a business requirement to send out upcoming group schedules to their groups? Would you like to use the LIMITLESS COSMIC POWER of the Integration Builder to generate those schedules and send them out in notifications?

If so, you may be interested in what we've put together to show off the versatility of the xMatters Integration Builder tools. This article provides a sample workflow template (and all the instructions for how to use it, of course) that takes an xMatters group name and date range as input to start the process, gathers the group schedule information via a REST API call, and then sends it all out via a second form to the xMatters group members. 

The information in this article is the intellectual property of xMatters and is intended only for use with xMatters products by xMatters customers and their employees. Further, this intellectual property is proprietary and must not be reused or resold.

What it does

The workflow attached to this article allows a group supervisor or an xMatters administrator to generate and send out the schedule to an xMatters group for a specified date/time range. The plan includes two separate forms: one form that submits the request, and a second form that sends out the group schedule as email and SMS notifications to group members. 

A note about the limitations...

  • Although you can enhance the form to reflect other time zones, the default implementation currently results in schedules in the GMT (Z for “Zulu”) time zone.
  • If the resulting group schedule is too long for an SMS text message or more than 20,000 characters for an email message, the group’s schedule will not be sent. If this happens, try again using a shorter date range.

Oh, one other thing: just for ease of reference, we're going to call this an "integration", because it really is. It's just integrating xMatters with.... well, xMatters.

How it works

Once you have imported and configured the workflow, the Request Group Schedule form will appear on the Messaging tab and in the xMatters mobile app. Group Supervisors (or the Company Supervisor) can enter the name of an xMatters group and the date/time range for which they want to retrieve a schedule.

The following screenshot illustrates how the form would appear in the xMatters mobile app. In this case, the user is requesting a five-day schedule for the Service Operations group:

MobileAppForm.png

The form sends a quick acknowledgement while it is querying xMatters via the REST API for the schedule information, and then triggers the API WhoIsOnDuty form to send the following information to each member of the Service Operations group:

Message.png

Here's a handy visual representation of how the components of the workflow work:

Picture3.png

 

How to do it

Here’s how to load the workflow and configure the hooks that correspond to your xMatters environment.

Step 1: Import the workflow

  1. Download the Get Group Schedule workflow (in a ZIP file format) attached to this article.
  • Do not extract the contents!
  • Log in to xMatters, and navigate to the Workflows tab.
  • In the list of workfows, click Import Plan, and then locate and import the downloaded ZIP file.
  • Click Edit > Forms to see the two forms that comprise the worklfow.

    • GetGroupSchedule-Forms.png

    Step 2: Add an integration user

    To make sure your forms can access the xMatters group schedules via REST web services, create a user specific to this integration. 

    This user needs to be able to work with events, but does not need to update administrative settings. While you can use the default Company Supervisor role to authenticate REST calls, the best method is to create a user specifically for this integration with a dedicated role that includes the permissions and capabilities.

    NOTE: To successfully execute some of the tasks for this integration, the integration user should also have the Group Supervisor and Full Access User roles.

    To create a REST API user:

    1. Log in to the target xMatters system.
    2. On the Users tab, click Add.
    3. Enter the appropriate information for your new user. Because this user will affect how messages appear for recipients and how events will be displayed in the reports and Communication Center, you may want to identify the user as specific to this integration; for example:
    • First Name: xmapiuser
    • Last Name: xmapiuser
    • User ID: xmapiuser
  • In the Roles area, add the REST Web Service User, Group Supervisor, and Full Access User roles.
    • If the REST Web Service User role does not exist in your deployment already, you may need to ask Customer Support to create it for you. 
  • Click Add.

    • Make a note of the user credentials and details; you will need them when configuring other parts of this integration.

    Step 3: Set the sender permissions for your forms

    1. Go back to the forms on your workflow, and for each form click the Web UI and Mobile button, and select Sender Permissions.
    2. Add the xmapiuser you created to the list of permitted senders:

    SenderPermissions.png

    Make sure you add the Group Supervisor and Company Supervisor roles to both lists, too. This will make sure that the Group Supervisors in your deployment can generate these emails as well.

    Step 4: Set the integration credentials

    The next step is to identify who's responsible for authenticating requests made to xMatters from within your integration scripts. Luckily, we just created the perfect candidate.

    1. Navigate up to the Get Group Schedule workflow, and click the Integration Builder tab.
    2. Click Edit Endpoints, and modify the preconfigured xMatters endpoint by associated it with the xmapiuser; your xMatters endpoint should look something like this:

    Endpoint.png

    Step 6: Connect the first form to the second form

    The next step is to make sure the forms can talk to each other. 

    1. In the Integration Builder, expand the list of inbound integrations, and then click the gear icon beside the Send Group Schedule for a Date Range to the Group inbound integration (catchy name, we know).
    2. In the drop-down list, select Integration URL.
    3. Copy the URL displayed in the dialog box to the clipboard:

    AccessIntegrationURL.png

    1. Click Edit Constants.
    2. In the Constants dialog box, select the Default Timezone constant and populate the value with one of the timezones listed on this page. They are also listed in the Timezone property.
    3. Then, select the InboundIntegrationURL constant, and paste the URL you copied into the Value field.
    4. Remove everything before the "/api/integration" portion of the URL.
    • Your constant should look like this:
    Constants.png
    1. Click Save Changes.
    2. Finally, click the Properties tab and edit the entries in the Timezone property. This is an exhaustive list of the timezones world wide and may not be needed for your organization. Edit this list to only include the timezones you need. Click Save Changes. 

    Test the integration

    You're now ready to test your configuration prowess!

    1. Navigate to the Messaging tab and click Request Group Schedule.

    MessageForm.png

    1. In the TargetGroup field, specify the name of the group for which you want to retrieve and send a schedule.
    2. Set the date range as follows
      • fromDate – the date of the start of the range for the schedule (Default: current date)
      • fromTime – the time of the start of the range for the schedule (Default: current time) 
      • toDate – the end date for the schedule (Default: current date +1 day)
      • toTime – the end time for the schedule (Default: current time +24 hours)
    3. Send the message!
    4. Click the Reports tab to check for new events and check the contents of the message and the recipients.
      • For example, if you specified the Service Operations group, the Events report on the Reports tab will show two events. 

    EventsReport.png

    The second event listed (the first one initiated) is retrieving the schedule and sending of the confirmation email. The first (and most recent) event is the group schedule that is sent out to the group members.

    Download the plan:

     

    Attachments
    Was this article helpful?
    0 out of 0 found this helpful

    Comments

    12 comments

    Please sign in to leave a comment.

    • Kyc
      Kyc

      Hi,


      A good alternative to on call reminder


      I wanted to use this and set up a scheduled message using the Request Group Schedule that targets the group at a specific time each day or whenever the team is scheduled to rotate. The targeted team would automatically receive that notification.


      My questions:


      - is there a way to set fromdate to today's date? I want to send the roster for the same day


      - How to enhance  the form to reflect other time zones i.e Melbourne


      Regards

      0
    • Travis DePuy
      Travis DePuy

      Hey Kyc!


         Great ideas. I've uploaded a new comm plan with a handful of changes:



      1. The toDate and toTime are no longer required and default to the current date and time respectively.

      2. The fromDate and fromTime are no longer required and default to the current date plus 1 and time plus 24 hours respectively.

      3. There is now a drop down with all of the timezones of the world for you to select. The "Default" option can be changed in the constant value called "Default Timezone". You should also edit this drop down so that it only has the timezones you really need, unless of course you need all of them! 


      I hope that helps. I made some code formatting changes that were bugging me and tweaked the html a little. 


      Let me know if that works for you!


      Happy Wednesday!
          --- Travis


       

      0
    • Kyc
      Kyc

      Hi Travis,


      Thank so much for helping and updating the code. The time works !!!


      I've imported the plan, but  the start date and end date are not quite right. 


      Start Roster: 2018-11-20 13:00:00


      End Roster: 2018-12-22 22:00:00 


       


      The idea I have on mind is to send only the roster schedule for the same date 


      Shift: M Morning - From 2018-11-23 07:00:00 TO 2018-12-20 13:00:00


      Roster 1: Start : 2018-11-24 07:00:00 End: 2018-11-24 13:00:00


      Members:


      1: John


      2: Louis


      3: Sean


      Shift : A Afternoon- From 2018-11-23 13:00:00 TO 2018-12-20 17:00:00


      Roster 2: Start : 2018-11-24 13:00:00 End: 2018-11-24 17:00:00


      Members:


      1: Carol


      2: Dave


      3: Travis


      Can you please let me know what functions need to be updated?


       


      Happy Friday !

      0
    • Travis DePuy
      Travis DePuy

      Great! Glad to hear it is useful to you and I can see this being useful to others. 


      I was digging into how that could be done and I found a glaring defect in the way "then" was being calculated. So I've attached a new comm plan that actually works. I'm not totally sure the best method for determining the "current day". Would it make sense to get the shifts from "now" to "23:59:59"?. Hopefully that makes sense. I've attached a new comm plan with the bug fix and using "23:59:59" as the default "toTime" value. 


      Let me know how that works for you!

      0
    • Kyc
      Kyc

      Hi Travis,


      The comm plan is still the old one. Can you please upload it again?


      Just an idea to determine the current date:


      fromdate=todate=currentdate - rather than using the time to determine the current date


      Thanks,


       

      0
    • Travis DePuy
      Travis DePuy

      Doh! Sorry about that. Try it now. 


      The API to get the on call shifts requires a date and time, so we'd need to sort out what time to send it. I think if we sent the whole day (midnight to midnight) it might be confusing for people who run this at 8pm or even 11pm because they would get mostly data (I'm guessing) they wouldn't care about as it was in the past. But you might have a use case where this is relevant. 


      If you'd like to send all the shift info for "today" (from midnight to midnight), then in the Launch who is on duty form change these lines on line 43:


      var now = moment( moment(), tzone );
      var then = moment( now.format( 'YYYY-MM-DDT23:59:59' ) );

      to:


      var now  = moment( moment().format( 'YYYY-MM-DDT00:00:00' ), tzone );
      var then = moment( now.format( 'YYYY-MM-DDT23:59:59' ) );

      That will default "now" to midnight this morning and "then" to 11:59 pm. This will then deliver all the shifts during that time period to the targeted group. 


      I hope that helps!

      0
    • Nicholas Stump
      Nicholas Stump

      Has any one run into this error?  Script failed with message: TypeError: null has no such function "split"


      I'm seeing it on the "Launch who is on duty form" activity stream.


      Seems to be related to the timezone settings. I'm on the east coast so I've tried 'America/New_York' and '(-05:00) America/New_York'  Am I missing something in the formatting?


       


      EDIT:  I'm also seeing the following under Reports as an Integration Problem.


       




















      15:56:52.129  

      Targeted recipient failure; none of the directly targeted recipients could be notified.
      15:56:52.880  

      Notifying xMatters Support (xm-support)
      15:56:52.890  

      xMatters Support (xm-support) has no notifiable Devices

      0
    • Travis DePuy
      Travis DePuy

      Hey Nicholas, 


         Yea, that "(-05:00) America/New_York" should work in the "Default Timezone" constant. The split is trying to split on the space before the America. In looking at these lines though I realize it is missing a comparison:


      // Full list of timezones are available here:
      // https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
      var tzone = callback.eventProperties.Timezone;
      tzone = ('Default' ? constants['Default Timezone'].split( ' ' )[1] : tzone.split( ' ' )[1] );

      So I'll have to fix that. But that shouldn't give you the error you are seeing if you have a value in the "Default Timezone" constant. 


      If you put this line before that "var tzone" line, what is the output:


      console.log( 'DEFAULT TZ: "' + constants['Default Timezone'] + '"' );

      Happy Thursday!

      0
    • Nicholas Stump
      Nicholas Stump

      Turns out I inadvertently changed the name of the Default Timezone constant, which obviously would make it return a null.  Thanks for your help!

      0
    • Travis DePuy
      Travis DePuy

      Ok, whew. The code is still broken, so if you use the timezone value in the UI panel, it will use the default anyway. I'll fix the comm plan for the future, but if you want to fix it now, change this:


      // Full list of timezones are available here:
      // https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
      var tzone = callback.eventProperties.Timezone;
      tzone = ('Default' ? constants['Default Timezone'].split( ' ' )[1] : tzone.split( ' ' )[1] );

      to this:


      // Full list of timezones are available here:
      // https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
      var tzone = callback.eventProperties.Timezone;
      tzone = (tzone && tzone == 'Default' ? constants['Default Timezone'].split( ' ' )[1] : tzone.split( ' ' )[1] );

      That makes sure tzone is populated and if 'Default' was selected, then go get the Default value from the constant, otherwise extract it from the value they selected. 


      (Comm Plan updated)

      0
    • Ian Clark
      Ian Clark

      Just an fyi for anyone that may still be getting stuck on the timezone being undefined, I noticed that the property is not set to "include in outbound integration". Just go to the form layout and change the property. It should work after all of the above changes were made to the code.

      0
    • Travis DePuy
      Travis DePuy

      Thanks for the heads up Ian! I hope you didn't pull out too much hair tracking that one down. Hopefully your follicle sacrifice will help prevent future sacrifices. 


      I've uploaded a new version with ALL the outbound checkboxes checked. 

      0