Steps use the xMatters endpoint to access your xMatters deployment, including the xMatters API. The Base URL shows the targeted hostname.

Built-in steps made to target xMatters use this endpoint to look up information in xMatters without you having to select it (for example, certain steps in the Tools tab). When you create a custom step, you can also set the endpoint type to xMatters to have that step target your xMatters deployment.

The authentication of the request is based on the credentials of the user triggering the flow. For a step using the xMatters endpoint to run successfully, that user needs to have appropriate permissions to make the requests associated with the step. Here are a couple of examples:

• If Ali Samara sends an email to an Email trigger with a Find User step connected to it, the find user request to xMatters uses Ali's credentials. This returns only the information for users Ali has permission to view.
• If you create a specific user to interact with xMatters on behalf of an application (for example, a Jira Integration user) and assign that user the REST Web Service User role, any steps in a flow initiated by this user (for example, an inbound HTTP request from that application) have all the permissions associated with the REST Web Service User Role.

You cannot delete or rename the xMatters endpoint. However, when creating a new custom step, you can assign a label to the endpoint, which you can use to reference the endpoint in the script for the step.

You can configure additional endpoints to use different authentication details, or to target a different URL than that of the default xMatters endpoint.

1. Create a new endpoint. There are a couple of ways to do this depending on where you're working:
   • To configure a new endpoint from the Integration Builder tab, click Edit Endpoints. On the Endpoints page, click Add Endpoint.
   • To configure a new endpoint when working in the script editor of an inbound or outbound integration, click Edit beside Endpoints in the list of available objects. On the Endpoints page, click Add Endpoint.
   • To configure a new endpoint when adding a step to a flow in Flow Designer, click the Components drop-down menu from either the canvas, or the Flows tab.
2. Enter the following information:
   • Name: Type a name that will identify your endpoint within the scripts. (If the name you choose has special characters or spaces, it will need to be escaped within the JavaScript.)
   • Base URL: Type the base URL, including the http:// or https:// protocol, of the target system. You can append additional paths within the scripts.
   • Trust self-signed certificates: This optional setting allows you to target HTTPS endpoints secured using self-signed certificates when testing integrations. The base URL of your endpoint must match the common name specified in the certificate. If the certificate is not valid the integration will throw a security exception and fail. Details of the exception will be reported in the Activity Stream.
   • Authentication: Provide the required credentials. For more information, see Endpoint authentication.

3. Click Save Changes.
   • After you save the endpoint, you won't be able to change the authentication type.

The trust self-signed certificates setting is returned to a default state of disabled when you export a workflow.

1. Click Edit Endpoints in the Integration Builder tab to open the Endpoints page.
   • If an endpoint is used in a flow, the Usage tab appears beside the Settings tab. Check this to see the places your change might impact.
2. Click the name of the endpoint you want to edit, and then modify its details.
   • You can't change the authentication type of an endpoint after it is created.
3. Click Save Changes to apply the new settings to all instances of the endpoint within the workflow.
4. Click Close to return to the Integration Builder.

1. Click Edit Endpoints in the Integration Builder tab to open the Endpoints page.
   • If an endpoint is used in a flow, the Usage tab appears beside the Settings tab. Before you delete the endpoint, you need to remove references to it from those steps.
2. Click the X beside the name of the endpoint you want to delete, and then click Delete Endpoint to confirm.

Select this option when authorization is not required to send requests to the URL.

For basic authentication, the user's authentication credentials are used only at the time the endpoint is configured. The password value is not stored and does not need to be updated if the user changes their password at a later time.

1. Select Basic from the Authentication list.
   • If you accessed the Endpoints page from Flow Designer, this might already be selected because the authentication options are set when the step is defined.
2. Supply a Username and Password credentials for a user with permission to execute API requests on the target system.

3. Clear the Preemptive check box if you don't want to use preemptive HTTP authentication.

