Integrate xMatters with Dynatrace Cloud Automation

Integrating Dynatrace Cloud Automation with xMatters allows SREs and developers to alert the right people, automatically initiate incidents, get more information from a CI/CD application, or send updates via your chosen chat application when an event occurs in Cloud Automation.

To integrate Dynatrace Cloud Automation with xMatters, follow the instructions below.

Prerequisites

xMatters

Dynatrace

xMatters

Create an xMatters account.
Install the Dynatrace Cloud Automation workflow template.
1. In your xMatters instance, select Workflows > Workflow templates.
2. Filter for and select Dynatrace Cloud Automation, and then select Install.
3. Copy the Trigger URL and save it for later.

Dynatrace

Create a Cloud Automation project with a shipyard file that has a custom task (for example, runbook) used to trigger the xMatters subscription.
Add the xMatters user name, password, or API key obtained above as a Cloud Automation secret based on one of the following authentication methods:
- URL authentication
  On the Cloud Automation bridge, select your Cloud Automation project.
  
  Select Settings, and then select Secrets.
  
  Select Add secret and enter the following values:
  
  Name: Enter a name for the secret (for example, xmatters)
  Scope: Select keptn-webhook-service
  Key/Value: Enter your value for the API key (for example, Key: xmatters-auth, Value: <the_GUID_of_the_xMatters_API_key>).
  
  Select Add secret.
- Basic authentication
  On the Cloud Automation bridge, select your Cloud Automation project.
  
  Select Settings, and then select Secrets.
  
  Select Add secret and enter the following values:
  
  Name: Enter a name for the secret (for example, xmatters)
  
  Scope: Select keptn-webhook-service
  
  Key/Value: Enter one key/value pair (for example, Key: xmatters-auth, Value: Basic <base64(username:password)>, where <base64(username:password)> is the Base64-encoded credentials string of an xMatters user with access to the workflow.)
  
  Example
  
  Based on the following values:
  
  username is JohnDoe
  password is a3fbebe2-ea0d-4ef8-ba16-d3888a9f884c
  
  You need to encode:
  
  1JohnDoe:a3fbebe2-ea0d-4ef8-ba16-d3888a9f884c
  
  The encoded string would be:
  
  1Sm9obkRvZTphM2ZiZWJlMi1lYTBkLTRlZjgtYmExNi1kMzg4OGE5Zjg4NGM=
  
  The resulting value would be:
  
  1Basic Sm9obkRvZTphM2ZiZWJlMi1lYTBkLTRlZjgtYmExNi1kMzg4OGE5Zjg4NGM=
  
  Select Add secret.
- API key authentication
  On the Cloud Automation bridge, select your Cloud Automation project.
  
  Select Settings, and then select Secrets.
  
  Select Add secret and enter the following values:
  
  Name: Enter a name for the secret (for example, xmatters)
  Scope: Select keptn-webhook-service
  Key/Value: Enter one key/value pair (for example, Key: xmatters-auth, Value: Enter Basic <base64(API Key:API Secret)>, where <base64(API Key:API Secret)> is the Base64-encoded API credentials string.)
  
  Example
  
  You need to encode:
  
  1x-api-key-2dferrc7e-65b2-4c25-911f-d8873434868ca:a3fbebe2-ea0d-4ef8-ba16-d3888a9f884c
  
  The Base64-encoded string would be:
  
  1eC1hcGkta2V5LTJkZmVycmM3ZS02NWIyLTRjMjUtOTExZi1kODg3MzQzNDg2OGNhOmEzZmJlYmUyLWVhMGQtNGVmOC1iYTE2LWQzODg4YTlmODg0Yw==
  
  The resulting value would be:
  
  1Basic eC1hcGkta2V5LTJkZmVycmM3ZS02NWIyLTRjMjUtOTExZi1kODg3MzQzNDg2OGNhOmEzZmJlYmUyLWVhMGQtNGVmOC1iYTE2LWQzODg4YTlmODg0Yw==
  
  Select Add secret.

Set up the xMatters webhook subscription

Use case: Set up a passive webhook subscription that triggers an xMatters workflow. The Cloud Automation sequence will not wait for xMatters to send back a Cloud Automation sequence task finished event.

On the Cloud Automation bridge, select your Cloud Automation project.
Select Settings and then select Integrations.
Select webhook-service from the list and then select Add subscription.
Enter the following values:
- Task: Select the task associated with your shipyard file (in this case, runbook).
- Task suffix: The task suffix sets one of the following webhook types:
  
  recommended
  Passive webhooks don't require a response from xMatters before continuing the sequence.
  To create a passive webhook, set the task suffix to started. Selecting started disables Send finished event, as no response is required to continue the sequence. This is the recommended option to ensure Dynatrace Cloud Automation processes sequences at the expected rate.
- Request method: Select POST.
Go through the steps below, according to your preferred authentication method.
For URL, enter your trigger URL endpoint from your workflow template, making sure to add the users or groups you want to target in the recipient's query parameter.
Example: https://mycompany.xmatters.com/api/integration/1/functions/83bcaca8-9afa-46bf-ade6-3c5b5c2d0218/triggers?apiKey={{.secret.xmatters.xmatters-auth}}&recipients=mygroup
You must URL-encode any special characters or spaces in the target names. To mask parts of the trigger URL, we recommend using a secret as above (see Prerequisites).

Select Add custom header, then enter the following values:

Name: Enter Content-Type.
Value: Enter application/json.

Enter a Custom payload.

Example:

1{
2      "data": {
3          "project": "{{.data.project}}",
4          "service": "{{.data.service}}",
5          "stage": "{{.data.stage}}"
6      },
7      "id": "{{.id}}",
8      "source": "{{.source}}",
9      "specversion": "{{.specversion}}",
10      "time": "{{.time}}",
11      "type": "{{.type}}",
12      "shkeptncontext": "{{.shkeptncontext}}"
13}

Select Create subscription.

Trigger a sequence

Cloud Automation triggers an xMatters workflow whenever the defined task in the sequence is triggered.

To trigger the sequence, you can send the event command in the Keptn CLI. In the following example, there's a sequence called incident and a task called runbook.

Create a file called triggered-event.json.