> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# xMatters

> Connect xMatters to find on-call responders, page groups, and manage alert activity.

The xMatters integration provides group search, on-call lookup, alert inspection,
response lookup, paging, comments, and alert lifecycle actions.

## Connect xMatters

1. Choose an xMatters integration user with access to the groups and alerts you
   want Serval to use. The connection inherits this user's permissions.
2. Open the user's profile, then select **More Actions → Manage API Keys →
   Create API Key Credential**. Create a credential and save its API key and
   one-time secret. See
   [xMatters API key administration](https://help.xmatters.com/ondemand/user/apikeys.htm).
3. In Serval's app catalog, select **xMatters** and connect an instance.
4. Enter an instance name, your tenant hostname (for example,
   `company.xmatters.com`), the API key, and its secret. The `x-api-key-` prefix
   is optional. Use the hostname only; do not paste a trigger URL here.
5. Run the connection health checks. They read groups, alerts, and one visible
   on-call group's schedule without sending notifications. If no on-call group
   is visible, the schedule check reports that it was not exercised.

The API key and secret are stored as integration credentials. You can rotate them
in the connection form. To change the tenant hostname, create a new connection.
Revoking the key or deleting its xMatters user prevents the connection from working.

## Configure paging

An xMatters administrator must set up the
[Trigger Alerts by Webhook template](https://help.xmatters.com/integrations/other/triggeralertsbywebhook.htm)
and enable its flow. Select **API Key Authentication** for the HTTP trigger.
The trigger's **Basic Authentication** option is for a user password and does
not accept these API-key credentials.

Copy the trigger UUID from the URL path:

```text theme={null}
https://company.xmatters.com/api/integration/1/functions/TRIGGER_UUID/triggers
```

Use that UUID as the **Trigger ID** input to **Page an xMatters Group**. Find the
recipient using **Find xMatters Groups**, then supply its explicit group UUID,
summary, and message. Serval supplies the resolved group name in both the
recipients query parameter and the template payload, replacing the default
recipient from the copied URL. Group names containing commas are not supported
by this workflow; choose an unambiguous group name in xMatters.

The workflow maps its message to the template's `description` field and sends
`MEDIUM` priority. Custom flows may need a custom Serval workflow. The xMatters
flow controls escalation and delivery.

## Install workflows

The **Alerting and On-Call** bundle includes:

| Workflow | Behavior | Default approval |
| - | - | - |
| Find xMatters Groups | Search groups and return their UUIDs | None |
| Get xMatters On-Call Responders | Read shifts and members for one group | None |
| Search xMatters Alerts | Filter alerts or correlate a trigger request | None |
| Get xMatters Alert Details | Read properties, status, and comments | None |
| Get xMatters Alert Responses | Read current response audit entries | None |
| Page an xMatters Group | Submit a paging flow for an explicit group | Installer |
| Add an xMatters Alert Comment | Add a comment without acknowledging | Installer |
| Change xMatters Alert Status | Resume, suspend, or terminate notifications | Installer |

## Interpret results

A paging result marked **accepted** means xMatters accepted the flow request.
It does not confirm alert creation or delivery. Use **Search xMatters Alerts**
with the returned `requestId` to find resulting alerts. The search can initially
be empty or return more than one alert. Inspect response entries separately.

List workflows return one bounded page with `hasMore` and `nextOffset`. Pass the
next offset to continue. On-call results also indicate whether nested member
lists are incomplete. An empty result only describes data visible to the API user.

Lifecycle actions accept `ACTIVE` (resume), `SUSPENDED` (pause), and `TERMINATED`
(stop permanently). Termination cannot be undone. None is an acknowledgment.
The API calls alerts **events**, and workflows use their UUIDs rather than their
numeric display IDs.

## Troubleshooting

* **401 or 403:** check the key, secret, user's status and permissions, and the
  trigger's authentication setting. REST access and flow-trigger access are
  separate checks.
* **429 or server errors during reads:** Serval makes up to three attempts using
  bounded backoff. If the read still fails, try again later.
* **Paging timeout or interruption:** a page might already have been sent. Inspect
  the xMatters Activity log before retrying. Paging has no exactly-once guarantee.
* **No alert found for a request ID:** allow time for the flow to execute and check
  its Activity log. Do not resubmit a page solely because this search is empty.

This integration does not automatically create xMatters flows, edit schedules,
provision users, or synchronize Serval tickets through callbacks.