Moogsoft Incidents

1. In Moogsoft, go to Integrations > Outbound Integrations and select Webhook from the menu.

   

2. Click Add a Webhook.

   

3. In the Name and Scope section fill in the following fields:
   • Name: Give the webhook a name (for example, xMatters).
   • Type: Select Incident from the drop-down menu.

     

4. In the CREATE Operation and HTTP Configuration section fill in the following fields:
   • Request Method: Select POST from the drop-down menu.
   • URL: Paste the trigger URL you copied from Flow Designer. Add the target names of any recipients you want to notify when the alert fires.
     • For URL authentication, use an ampersand to attach recipients. For example, if you want to notify Emma Pearson and the on-call members in the group responsible for the Antares service, you'd add &recipients=epearson,antares to the URL.
     • For other authentication types, use a question mark to attach recipients. For example, if you want to notify Barry Gull and the on-call members in the group responsible for the Cassiopeia service, you'd add ?recipients=bgull,cassiopeia to the URL.
     • You must URL-encode any special characters or spaces in the target names.

   

5. In the Payload Body for CREATE Operation section, set the payload as:
   Copy

   {
   "timestamp": "$created_at",
   "location": "$tags.region",
   "severity": "$severity",
   "id": "$id",
   "description": "$description",
   "services": $services,
   "status": "$status",
   "totalalerts": "$total_alerts",
   "signalMode": "New",
   "assignee": "$assignee",
   "correlationDefinition": "$correlation_definition",
   "incidentURL": "$incident_url"
   }
   

6. In the UPDATE notifications section fill in the following fields:
   • Turn on the Enable update notifications toggle.
   • Request Method: Select POST from the drop-down menu.
   • URL: Paste the trigger URL you copied from Flow Designer. Add the target names of any recipients you want to notify when the alert fires.
     • For URL authentication, use an ampersand to attach recipients. For example, if you want to notify Emma Pearson and the on-call members in the group responsible for the Antares service, you'd add &recipients=epearson,antares to the URL.
     • For other authentication types, use a question mark to attach recipients. For example, if you want to notify Barry Gull and the on-call members in the group responsible for the Cassiopeia service, you'd add ?recipients=bgull,cassiopeia to the URL.
     • You must URL-encode any special characters or spaces in the target names.
   • Triggers: turn on the toggles for type of updates you'd like to receive notifications for.

   

7. In the Payload Body for UPDATE Operation section, set the payload as:
   Copy

   {
   "timestamp": "$created_at",
   "location": "$tags.region",
   "severity": "$severity",
   "id": "$id",
   "description": "$description",
   "services": $services,
   "status": "$status",
   "totalalerts": "$total_alerts",
   "signalMode": "Update",
   "assignee": "$assignee",
   "correlationDefinition": "$correlation_definition",
   "incidentURL": "$incident_url"
   }
   

8. Optional: To test the webhook, go to the top of the Outbound Webhook page and click Test.

   

9. Click Save.

You're ready to use the webhook to trigger automated flows, including steps such as sending alerts and initiating incidents, though we always recommend testing before putting things into use. To keep things tidy in Moogsoft, we recommend using the Correlation Engine to combine similar incoming alerts into Moogsoft incidents.

Configure Correlation Engine

1. In Moogsoft go to Correlate & Automate > Correlation Engine.

   

2. Click Add Correlation Definition.

   

3. In the Construct Your Incident Description section fill in the following fields:
   • Correlation Name: Give the correlation a unique name.
   • Incident Description: Set the correlation description. The description displays for all incidents created by this correlation definition.

   

4. In the Definition section, set the Scope of the correlation to match all alerts or only alerts that match the filter parameters, then click Add Field.

   

5. Optional: In the Advanced section you can set duration for the Correlation Time Window and select the minimum number of similar alerts before an incident is created.

   

6. Click Save.

The correlation engine will create Moogsoft incidents from the incoming alerts based on your configuration settings.

The xMatters custom user property associates the email address of your Moogsoft account with your xMatters account. Once the property is created, any user can add their Moogsoft email address to their xMatters profile to receive notifications. The email address stored in the custom user property is used in the Create Alert - Assign to User step of the workflow.

1. Open the xMatters Admin menu and select Custom User Properties.

   

2. On the Custom User Properties window, click Add Property and fill in the following fields: 
   • Name: Moogsoft User ID
     • For the workflow to successfully send updates to Moogsoft, the name of the property must be Moogsoft User ID. If you give this property a different name, you must update the workflow constant with the new name.
   • Type: Select Text from the drop-down menu.

   

3. Click Save.

Now that the property is saved in your system, you need to populate the field with the users' Moogsoft email addresses. There are two ways to do this: 

• Batch upload: 
  • Export a list of all users in your system. The file will contain a column for the custom property you just created.
  • Add the Moogsoft email address for each user.
  • Upload the file to xMatters.
• Manually add each user's email address to their account.

Here's how to add a Moogsoft email address to an xMatters account profile.

1. To access your user profile, click on your username at the top-right corner of the xMatters, then select Profile.

   

2. Click Edit Profile.

   

3. Scroll to the bottom of the Edit Profile screen to the new Moogsoft User ID field.

   

4. Enter the email address associated with the Moogsoft account into the Moogsoft User ID field.
5. Click Save.

The Moogsoft API key sets the authentication method for the endpoint so that information can flow between Moogsoft and xMatters. Creating an API key and adding it to your flow as a constant means there's no configuration required for the Moogsoft endpoint.

Go to your Moogsoft account and use Moogsoft's instructions to create an API key. Save the API key to a secure location as it is only displayed once. If you don't save the API key, or forget it, you must create a new one.

Now that the API key and custom user property are created, apply them as constants to your Moogsoft Incidents workflow.

1. Open your Moogsoft Incidents workflow.
2. Click the Flow Designer tab, and open the Moogsoft Incidents canvas.
3. Expand the Components menu and select Constants.The workflow contains two constants for you: One for the API key, and the other for the custom user property.

   

4. Select the API Key tab.

   

5. Fill in the following fields:
   • Description: Enter an optional description for the API key.
   • Value: Enter the API Key value you generated in Moogsoft.
6. Click the Moogsoft User ID Property tab. You'll see that the value is already set as Moogsoft User ID. If you gave your custom user property a name other than Moogsoft User ID, enter that name into the Value field.
7. Click Save then Close.

The constant values are used in various steps throughout the workflow.

When a signal is received from Moogsoft and a new incident is created, the person responding to the notification has the following response options available:

• Assign to me: Acknowledges the notifications and stops escalations. The Moogsoft incident is updated with a note containing the xMatters incident ID and information about the authenticating user.
• Escalate: Immediately escalates the alert to the next on-call resolver in a targeted group.
• Resolve: Ends the xMatters alert and stops notifying all targeted recipients. The Moogsoft incident is resolved and a note is added for the change in status.
• Close: Ends the xMatters alert and stops notifying all targeted recipients. Both the xMatters and Moogsoft incidents are closed and a note is added for the change in status.