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 the integration script to match the instance_url property returned in the authentication response.

1. Select OAuth2 (Salesforce) from the Authentication 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.

For outbound integrations to Slack, users are not required to enter an access token URL, client ID, or client secret. The Endpoints screen for the Slack authentication method contains a 'Connect' button that initiates the OAuth2 process for Slack which requires users to authorize access to their Slack team. The Slack endpoint requests the following OAuth scopes:

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

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