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:

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:

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

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!

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

• 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. 

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:

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:

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:

4. Click Edit Constants.
5. 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.
6. Then, select the InboundIntegrationURL constant, and paste the URL you copied into the Value field.
7. Remove everything before the "/api/integration" portion of the URL.

• Your constant should look like this:

7. Click Save Changes.
8. 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.

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. 

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: