Synchronize with ServiceNow

On the Admin menu, under Configuration, select Data Sync.

Sync Configurations

On the Sync Configurations tab you can: 

• Click the name of a sync to open its configuration settings page.
• See the status of syncs that are currently running.
• See the status and time stamp of completed syncs.
• Use the status link to the summary report of the completed sync.

On the History tab, you can: 

• View status of syncs that are currently running.
• Filter by date, configuration, or status.
• Click the name of they sync to open its configuration settings page.
• Click the status link to see a detailed report of the sync.

When you click the status link you'll see a detailed report containing the sync results, as well as any errors or warning that occurred during the sync.

From this page, you can go to the sync configuration page or export the report. If you choose to export the report, you can select what to export as a .csv file: 

• Export Sync Files: Exports only the user data of the sync.
• Export Error Report: Exports only the error and warning messages.
• Export Report and Sync Files: Exports both the user data and the error report.

To create a new ServiceNow data configuration: 

1. Go to Admin > Data Sync.
2. Click Add Sync Configuration.
3. On the Add Sync Configuration window, fill in the following fields: 
   • Name: A unique name for your sync configuration.
   • Data Source: This field is not editable as the only available data sync is with ServiceNow.
   • Authentication Method: This field is not editable as ServiceNow only accepts OAuth 2.0.
   • Base URL: The base URL of the ServiceNow server to synchronize with.
   • Username: Username of the authenticating user who has permission to execute requests in ServiceNow.
   • Password: Password of the authenticating user.
   • Client ID: Client ID of the authenticating user who has permission to execute requests in ServiceNow.
   • Client Secret: Secret for the authenticating Client ID.
4. Optional: Copy the redirect URL if you need to configure the connection between xMatters and ServiceNow. Once the you authorize xMatters, ServiceNow sends you to the redirect URL with an authorization code.
5. Click Save.

The configuration is created and you're redirected to the configuration settings page. The new configuration is added as a tile to the Sync Configurations Sync Configurations page.

To include devices in the data sync:

1. Go to the Device Sync Rules section and enable the 'Assign user devices' toggle.

   

2. In the Device Properties Mapping table, map source properties from ServiceNow to their corresponding xMatters properties.
   • xMatters Device: Select the xMatters device type from the drop-down menu.
   • Source Property: Select the ServiceNow property from the drop-down menu.
   • Sync Action: What action to take for each property when a subsequent sync is run. During the initial sync the Sync Action setting is ignored. Available values are: 
     • Overwrite existing: Overwrite the existing property in xMatters with the property value from ServiceNow.
     • Ignore (skip): Make no changes in xMatters.
3. To map additional device types, click Add Mapping.
4. Save the sync, or continue to the next configuration section.

Each user in xMatters must have at least one role assigned to their profile. The role is added when a user profile is created during the initial sync. The default role is 'Standard User', but you can select multiple values by either typing the role names, or selecting them from the Default Role drop-down list.

Supervisors are added when a user record is created during the initial sync with xMatters. You can assign one or more supervisors for each user. To include supervisors as part of the data sync: 

1. Go to the Supervisor Sync Rules section and enable the 'Assign user supervisors' toggle.

   

2. In the User Supervisor field, search for supervisor names by typing at least two letters, or select one or more supervisors from the drop-down list.
   • Only people who have permission to supervise users are displayed in the list.
3. Save the sync, or continue to the next configuration section.

You can make changes to an existing configuration if required. It is important to note that when configuration settings change, there may be mapping errors that require correction.

To edit the sync configuration: 

1. From the Sync Configurations page, click the name of the sync you'd like to modify.
2. When the configuration opens, go to the Options menu and select Edit Configuration.

   

3. On the Edit Sync Configurations window, make the required changes.
4. Click Save.

Once applied, any properties not compatible with the new configuration settings will be highlighted. To run a sync using the new configuration you must clear all mapping errors and save the configuration.

If a sync configuration is no longer required, you can delete it to ensure it's not accidentally run. Deleting a sync removes the connection between xMatters and ServiceNow, but it does not delete any data brought into xMatters from previously run syncs.

To delete the sync configuration:

1. From the Sync Configurations page, click the name of the sync you'd like to delete.
2. When the data sync opens, go to the Options menu and select Delete.

   

3. Confirm the deletion.

The sync is deleted from the Sync Configurations page.