Each communication plan includes a default 'xMatters' endpoint with the base URL set to the hostname of your xMatters instance. This pre-configured endpoint is used to target your xMatters deployment when making web requests to the xMatters REST API from within Integration Builder transformation scripts. You cannot delete or rename the xMatters endpoint in the Integration Builder.

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 Create New Endpoint on the Endpoint tab of the step configuration dialog box. xMatters displays the Endpoints page where you can edit your endpoint settings.
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 communication plan.

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 communication plan.
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. Select the Preemptive check box if you'd like to use preemptive HTTP authentication.

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 communication plan, both of which require a ServiceNow instance with the xMatters App installed. During the configuration of the endpoint, xMatters validates that the app is installed in your instance.

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.
   1. This request checks that the xMatters App is installed in the ServiceNow instance. If the page displays a message that the authentication failed, check your credentials and their permissions in ServiceNow, the Base URL you entered, and that the app is installed in that instance.
4. Once your setup has been successfully verified, click Save Changes.