> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/ai-sre/ai-sre-for-administrators/set-up-on-call-management/integrations/xmatters.md).

# xMatters Integration

Synchronize on-call schedules, escalation policies, and user information from xMatters to Harness AI SRE.

### Overview <a href="#overview" id="overview"></a>

The xMatters integration enables you to:

* **Import schedules**: Synchronize rotation schedules with shifts and time zones
* **Import on-call groups**: Bring existing escalation chains into AI SRE
* **Import teams**: Synchronize user groups and team structures
* **Import user details**: Sync contact information including email, SMS, and phone numbers
* **Maintain consistency**: Keep on-call configurations aligned between systems

***

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

* xMatters account with administrator access
* xMatters API user credentials or API key
* xMatters instance URL (e.g., `https://yourcompany.xmatters.com`)
* Harness project with On-Call Management enabled

***

### Configure xMatters sync <a href="#configure-xmatters-sync" id="configure-xmatters-sync"></a>

#### Step 1: Create API user or generate API key <a href="#step-1-create-api-user-or-generate-api-key" id="step-1-create-api-user-or-generate-api-key"></a>

**Option A: Create API user**

Create a dedicated REST web service user in xMatters:

1. Log in to xMatters as an administrator
2. Navigate to **Users** → **Add User**
3. Configure the user:
   * **Username**: Enter "harness-api-user"
   * **Role**: Select **REST Web Service User** or **Full Access User**
   * **Password**: Generate a secure password
4. Save the user credentials

**Option B: Generate API key**

Generate an API key from your xMatters profile:

1. Log in to xMatters as an administrator
2. Navigate to your **Profile** → **API Keys**
3. Click **Create API Key**
4. Enter a description such as "Harness AI SRE Integration"
5. Copy the generated API key

#### Step 2: Connect xMatters to AI SRE <a href="#step-2-connect-xmatters-to-ai-sre" id="step-2-connect-xmatters-to-ai-sre"></a>

Add xMatters as a sync source and verify the connection:

1. In Harness AI SRE, navigate to **On-Call** → **Sync from 3rd Party** tab
2. Click **Connect Source**
3. Select **xMatters** as the source system
4. Configure the connector:
   * **Instance URL**: Enter your xMatters instance URL (e.g., `https://yourcompany.xmatters.com`)
   * **Username**: Enter the API user username or your admin username
   * **Password**: Enter the API user password or API key
5. Click **Test Connection** to verify credentials
6. Click **Next: Select Entities**

#### Step 3: Select entities to sync <a href="#step-3-select-entities-to-sync" id="step-3-select-entities-to-sync"></a>

Choose which xMatters entities to import and preview the results:

1. Choose which services to synchronize:
   * **All Services**: Import all xMatters services/groups
   * **Specific Services**: Select individual services to import
2. Review the preview showing what will be imported:
   * Schedules with rotation patterns and shifts
   * On-call groups (mapped to escalation policies)
   * Groups mapped to Harness User Groups
   * People with contact information
3. Click **Next: Invite Users**

#### Step 4: Invite users to Harness <a href="#step-4-invite-users-to-harness" id="step-4-invite-users-to-harness"></a>

Invite the discovered users so they can receive pages in Harness:

1. Review the list of discovered users from xMatters
2. Select users who need Harness accounts to receive pages
3. Selected users will receive email invitations to join Harness
4. Users already in Harness will be automatically mapped by email
5. Click **Next: Configure Sync Rules**

#### Step 5: Configure sync rules <a href="#step-5-configure-sync-rules" id="step-5-configure-sync-rules"></a>

Set the sync behavior and conflict resolution strategy, then start the sync:

1. Configure sync behavior:
   * **Sync Contact Details**: Enable to import email, SMS, and phone numbers
   * **Sync Strategy**: Choose conflict resolution strategy:
     * **Preserve Local Changes**: Keep existing Harness data when conflicts occur
     * **Overwrite with Source**: Use xMatters data for all conflicts
2. Review the sync summary showing selected options
3. Click **Start Sync**

#### Step 6: Monitor sync progress <a href="#step-6-monitor-sync-progress" id="step-6-monitor-sync-progress"></a>

Track the import status and review the imported entities:

1. View the sync status dashboard showing:
   * Import progress by entity type
   * Successfully imported items
   * Skipped items with reasons
   * Failed items with error details
2. Review imported entities:
   * Users: Number imported and invitation status
   * Schedules: Rotation patterns and shift assignments
   * On-Call Groups: Escalation policy mappings
   * Teams: User Group mappings

***

### Post-sync steps <a href="#post-sync-steps" id="post-sync-steps"></a>

After completing the initial sync:

1. **Verify user mapping**: Ensure external users are correctly mapped to Harness users by email
2. **Review schedules**: Check that rotation patterns and time zones imported correctly
3. **Test escalation policies**: Verify escalation rules work as expected (xMatters on-call groups are mapped to AI SRE escalation policies)
4. **Update service ownership**: Assign imported teams to services in the Service Directory
5. **Configure notifications**: Set up notification preferences for imported users

***

### xMatters-specific considerations <a href="#xmatters-specific-considerations" id="xmatters-specific-considerations"></a>

#### How on-call groups map <a href="#how-on-call-groups-map" id="how-on-call-groups-map"></a>

xMatters on-call groups are automatically mapped to Harness AI SRE escalation policies:

* Group members become escalation policy levels
* Group rotation patterns are preserved
* Notification preferences are imported when available

#### How time zones are handled <a href="#how-time-zones-are-handled" id="how-time-zones-are-handled"></a>

xMatters schedules may use different time zone formats:

* AI SRE automatically converts xMatters time zones to standard IANA format
* Review imported schedules to verify time zone conversions are correct
* Adjust time zones manually if needed after import

***

### Sync conflicts <a href="#sync-conflicts" id="sync-conflicts"></a>

Common conflicts and how to resolve them:

| Conflict Type           | Cause                                             | Resolution                                            |
| ----------------------- | ------------------------------------------------- | ----------------------------------------------------- |
| **User not found**      | External user email does not match a Harness user | Invite the user to Harness or map to an existing user |
| **Duplicate schedule**  | Schedule with same name already exists            | Rename one of the schedules or merge them             |
| **Team name collision** | User Group with same name exists                  | Rename the User Group or choose to merge              |
| **Timezone mismatch**   | External tool uses different timezone format      | Review and confirm timezone conversions               |

***

### Ongoing sync <a href="#ongoing-sync" id="ongoing-sync"></a>

After the initial import:

* **Re-sync periodically**: Pull updates from xMatters to keep schedules current
* **One-way sync**: Changes in xMatters can be synced to AI SRE
* **Manual management**: After import, manage schedules independently in AI SRE
* **Selective updates**: Re-run sync for specific services when needed

***

### Next steps <a href="#next-steps" id="next-steps"></a>

* Go to [Create On-Call Schedules](/ai-sre/ai-sre-for-administrators/set-up-on-call-management/create-oncall-schedules.md) to manage imported schedules.
* Go to [Define Escalation Policies](/ai-sre/ai-sre-for-administrators/set-up-on-call-management/define-escalation-policies.md) to configure escalation chains.
* Go to [Configure Notification Fallback](/ai-sre/ai-sre-for-administrators/set-up-on-call-management/notification-fallback.md) to set up multi-channel notifications.