Instructions for setting up integration from ServiceNow to xMatters via IntegrationHub
Switch branches/tags
Nothing to show
Clone or download
Pull request Compare This branch is 2 commits ahead of michael-sorenson:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
media
EmailMessageTemplate.html
ExampleCommPlan.zip
LICENSE
PayloadBody.png
README.md
ServiceNowIntegrationHub.zip
UpdateSet.xml

README.md

ServiceNow Inbound (to xMatters) Integration via IntegrationHub

IntegrationHub is a feature in ServiceNow that makes integrating to third-party (in this example, xMatters) apps easier than ever before, and the best part about it? No coding! Well, at least minimal... With this inbound integration, you can set up a trigger from any (that's right, any!) table and table entry to create an event in xMatters.

Pre-Requisites

  • ServiceNow instance, with IntegrationHub purchased and installed - if you don't have IntegrationHub, see details on how to get it here
  • Existing communications plan - Use this packaged integration from the integrations page, or build your own
  • xMatters account - If you don't have one, get one!

Files

How it works

Add some info here detailing the overall architecture and how the integration works. The more information you can add, the more helpful this sections becomes. For example: An action happens in Application XYZ which triggers the thingamajig to fire a REST API call to the xMatters inbound integration on the imported communication plan. The integration script then parses out the payload and builds an event and passes that to xMatters.

Installation

In xMatters:

Setting up the Communication Plan

  1. Download the zip file onto your computer
  2. Log in to xMatters and navigate to the DEVELOPER tab
  3. Click Import Plan and select the zip file you just downloaded, then click Import Plan
  4. On the righthand side of the Communication Plan you just imported, click Edit > Integration Builder
  5. Next to Inbound Integrations, open the dropdown menu by clicking the blue 1 Configured, then click ServiceNow IntegrationHub Inbound
  6. At the bottom of the page, copy the request URL to something accessible

Setting up an account to access the Communication Plan

  1. Navigate to the USERS tab
  2. Click Add on the righthand side
  3. Give the user a first and last name (e.g. ServiceNow IntegrationHub), user ID (username used for logging in) and password, and give it the REST Web Service User role, then click Add
  4. Navigate back to the DEVELOPER tab and next to the Communication Plan you just imported, click Edit > Access Permissions, then type the user ID of the account you just created, select the account, and click Save Changes. Alternatively, you can select Accessible by All, however this allows all users in your xMatters instance to view and edit the Communication Plan

In ServiceNow:

Option 1: Setting it up yourself

Setting up a Credential and Connection Alias:

Now that you have an xMatters Communication Plan, we need to set up a Connection alias in ServiceNow to connect quickly and easily to the Comm Plan

  1. Log in to your ServiceNow instance

  2. In the Filter navigator, search for "alias", and select Connection & Credential aliases

  1. In the top left next to where you see Connection & Credential aliases, click New
  1. In the dropdown menu next to Type, select Credential, then give the Credential a Name, and hit Submit
  1. You will now see a list of Connections and Credentials; click (or search if you have many set up) the Credential you just created

  2. Next to Credentials (right below the Credential Name and Type), click New, and select the Basic Auth Credentials option on the following page

  1. Give the Credential a Name, and enter the User and Password for the xMatters account with access to the Communication Plan, then click Submit to finish
  1. Now that you have a Credential, click the back button to return to the list of Connections & Credentials, then hit New
  1. This time, in the dropdown menu next to Type, select Connection and Credential, and in the dropdown menu next to Connection Type, select HTTP, then give the Connection a Name, and click Submit
  1. You will again see a list of Connections and Credentials; click (or search for) the Connection you just created
  2. Next to Connections (right below the Connection Name and Type), click New
  1. Give the Connection a Name, then click the Credential, and select the Credential that you just created
  1. Paste the URL you copied from the xMatters Communication Plan into the Connection URL box, then Submit

Now you have a working Connection Alias that we can use to easiliy communicate to xMatters! Now for setting up an Action

Setting up an Action

  1. In the Filter navigator, search for "flow", and under Flow Designer, click Designer
  1. You should see a list of flows. On the righthand side, click New > New Action
  1. Give the Action a Name and Description, then Submit

  2. In the Inputs, click Create Input, and give the input variable a name, then select the type and the table from which the input will be grabbed (for example, an input of type Reference from the table Incident [incident])

  1. Now for the magic. Between the Inputs and Outputs, click the + button to add a step. Click on REST Step (Note: you must have IntegrationHub installed for this to be available)
  1. Next to Connection, leave the default of Use Connection Alias, then select your Connection Alias in the dropdown menu next to Connection and Credential Alias
  1. From the dropdown menu next to HTTP Method, select POST (the Base URL is grayed out because it is already defined in the Connection Alias). We will not need to fill anything in for Resource Path in this example because the full URL from the Communication Plan is in the Connection Alias. However, if you would like to set up multiple integrations using IntegrationHub, it may be a good idea to define the URL in the Connection Alias as being https://example.xmatters.com/api/integration/1/functions/ (with example being replaced with your instance), and then you could create multiple inbound integrations and have different actions use different inbound integration URLs by using the same Connection alias, and only change the Resource Path to [API key]/triggers .

  2. For headers, use Content-Type under Name, and application/json under Value

  3. Under body, you will have to enter each part of the input you would like to send to xMatters (this part isn't so much fun...). Here is a good example of an input body:

  1. Once you are happy with your body, hit Save in the top right, and then Publish (if you don't publish, you will not be able to see your Action when you are creating your Flow!)

Setting up a Flow

  1. Now that you have an Action created, it is time to define a Flow. Next to the tab of your newly created Action, click the + button, and select New Flow
  1. Give your Flow a Name and a Description, then click Submit
  1. Under Triggers, click Click to add a Trigger, and select the kind of Trigger you want (for example, use Created or Updated to fire the Flow whenever a table entry is created or updated, combined with whatever conditions you define).
  1. Add any conditions you would like to add (for example, Assignment group => changes would fire the action or flow logic whenever an incident is created or updated where the assignment group changes), set Run Triggers to Always, then click Done
  1. Now that you have a Trigger, you can add the Action using the Trigger as the input. Click Click to add Action or Flow Logic, select the Action you just created, then use the Data Pill Picker to select the Trigger input, and click Done to save it

There you have it! Once you have made all the changes you want to the body and the trigger, make sure to test your flow with the Test button, using any incident to test the integration, then hit Save and Activate to activate your integration!

Option 2: Installing an Update Set

  1. Download the update set

  2. Log in to your ServiceNow instance

  3. In the Filter navigator, search for "update sets", and under "System update sets", click "Update Sets to Commit"

  1. Under Related Links, click Import Update Sets from XML
  1. Click the Choose file button, select the update set you downloaded and click Open. Next, hit the Upload button.
  2. Now you should see a list of retrieved update sets. Click on the update set IntegrationHub Demo, then click Preview Update Set
  1. After the preview loads, click Commit Update Set to add the update set to your ServiceNow instance

  2. Now you should have an example Connection, Credential, Action, and Flow. First, using the Filter navigator, search for "alias" and click Connection and Credential alias

  1. Click on Example Credential, then click on xMatters Example under the credentials list
  1. Change the Username and Password to the account that can access the Communication Plan in xMatters, and then click Update
  2. Click the back button, and open the Example Connection, then click New next to the Connections list
  1. Give the Connection a Name, select the Credential you just changed, then fill in the Connection URL with the URL from your xMatters Communication Plan, and click Update
  1. Search for "flow" in the Filter navigator, and under Flow Designer, click Designer
  1. Search for "Example" and click on Example Flow, then click Edit Properties, and rename the Flow
  1. Click on the trigger [Incident] Created or Updated and set the table to whatever table you would like to grab the input from. Now, set the trigger to what you would like it to be, then click Done
  1. Click the Home button in the top left, then click on Actions, and search "Example", selecting Example Action, and rename the Action using Edit Properties
  1. Change the input to the same table as the one selected in the Flow, then click on the REST Step
  1. Verify that the correct Connection and Credential Alias is selected, then edit the body to send the desired values over to xMatters (see Troubleshooting section for more help on this) There you have it! Make sure to hit Publish on the Action to commit the changes you make, then use the Test button in the Flow to troubleshoot body errors

xMatters set up

Change the endpoint

  1. Navigate to the DEVELOPER tab, and locate the ServiceNow IntegrationHub Comm Plan
  2. Next to the Communication Plan, click Edit > Integration Builder
  3. Click Edit Endpoints, then click ServiceNow
  4. Change the Base URL to the URL of your ServiceNow instance
  5. Hit Save Changes then Close

Change the default recipients

  1. Open the Inbound Integrations dropdown, and select ServiceNow IntegrationHub Inbound
  2. Click Open Script Editor near the center of the page
  3. Navigate to line 21, and change the Default Recipients to the name of the xMatters group you would like to notify by default
  4. Hit Save. Your IntegrationHub flow will now fire to xMatters and notify your default recipients with the response options defined in the form! Happy Integrating!

Testing

To test the Flow, you can use the Test button and add an input incident, then in xMatters navigate to the communication plan and hit Edit > Integration Builder, then on the righthand side of the Inbound integration to ServiceNow IntegrationHub, click the gear icon and select Activity Stream. In the Activity Stream, you should be able to see a successful POST and an email should be sent to the recipients.

Troubleshooting

The most difficult part about setting up an integration with IntegrationHub using the "Content-Type: application/json" header is definitely setting up the body. Using the click and drag GUI has its advantages, but it makes the body very difficult to reproduce. Some pointers:

  1. Make sure the format is
{"recipients": "[Recipient group]",
"properties": {
"[Property 1 name]": "[Property 1 value]",
"[Property 2 name]": "[Property 2 value]",
.....
"[Property n name]": "[Property n value]"
}}

Each [property name], you can type in yourself, but each [property value], you have to set it up with two double quotes (e.g. "assignment_group": ""), place the cursor between the two double quotes, then click and drag the property value (dropdown menu under incident > click and drag "assignment group" to the cursor)