Integrating with Salesforce (public preview)

You can now create Salesforce incidents by using Instana. After you create a Salesforce alert channel in the Instana UI, all alert notifications that are sent by Instana can be sent to Salesforce through Salesforce Incident Object Model.

Setting up the Salesforce alert channel

Before you set up the alert channel in Instana, you must create a connected app within a Salesforce organization. For more information about the setup process, see Configure a Connected App for the OAuth 2.0 Client Credentials Flow.

Creating a Salesforce connected app

You must configure the Salesforce connected app that connects to Instana with the following options on the setup page:

  • Connected App Name: The name of the app that connects to Instana

  • Contact Email: The email of someone within an organization that is familiar with Instana to debug any issues

  • Enable OAuth Settings: You must enable OAuth because Instana uses OAuth to authenticate with Salesforce.

  • Callback URL: Due to the use of client credentials for the Client Credentials Flow for Server-to-Server Integration with Salesforce, Instana does not use the callback URL for authentication. You can enter your organization's Instana URL, such as https://<instana_org_name>.instana.io

  • Selected OAuth Scopes: The following scopes must be added:

    • Manage user data via APIs (api)
    • Perform requests at any time (refresh_token, offline_access)

  • Enable Client Credentials Flow: You must enable Client Credentials Flow because Instana uses the Client Credentials OAuth Flow as part of the Salesforce integration.

See the following example of connected app settings:

Salesforce Connected App Example

Configuring an execution user for the flow

You must configure an execution user in your Salesforce organization. Make sure that the profile that is assigned to the user have the creation, reading, updating, and deletion permissions of Salesforce incident objects.

To configure permissions, follow the steps:

  1. Create a profile by clicking Administration > Users > Profiles in the Salesforce UI. After you create a new profile, edit the configuration by clicking Edit. Then, modify the Standard Object Permissions section so that a new profile can "modify all" incidents as seen in the following screenshot:

    Salesforce Profile Permission Example

    You can edit the user profile to be restricted or open as needed.

  2. Create a user that uses this profile. This user is assigned as the execution user for the previously created connected app. To create a user, click Administration > Users > Users > New User, enter the necessary data, and then select the previously created user profile.

  3. Add the user that you created as an execution user to the previously created connected app by viewing the newly created connected app and clicking Manage.

    Salesforce app manage location

  4. On the App Manager page, click Edit Policies.

    Salesforce Edit Policies location

  5. On the connected app policies page, scroll to the Client Credentials Flow section, and enter the name of the user that has the permission to modify all the Salesforce incident objects. Then, click Save.

    Salesforce Edit Policies location

Now, you can use the connected app to create and modify Salesforce incidents in an organization.

Configuring the Salesforce alert channel

You must add the Salesforce alert channel by clicking Settings > Alert Channels > Add Alert Channel in the Instana UI.

To make requests for incidents and to generate Bearer tokens, you need to point the Salesforce Organization URL field to an organization's Salesforce instance URL. An example of such a URL is https://<salesforce_org>.my.salesforce.com. For more information, see My Domain Hostnames, specifically the 'Login' hostname type.

Salesforce Alert Channel

Alert payload details

The alerts are received when an event is triggered in the Instana UI. A URL endpoint is provided when you create a Salesforce alert channel. The alert payload that is received is sent to this URL endpoint.

The alert payload contains the following information:

  • Subject: Title of the event
  • Description: The description contains the following fields:
    • Link to Instana
    • Description of the event
    • Entity
    • Host
    • Custom Zone
    • Availability Zone
    • Custom Payloads
    • Instana Incident ID
  • DetectedDateTime: Start time of event
  • EndDateTime: End time of event
  • Impact: The Instana events that have a critical severity are mapped to the high impact. The Instana events that have a warning severity are mapped to the medium impact, and the rest of the events are mapped to the low impact.
  • IsMajorIncident: The Instana events that have a critical severity are set to true.
  • Priority: The Instana events that have a critical severity are mapped to the critical priority. The Instana events that have a warning severity are mapped to the moderate priority, and the rest of the events are mapped to the low priority.
  • ReportedMethod: The source through which the incident was created. The information is always prefilled to Instana.
  • StartDateTime: Start time of event
  • Status: The Instana events that are open are mapped to new. The Instana events that are closed are mapped to closed. The Instana test events are mapped to resolved.
  • Urgency: The Instana events that have a critical severity are mapped to the high urgency. The Instana events that have a warning severity are mapped to the medium urgency, and the rest of the events are mapped to the low urgency.

As part of the Salesforce integration, incidents that are opened through Instana must also be closed through Instana. When a close alert notification goes out, Instana sends a request to Salesforce that changes the status of the Salesforce incident from New to Closed. In other alert channels, you get a separate closed alert notification that looks like a new alert. The alert types that do not send out close notifications have their Salesforce incident start with their status as resolved.

Salesforce example for an incident that is created by Instana

The following example shows the alert payload of a test event with type Issue and status as Resolved:

Salesforce Example