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

# xMatters

> Connect xMatters to Oleria to see who can page, alert, and act in your incident-response platform: users, groups, roles, workflows, messaging forms, integrations, service accounts, and alerting activity.

Connect xMatters (an Everbridge company) to Oleria to see who has access to your xMatters instance: its users, groups, and roles, who can send alerts with each messaging form and scenario, and which integrations and service accounts can act in it. Oleria reads this data with an API key that belongs to a dedicated xMatters integration user, so you can see where access is over-provisioned and take action directly from Oleria.

> [!NOTE]
>
> If you connected xMatters through the earlier SCIM setup (a SCIM base URL and bearer token), that connection stops syncing once this connector replaces it. Remove it and add xMatters again with an API key or web login, as described below.

## What Oleria discovers

Once connected, Oleria continuously discovers and maps the following from your xMatters instance:

* **Accounts** - every user in your instance, with their name, email address (from their email devices), status, license type, roles, site, and when they were created, last changed, and last signed in.
* **Groups** - on-call, broadcast, and dynamic groups, their user members and nested groups, and the supervisors who manage each group.
* **Roles** - every default and custom role, and which users hold each one.
* **Resources** - workflows, messaging forms, scenarios, and services, and how they fit together (a workflow contains its forms, a form contains its scenarios).
* **Resource access** - who can send alerts with each messaging form and scenario, which roles can observe each group, and which form each integration triggers.
* **Non-human identities (NHIs)** - service accounts (users whose only roles are **REST Web Service User** or **Web Service Supervisor**), linked to their supervisors as owners, and the integrations in your workflows.
* **Credentials** - the API key Oleria connects with, linked to the user who owns it, and workflow endpoints that store a password or an OAuth client secret. Oleria records only names, types, and owners. It never reads or stores secret values.
* **Activity** - inbound signals, alerts and who raised them, alert comments and responses, integration calls with their source IP address, and user import jobs.

