xMatters Integration
Synchronize on-call schedules, escalation policies, and user information.
Synchronize on-call schedules, escalation policies, and user information from xMatters to Harness AI SRE.
Overview
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
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
Step 1: Create API user or generate API key
Option A: Create API user
Create a dedicated REST web service user in xMatters:
Log in to xMatters as an administrator
Navigate to Users → Add User
Configure the user:
Username: Enter "harness-api-user"
Role: Select REST Web Service User or Full Access User
Password: Generate a secure password
Save the user credentials
Option B: Generate API key
Generate an API key from your xMatters profile:
Log in to xMatters as an administrator
Navigate to your Profile → API Keys
Click Create API Key
Enter a description such as "Harness AI SRE Integration"
Copy the generated API key
Step 2: Connect xMatters to AI SRE
Add xMatters as a sync source and verify the connection:
In Harness AI SRE, navigate to On-Call → Sync from 3rd Party tab
Click Connect Source
Select xMatters as the source system
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
Click Test Connection to verify credentials
Click Next: Select Entities
Step 3: Select entities to sync
Choose which xMatters entities to import and preview the results:
Choose which services to synchronize:
All Services: Import all xMatters services/groups
Specific Services: Select individual services to import
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
Click Next: Invite Users
Step 4: Invite users to Harness
Invite the discovered users so they can receive pages in Harness:
Review the list of discovered users from xMatters
Select users who need Harness accounts to receive pages
Selected users will receive email invitations to join Harness
Users already in Harness will be automatically mapped by email
Click Next: Configure Sync Rules
Step 5: Configure sync rules
Set the sync behavior and conflict resolution strategy, then start the sync:
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
Review the sync summary showing selected options
Click Start Sync
Step 6: Monitor sync progress
Track the import status and review the imported entities:
View the sync status dashboard showing:
Import progress by entity type
Successfully imported items
Skipped items with reasons
Failed items with error details
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
After completing the initial sync:
Verify user mapping: Ensure external users are correctly mapped to Harness users by email
Review schedules: Check that rotation patterns and time zones imported correctly
Test escalation policies: Verify escalation rules work as expected (xMatters on-call groups are mapped to AI SRE escalation policies)
Update service ownership: Assign imported teams to services in the Service Directory
Configure notifications: Set up notification preferences for imported users
xMatters-specific considerations
How on-call groups map
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
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
Common conflicts and how to resolve them:
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
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
Go to Create On-Call Schedules to manage imported schedules.
Go to Define Escalation Policies to configure escalation chains.
Go to Configure Notification Fallback to set up multi-channel notifications.
Last updated
Was this helpful?