Synchronize with ServiceNow

The ServiceNow Data Sync allows xMatters to connect directly to the ServiceNow API to import user and role data. Administrators configure the sync by mapping ServiceNow roles to xMatters license types and defining how user properties should be handled. Default values can be set for missing or invalid data, and once the configuration is complete, the sync runs manually and generates a report showing processed records and any issues.

""

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 page.

Once you have created a new sync configuration, you can set which ServiceNow roles you want to map to each license type in xMatters.

" "

To add roles to a license type; 

  1. In the User Sync Rules section, expand the License Type drop-down menu and select the license type. Available options are:
    • Full User
    • Stakeholder User
  2. Expand the Source Role drop-down menu and select the ServiceNow roles to map to the license type.
    • An xMatters license type can contain multiple ServiceNow roles, but a role can only be mapped to one license type. If a user matches criteria for both license types, the Full User license type takes precedence.
  3. To add another License Type option click Add then repeat Steps 1 and 2.

Now that the license types are mapped, you can map the user properties.

" "

  1. In the User Properties Mapping table, map source properties from ServiceNow to their corresponding xMatters properties.
    • xMatters Property: Name of the property in xMatters.
    • Source Property: Name of the property in ServiceNow.
    • Default Value: The default value for the property.
    • 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.
      • Update if empty: Only update the field in xMatters if it was previously empty.
      • Ignore (skip): Make no changes in xMatters.
  2. To map properties other than the listed default properties, click Add Mapping.
  3. Click Save.

After a configuration is saved, click Sync Now to run the data sync.

Only one sync can be run at a time for each configuration and it can take several minutes for a sync to connect, then to complete. Once you click 'Sync Now', do not navigate away from the page, or click the 'Sync Now' button again.

When the sync is finished, you can click the Status link to view a summary report.

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.