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.
How to install the 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
  How to add the secret for URL authentication as a Cloud Automation secret
  1. On the Cloud Automation bridge, select your Cloud Automation project.
  2. Select Settings, and then select Secrets.
  3. 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>).
  4. Select Add secret.
- Basic authentication
  How to add the xMatters username and password as a Cloud Automation secret
  1. On the Cloud Automation bridge, select your Cloud Automation project.
  2. Select Settings, and then select Secrets.
  3. 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:
    
    plaintext
    JohnDoe:a3fbebe2-ea0d-4ef8-ba16-d3888a9f884c
    
    The encoded string would be:
    
    plaintext
    Sm9obkRvZTphM2ZiZWJlMi1lYTBkLTRlZjgtYmExNi1kMzg4OGE5Zjg4NGM=
    
    The resulting value would be:
    
    plaintext
    Basic Sm9obkRvZTphM2ZiZWJlMi1lYTBkLTRlZjgtYmExNi1kMzg4OGE5Zjg4NGM=
  4. Select Add secret.
- API key authentication
  How to add the xMatters API key as a Cloud Automation secret
  1. On the Cloud Automation bridge, select your Cloud Automation project.
  2. Select Settings, and then select Secrets.
  3. 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:
    
    plaintext
    x-api-key-2dferrc7e-65b2-4c25-911f-d8873434868ca:a3fbebe2-ea0d-4ef8-ba16-d3888a9f884c
    
    The Base64-encoded string would be:
    
    plaintext
    eC1hcGkta2V5LTJkZmVycmM3ZS02NWIyLTRjMjUtOTExZi1kODg3MzQzNDg2OGNhOmEzZmJlYmUyLWVhMGQtNGVmOC1iYTE2LWQzODg4YTlmODg0Yw==
    
    The resulting value would be:
    
    plaintext
    Basic eC1hcGkta2V5LTJkZmVycmM3ZS02NWIyLTRjMjUtOTExZi1kODg3MzQzNDg2OGNhOmEzZmJlYmUyLWVhMGQtNGVmOC1iYTE2LWQzODg4YTlmODg0Yw==
  4. 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:
  Passive webhooksActive webhooks
  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.
  Active webhooks stop a sequence from progressing until a response is received from xMatters.
  To create an active webhook, set the task suffix to triggered, and then set Send finished event:
  - If you select automatically, the sequence continues without needing a response from xMatters, which is similar to a passive webhook.
  - If you select by webhook receiver, Cloud Automation stops the sequence and waits to receive a response from the xMatters Finish Cloud Automation Event step before continuing.
- Request method: Select POST.
Go through the steps below, according to your preferred authentication method.
URL authenticationBasic authenticationAPI key authentication
1. 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
Note: 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).
1. Select Add custom header, then enter the following values:
- Name: Enter Content-Type.
- Value: Enter application/json.
1. 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?recipients=mygroup
Note: You must URL-encode any special characters or spaces in the target names.
1. Select Add custom header, then enter the following values:
- Name: Enter Authorization.
- Value: Enter {.secret.xmatters.xmatters-auth}
1. Select Add custom header once more, then enter the following values:
- Name: Enter Content-Type.
- Value: Enter application/json.
1. 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?recipients=mygroup
Note: You must URL-encode any special characters or spaces in the target names.
1. Select Add custom header, then enter the following values:
- Name: Enter Authorization.
- Value: Enter {.secret.xmatters.xmatters-auth}.
1. Select Add custom header once more, then enter the following values:
- Name: Enter Content-Type.
- Value: Enter application/json.

Enter a Custom payload.

Example:

json
{
      "data": {
          "project": "{{.data.project}}",
          "service": "{{.data.service}}",
          "stage": "{{.data.stage}}"
      },
      "id": "{{.id}}",
      "source": "{{.source}}",
      "specversion": "{{.specversion}}",
      "time": "{{.time}}",
      "type": "{{.type}}",
      "shkeptncontext": "{{.shkeptncontext}}"
}

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.

Example:

json
{
  "type": "sh.keptn.event.mystage.incident.triggered",
  "specversion": "1.0",
  "source": "manual-trigger",
  "data": {
    "project": "myproject",
    "stage": "production",
    "service": "myservice"
  }
}

Send the event.

bash
keptn send event --file triggered-event.json