Oleria refreshes users, groups, roles, and resources on its [regular sync schedule](/integrations/overview.md#sync-model).

> [!NOTE]
>
> Oleria doesn't import on-call schedules, incident details, or message content. This integration covers identity and access governance for xMatters only.

## Prerequisites

* An xMatters instance. Note its hostname, for example `acme.xmatters.com` or `acme.na1.xmatters.com`.
* A dedicated xMatters integration user with the **REST Web Service User** role (or **Company Supervisor**, for full visibility). Oleria reads and acts with this user's access.
* That role must be an **observer** of every group you want Oleria to see. See [Let the integration user see every group](#let-the-integration-user-see-every-group).
* An xMatters user who can manage the integration user's API keys, such as the user's supervisor or a Company Supervisor.
* Admin access to the Oleria workspace.

> [!WARNING]
>
> xMatters API keys belong to a single user. There's no organization-wide key. Create the key on a dedicated integration user instead of a named person's account. If the key's owner is deactivated or removed, or the key is deleted, syncs and actions stop working.

## Create the integration user in xMatters

**1. Open the integration user**

Go to **Users** and create a user for Oleria, for example **Integration Service**. Open the user's page.

![xMatters user page for the Integration Service user](https://mintcdn.com/oleria/33eFJshuBSuoJ4_n/images/integrations/xmatters/step-1.png?fit=max\&auto=format\&n=33eFJshuBSuoJ4_n\&q=85\&s=f1b1221fac12c027eb401f8cbd439f99)

**2. Assign the role**

Select **More Actions** > **Manage Roles**. Assign **REST Web Service User**, remove any other roles, and select **Save**.

The **REST Web Service User** role lets the user call the xMatters REST API. It also includes **Data Synchronization** and **Edit Incidents**, so it isn't read-only.

![Roles dialog with REST Web Service User assigned and its functions listed](https://mintcdn.com/oleria/33eFJshuBSuoJ4_n/images/integrations/xmatters/step-2.png?fit=max\&auto=format\&n=33eFJshuBSuoJ4_n\&q=85\&s=02c3e8be6e3b9d0e8eb9bae1e99f44e1)

## Create an API key for the integration user

**1. Open Manage API Keys**

On the integration user's page, select **More Actions** > **Manage API Keys**.

![More Actions menu on the user page with Manage API Keys and Manage Roles](https://mintcdn.com/oleria/33eFJshuBSuoJ4_n/images/integrations/xmatters/step-3.png?fit=max\&auto=format\&n=33eFJshuBSuoJ4_n\&q=85\&s=01bf38b77dca138b8bd0dfcbeef1d38e)

**2. Copy the User API Key and create a credential**

Copy the **User API Key** shown at the top of the page. This is the API key you enter in Oleria, and it identifies the integration user, so Oleria knows which user it connects as. Then select **Create API Key Credential**.

![Manage API Keys dialog with the User API Key field and the Create API Key Credential button](https://mintcdn.com/oleria/33eFJshuBSuoJ4_n/images/integrations/xmatters/step-4.png?fit=max\&auto=format\&n=33eFJshuBSuoJ4_n\&q=85\&s=e4a0f3247cf6b2044808dc39cfe454c7)

**3. Name the credential**

Enter a **Name** you'll recognize later, for example `oleria-connector`, and an optional **Description**. Select **Create**.

![Create API Key Credential dialog with the Name and Description fields](https://mintcdn.com/oleria/33eFJshuBSuoJ4_n/images/integrations/xmatters/step-5.png?fit=max\&auto=format\&n=33eFJshuBSuoJ4_n\&q=85\&s=c8b164ec9722efe50e9cd86f9abdf681)

**4. Copy the secret**

Copy the secret right away. xMatters shows it only once. You need the API key and the secret to connect xMatters to Oleria.

> [!NOTE]
>
> You can connect with the integration user's web login ID and password instead of an API key. We recommend an API key: it can't be used to sign in to xMatters, and you can revoke it without changing the user's password. If your instance enforces single sign-on, a password sign-in may not be allowed, so use an API key.

## Let the integration user see every group

xMatters can limit which roles see a group. If a group restricts its observers, users whose role isn't an observer can't see it, and Oleria won't discover it.

**1. Open the group's observers**

Go to **Groups**, open a group, and select **People** > **Observers**.

**2. Add the role**

Select **Manage Observers** and add **REST Web Service User** (or the role you gave the integration user). Repeat for each group that restricts observers.

![Observers tab of a group with REST Web Service User listed as an observer](https://mintcdn.com/oleria/33eFJshuBSuoJ4_n/images/integrations/xmatters/step-6.png?fit=max\&auto=format\&n=33eFJshuBSuoJ4_n\&q=85\&s=220df1bd5ac06018437f27ae187b058b)

## Permissions Oleria needs

| What you want Oleria to do | What it needs |
| :- | :- |
| Sync users, groups, roles, resources, credentials, and activity | An API key (or web login) of a user with **REST Web Service User** or **Company Supervisor**. |
| See every group | That user's role must be an observer of each group that restricts observers. |
| Run remediation actions | The same user. Oleria uses no separate write credential. |

## Connect xMatters to Oleria

**1. Open the integration**

Go to your Oleria workspace, select **Integrations** -> select **xMatters**.

**2. Complete the connection form**

Select **Continue** and provide the following:

| Field | Notes |
| :- | :- |
| Instance hostname | Required. Your xMatters host, for example `acme.xmatters.com` or `acme.na1.xmatters.com`. You can also paste the instance URL. Oleria keeps only the host. |
| Authentication method | **API key** (recommended) or **Web login and password**. |
| API key | Required for the API key method. The **User API Key** from the integration user's **Manage API Keys** page. |
| API secret | Required for the API key method. The secret you copied when you created the credential. |
| Web login ID | Required for the web login method only. The integration user's web login ID. |
| Password | Required for the web login method only. The integration user's password. |

Oleria stores the secret or password encrypted.

**3. Confirm the connection**

Select **Authenticate**. Oleria checks that it can read your instance with these credentials before it saves anything. Find the newly connected instance on the **Connected** tab of your Oleria **Integrations** page.

> [!NOTE]
>
> When you edit the integration, you can't change the instance hostname. To connect a different instance, add another integration. Leave the secret or password blank to keep the stored one, unless you change the authentication method.

## Verify the integration

Confirm the xMatters instance appears on the **Connected** tab of your Oleria **Integrations** page with a status of **Healthy**. After the first sync completes, check that users, groups, and roles appear in your Oleria workspace, that the integration user appears as a service account (when **REST Web Service User** is its only role), and that your workflows and messaging forms appear as resources.

## Remediation actions

Oleria can take these actions in xMatters. Each one runs with the access of the integration user:

* **Disable a user** and **enable a user**. Disabling sets the user's status to **Inactive**.
* **Create a user.** Oleria creates the user with the **Standard User** role, a work email device, and no password. The user is **Inactive** unless you choose to activate it, and signs in through single sign-on or the password reset flow.
* **Delete a user.** This can't be undone.
* **Create a group.**
* **Add a user to a group** and **remove a user from a group**.
* **Assign a role to a user** and **remove a role from a user**.
* **Revoke a user's permission to send with a messaging form.** This removes the user's own sender permission. If the user can send through a role, Oleria tells you which role to remove instead.
* **Disable a non-human identity.** A service account is set to **Inactive**. An integration is undeployed.

Keep these limits in mind when you use these actions:

* Oleria reads the user, group, or form before it changes anything. If it's already in the requested state, Oleria makes no change.
* Reverting an action undoes only the change that action made. Deleting a user can't be reverted.
* Oleria won't disable, delete, or remove roles or sender permissions from the integration user it connects as.
* Oleria won't delete a **Company Supervisor**.
* Oleria won't remove a user's last role, or a form's last sender.
* Scenario sender permissions can't be changed from Oleria. Change them in xMatters.
* Oleria can't revoke a user's sessions or API keys. xMatters allows this only in its web interface.

## Known limitations

* **API keys are per user.** xMatters has no organization-wide key, so the connection depends on the integration user. Use a dedicated user, not a person's account.
* **Groups that restrict observers are hidden** unless the integration user's role is an observer. See [Let the integration user see every group](#let-the-integration-user-see-every-group).
* **Some built-in workflows can't be read.** xMatters may refuse to show the integrations, endpoints, or form senders of a built-in workflow to the **REST Web Service User** role. Oleria skips those details and keeps syncing everything else.
* **No audit log or sign-in history.** xMatters has no API for its system audit report, sign-in history, API key list, OAuth tokens, SAML settings, or role permissions, so Oleria doesn't import them.
* **No multi-factor authentication or single sign-on status.** xMatters doesn't report them per user. Multi-factor authentication comes from your identity provider.
* **Limited user details.** xMatters stores email addresses on devices, and job title, department, and manager only as custom fields. Oleria imports email from email devices.
* **No creation dates** for groups, roles, integrations, or endpoints, and no last password change. xMatters doesn't report them.
* **Activity has collection limits.** Oleria reads comments and responses for the first 200 alerts in each sync and misses responses sent more than 24 hours after an alert. Integration calls come from each integration's latest 1,000 log entries, for up to 200 integrations.
* **Signals and alerts older than 30 days need extra permission.** xMatters returns older records only with its historical data permission, which xMatters Support turns on.
* **OAuth isn't supported.** xMatters OAuth uses the same user's password, so it adds no protection over an API key.

## Contact us

For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.