All REST-based integrations require someone to authenticate REST calls when injecting signals. This user needs to be able to create and work with alerts, but usually doesn't need to access any administrative settings (unless working with some customized or packaged integrations – more on this later). xMatters includes a default "REST Web Service User" role that should provide all of the necessary permissions for most integrations.

When you install an integration using a workflow template, the new configuration automatically authenticates REST API requests using your credentials (or the account you're using to install the integration). But this user appears as the initiator or submitter of signals from the integration (in messages, the Communication Center, alert reports, etc.), so if you're customizing integrations, or want to install multiple integrations into the same deployment, you might want to create a separate user for each integration.

Creating separate users for each integration makes it easier to identify which integration is making specific requests in the reports or logs and allows you greater control over which systems can submit requests to xMatters.

If you create separate users for each integration, we also recommend using a standard convention to make it easier to find all the integration users at once. For example, you might decide to give all of your integration users the same last name then give each one a first name that matches their integration.

For Free customers: your system has an "Integration User" already configured with the REST Web Service User role. You might want to use this as the integration user for all your integrations so you're only using one license from your limited supply; just keep in mind that this user will appear as the initiator of alerts for all integrations. If you don't want to create an additional user, just make sure you've changed this user's password from the default before you skip to the next section.

To create an integration user:

1. Log in to the target xMatters system.
2. On the Users listing page, click Add Users.
3. Enter the appropriate information for your new user. Because this user appears as the initiator or submitter of alerts from the integration (in messages, the Communication Center, alert reports, etc.), we recommend you identify the user as specific to this integration – for example:
   • First Name: AppDynamics
   • Last Name: Integration
   • User ID: appdynamics
4. In the Roles area, add the REST Web Service User role (and any other roles required for your specific integration).
   • Some integrations require that you grant access permissions to the source application to act on your behalf in xMatters.
5. Click Add.

Make a note of the user credentials and details. Use this user's credentials if you need to set up an xMatters user in the source application.

Once you've created an integration user, make sure they have permission to access the correct integrations. For both built-in and packaged integrations, this means adding them to the Access Permissions list.

To assign access permissions:

1. In xMatters, click the Workflows tab, and then do one of the following:
   • On the Workflows tab, click the gear icon beside the name and select Editor Permissions.
   • When viewing a workflow, click the gear icon at the top and select Editor Permissions.
2. In the Editor Permissions dialog, use the search bar to locate the integration user you created above.
3. Click Save Changes.

Some packaged integrations include a data synchronization feature that retrieves user and group data from another system and automatically imports it into xMatters. Check your integration's instructions for more information on how to use the data sync feature.

Whether you're synchronizing information from another system or entering it all manually, it's a good idea to get as much of your user, device, and group information into xMatters as you can before putting your integration to use. If you're just testing an integration out to see what it can do, creating a couple users and a sample group can help not only streamline the integration process, but also give you a better idea of the integration's capabilities.

For information about creating users and groups in xMatters, see:

• Manage users
• Manage groups

You can control what access the integration user has to add, view, and act on users and groups in xMatters.

Enable the integration user to perform data syncs of user and group information

As mentioned in the section above, some packaged integrations include a data sync feature. If you're installing an integration that includes a data synchronization component, the integration user needs to be assigned a role in xMatters that has permissions to add users and groups (for example, Group Supervisor or Full Access User). Remember, for a REST call to be successful, the authenticating user must have permission to perform the same task in the xMatters web user interface.

Limit the integration user's permissions related to other users

By default, the "REST Web Service User" role assigned to the integration user can act on all other roles (and therefore all users) in xMatters. Depending on your environment, this might not be desirable.

If needed, you can change the permissions of this role: go to Admin > Roles, then select the REST Web Service User and configure the permissions this role has on other roles. This changes the permissions for all users assigned to this role. See Managing roles and functions for more detailed information.

Allow the integration user to view group information

For some integrations to work properly, your integration user needs to be able to view xMatters groups. By default, groups are set to Observed By All, so if you haven't changed that, there's nothing you need to do. However, if you've tweaked your group observers, you might need to give your integration user the ability to view a group.

There are two ways you can accomplish this:

• Assign the Group Monitor (or Group Supervisor) role to the integration user. This gives the integration user the ability to view (or act on) all groups in xMatters. See Manage users for instructions.
• Go to the group you want the integration user to be able to view and add the "REST Web Service User" role to the list of Observers (if the group is not already set to Observed By All). See Group options and settings for instructions.

For most integrations, the easiest way to get started is to install one using a workflow template. But you may also want to use an integration that someone else has already created and customized, one for a product that isn't available as a workflow template yet, or an older version of an integration. To use one of these packaged integrations, go to the Workflow page and click Import.

One thing to note about imported workflows that is particularly relevant to integrations: when they are exported (in other words, packaged) then imported, they retain many of the settings and properties that were in place during the export. For example, if a workflow contains a form that is enabled as "Web Service Only" when it is exported, that form is automatically enabled as "Web Service Only" when you import the workflow into xMatters.

See our topic on managing workflows for more information on what is retained during the export-import process. It's a good idea to check the imported workflow to make sure the settings suit your system and business purposes. Some things to check include:

• Authentication settings
• Endpoints
• Enabled or disabled forms
• Form layouts
• Default recipients

For more information about packaged integrations or to download one, visit the xMatters Support site.

You can set the default recipients for an integration on the form's Layout tab.

1. Navigate to the Forms tab of your workflow, click Edit > Layout.
2. In the Recipients section, add the default groups and users you want to receive notifications for this integration's alerts.
3. Click Save Changes.

To extend your integration beyond its built-in functionality, you might need to first convert it to a workflow.

To convert your integration:

1. Do one of the following:
   • On the Workflows tab, click the gear icon for a built-in workflow and select Convert to Custom Workflow.
   • When viewing a workflow, click the gear icon on the configuration page and select Convert to Custom Workflow.
2. On the warning dialog window that appears, click Convert to Custom Workflow.

That's it – you're done. For information on working with a custom workflow, see Manage workflows.