The BMC Remedy authentication type is used by BMC Remedy steps in Flow Designer and by the BMC Remedy workflow. When the endpoint is used, it makes a request to the Remedy API for the access token of the user provided in the Authentication settings.

1. Select Remedy Token from the Authentication Type drop-down list.
   • If you accessed the Endpoints page from Flow Designer, this might already be selected because the authentication options are set when the step is defined.
2. Supply the Username and Password of a BMC Remedy user that is a Support Staff member with 'Incident Master', 'Incident User' or 'Incident Submitter' permissions.
   • Because of Remedy's assignment rules, we recommend creating a user specifically for this integration.

3. Once your setup has been successfully verified, click Save Changes.

To allow flow steps to create channels and post messages to Teams, you need to configure a Microsoft Graph API endpoint. Selecting the Microsoft Graph API authentication method lets you initiate the OAuth2 process to authorize access to Teams. Some of the permissions the endpoint needs require admin approval, which you can request during setup if you're not an admin.

Set up the Graph API authentication

1. Select Microsoft Graph API from the Authentication Type drop-down list.
   • If you opened the dialog from the step configuration, this is already selected.
2. Click Connect.
   • A new browser window connects to Teams and starts the connection process. If you're asked to sign in, enter your Microsoft credentials.

3. Accept the permissions (if you're an administrator) or request approval (if you're not).
   • If you're an administrator, review the permissions, select the check box to accept the permissions on behalf of your organization then click Accept.
   • If you're not an administrator, enter the reason why you're requesting approval (for example, "xMatters is essential to streamlined incident resolution") and click Request Approval. You should get an email when your Microsoft administrator has reviewed the request.

If you're an administrator

The xMatters endpoint connects to an Azure application called xMatters Connector. If a user in your organization sets up a Microsoft Graph API endpoint in xMatters, you'll receive an Admin Consent Request. You can review the request details, including who requested the connection and why. Once you've reviewed the request, click Review permissions and consent. See the Azure documentation on managing content requests for details, as well as information on managing access on a more granular level.

The endpoint requests the following OAuth scopes with delegated permissions:

• ChannelMessage.Read.All
• Directory.ReadWrite.All
• Group.ReadWrite.All
• offline_access
• OnlineMeetings.ReadWrite
• Openid
• Profile
• User.Read

For more information on the requested Graph API scopes, see the Graph API documentation.

You can use the Test Authentication feature to verify your credentials, or run the integration or flow the endpoint is used in and check the output in the Activity Stream or Activity panel to determine if the OAuth2 endpoint is configured correctly.

1. Select OAuth2 from the Authentication Type drop-down list.
   • If you accessed the Endpoints page from Flow Designer, this might already be selected because the authentication options are set when the step is defined.
2. Select a Grant Type.
   • OAuth2 support is currently limited to Password (or resource owner password credentials) authorization flow.
3. Enter the Access Token URL for the application.
4. Provide the credentials required by the OAuth2 server being targeted, which may include: Username, Password, Client ID, or Client Secret.
5. Click Test Authentication to send a test request using your credentials to the target Access Token URL.
   1. If your credentials are correct, the Endpoints page displays a success message. If the request failed, the page displays the error details returned by the target system.
6. Once your credentials have been successfully verified, click Save Changes.

The following example demonstrates how an OAuth2 endpoint would be used to query for a protected resource, and print out the response received:

For force.com integrations, the authentication response contains an "instance_url" parameter that is part of the hostname on which the access token is valid; for example, "https://na34.force.com". This portion of the URL is not known in advance, and is therefore unavailable when configuring your endpoint.

To support these integrations, an OAuth2 (Salesforce) endpoint dynamically changes the URL assigned to the endpoint during execution of the step or the integration script so it matches the instance_url property returned in the authentication response.

Set up the Connected App

To use the OAuth2 (Salesforce) endpoint, you first need to set up xMatters as a Connected App on the target system.

