Edwin AI xMatters Integration

The Edwin AI xMatters integration enables automated issue management between Edwin AI and xMatters to create, trigger, or update incidents. By evaluating incoming events and correlating operational signals, Edwin AI automatically generates and updates xMatters incidents based on configured workflows, depending on how your xMatters administrator configures incident notifications.

Configuring the Edwin AI xMatters Integration involves the following:

• creating an Edwin AI user in a xMatters account
• configuring Edwin AI to connect to xMatters
• configuring an xMatters action group with mapped fields

You can validate the newly configured integration by triggering both incident creation and update workflows from Edwin AI.

Requirements for Configuring the Edwin AI xMatters Integration

To configure the Edwin AI xMatters Integration, you need the following:

• Your xMatters Tenant URL (for example, https://<host>.xmatters.com)
• An xMatters administrator who can manage users, roles, and OAuth settings
• Determine which Edwin AI records (for example, insights or singleton alerts) and severity levels that create incidents, and which fields should be mapped to incoming xMatters details.

Configuring the Edwin AI xMatters Integration in xMatters

1. Create a dedicated xMatters user for Edwin AI.
   For more information, see Configuring xMatters from xMatters.

2. Assign the REST Web Service User role and any other permissions required to create and update incidents in your target xMatters workflow.
3. Locate the OAuth Client ID for your xMatters instance and save it in a secure location.
   For more information, see OAuth authentication and OAuth authentication from xMatters. 
4. Use the xMatters OAuth token endpoint to generate a long-lived OAuth refresh token.
   Edwin AI uses xMatters OAuth credentials to request short-lived access tokens for API calls.

5. Replace the variables with the following details:

curl --location 'https://${yourHost}.xmatters.com/api/xm/1/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=${clientId}' \
--data-urlencode 'username=${username}' \
--data-urlencode 'password=${password}' \
--data-urlencode 'grant_type=password'

Configuring xMatters Alert Actions in Edwin AI

1. Navigate to the Edwin AI > Actions page.
2. Create a new action, or edit an existing one.
   For more information, see Creating and Editing Action in Edwin AI.
3. Select “xMattersIncident” from the Source dropdown menu.
4. Select Add Action
5. Select one of the following options from the Add Action dropdown menu.
   • To create or trigger a new incident in xMatters, select “Create xMatter Incident.”
   • To update existing xMatters incidents, select “Update xMatter Incident.”
6. Configure the mapped fields to match your xMatters configuration.
   By default, Edwin AI maps the following fields:

7. Select Submit.

The new action displays in the Actions list. Assign the new action to one or more Edwin AI Rules to trigger the action when the rule conditions are met. For more information, see Edwin AI Rules.

When a rule triggers the action, it generates one of the following responses:

• When Edwin AI successfully triggers a Create/Trigger xMatters Incident action, the expected response from the xMatters API is 201 Created.
• When Edwin AI successfully triggers an Update xMatters Incident action, the expected response from the xMatters API is 200 OK.

Incident Creation and Update Validation In Edwin AI

Confirm that the actions you configure in Edwin AI successfully connects to xMatters by manually triggering the action steps that create and update incidents in xMatters.

Validating Outbound Incident Creation

1. Navigate to Edwin AI > Explore and select an existing insight.
2. On the insight details, select “Create Incident” from the Actions dropdown menu.
3. Confirm Edwin stores or displays the returned xMatters incident reference.
4. In the xMatters console, confirm a new incident displays that contains the expected mapped fields.
   The incident payload includes the mapped fields configured in Edwin, as in the following example payload:

{
  "summary": "<Edwin incident summary>",
  "description": "<Edwin incident details>",
  "status": "Open",
  "severity": "Critical"
}

5. Confirm the incident is visible to the customer team that reviews xMatters incidents.

xMatters returns a created response and an incident reference. Edwin stores that xMatters incident reference so the same incident can be updated later.

Validating Outbound Incident Updates

1. In Edwin AI, update an incident with a correlating incident in xMatters.
   For example, you can create an interactive rule to change the status of an existing alert.
2. In the xMatters console, confirm that the existing xMatters incident is updated.
   Review the xMatters incident to confirm the following:
   • The update uses the original xMatters incident reference.
   • The mapped fields update as expected.
   • No duplicate xMatters incident is created.
   • xMatters sends a response to the Edwin AI endpoint.
3. in Edwin AI, confirm the following:
   • Edwin receives the inbound payload.
   • Edwin processes the status update according to the configured lifecycle workflow.

Edwin updates the existing xMatters incident using the stored xMatters incident reference. This prevents duplicate incidents and keeps the xMatters incident aligned with the Edwin workflow, as in the following example payload:

{
  "id": "<xMatters incident ID>",
  "status": "In_Progress"
}

For more information about sending outbound updates from xMatters workflows, see Outbound integrations from xMatters. For more information about xMatters incident fields and incident lifecycle values, see Update incident details and xMatters REST API Reference from xMatters.