1. Create a new Connected App, using the following settings:
   • Connected App Name and API Name: Use a name that will let you easily see what this Connected App is used for (for example, xMatters).
   • Contact Email: Enter a valid email address for a user in the target system.
   • Enable OAuth Settings: Select this check box.
   • Enable for Device Flow: Select this check box.
   • Callback URL: Enter the URL of your xMatters instance.
   • Selected OAuth Scopes: Add "Access and manage your data (api)", "Access your basic information (id, profile, email, address, phone)", and "Perform requests on your behalf at any time (refresh_token, offline_access)".
   • Require Secret for Web Server Flow: Select this check box.

   Other options can be left as their defaults.

2. After you save the Connected App, you should be taken to a screen where you can obtain your secret and ID (or Key). Make note of these so you can use them when you configure the endpoint in xMatters.
3. Finally, edit the Connected App and change the OAuth policies settings.
   • Permitted Users: Select "All users may self-authorize".
   • IP Relaxation: Select "Relax IP restrictions". If you don't select this option, you might need to append the user's security token to the password when configuring the endpoint.
   • Refresh Token Policy: Select "Refresh token is valid until revoked".

   Other options can be left as their defaults.

See the documentation of the target system for details on creating a new Connected App.

Configure the endpoint

1. In the Authentication section, select OAuth2 (Salesforce) as the Authentication Type list, if it's not already selected.
   • Grant Type is set to Password because OAuth2 support is currently limited to the Password (or resource owner password credentials) authorization flow.
2. Enter the Access Token URL for the application (for example, https://login.salesforce.com or https://test.salesforce.com).
3. Provide the credentials required by the target OAuth2 server, which may include: Username, Password, Client ID, or Client Secret. Depending on your settings in the target application, you might need to append the user's security token to the password.
4. Click Test Authentication to send a test request using your credentials to the target Access Token URL.
   • If your credentials are correct, the Endpoints page displays a success message. If the request failed, the page displays the error details returned by the target system.
5. Once your credentials have been successfully verified, click Save Changes.

For outbound integrations to Slack, users are not required to enter an access token URL, client ID, or client secret. Selecting the Slack authentication method lets you initiate the OAuth2 process to authorize access to your Slack team, using the credentials you enter. The Slack endpoint requests the following OAuth scopes:

• users:read
• team:read
• channels:history
• channels:write
• channels:read
• chat:write:bot
• chat:write:user

For the full list of available Slack scopes, see https://api.slack.com/docs/oauth-scopes

1. Select Slack from the Authentication Type drop-down list.
   • If you accessed the Endpoints page from Flow Designer, this might already be selected because the authentication options are set when the step is defined.
2. Click Connect.
   1. A new browser window opens to slack.com to authorize access to your Slack account.

3. Select or sign into the Slack team that you want to authorize xMatters to access.
4. Click Authorize.

Pop-ups must be enabled in your browser to open the Slack authorization page.

Adding the Slack token to API requests

When calling a Slack endpoint in an HTTP request, you must explicitly add a function call to add the Slack token to your API request, or the endpoint will not authenticate.

To add the authentication token, use the following syntax in the relevant portion of your script:

http.authenticate( '<SlackEndpointName' )

For example:

// Prepare the HTTP request

var slackRequest = http.request({

   'endpoint': 'Slack',

   'method': 'POST',

   'path': 'channels.create?token=' + http.authenticate( 'Slack' ) + '&name=' + channelName

});

var slackResponse = slackRequest.write();

var slackBody = JSON.parse( slackResponse.body );

The ServiceNow authentication type is used by ServiceNow steps in Flow Designer and by the ServiceNow workflow.

1. Select ServiceNow from the Authentication Type drop-down list.
   • If you accessed the Endpoints page from Flow Designer, this might already be selected because the authentication options are set when the step is defined.
2. Supply the Username and Password of a ServiceNow user with the x_xma_xmatters.xmatters_rest and itil roles.
3. Click Test Authentication to send a request using the username and password to the ServiceNow instance you entered in the Base URL field.
4. Once your setup has been successfully verified, click Save Changes.