ServiceNow application alert channel (public preview)

The ServiceNow application alert channel propagates alert notifications between Instana and ServiceNow application. The IBM Instana application which runs on ServiceNow provides the following functions:

  • propagates Instana events to ServiceNow Incident table or IBM Instana intermediate tables
  • propagates notes and AI incident summarization results of Instana incidents to corresponding ServiceNow Incidents that were created by the IBM Instana application
  • propagates Instana events closure status to ServiceNow incident table or IBM Instana intermediate tables
  • propagates work notes, additional comments, and field changes from ServiceNow incident table to Instana
  • propagates event closure when the status of incidents is changed to Resolved or Closed

Installation prerequisites

Instana currently supports only SaaS deployments.

The ServiceNow application accesses the following ServiceNow tables:

  • Incident (incident) Read/Write
  • Priority Data Lookup (dl_u_priority) Read Only
  • User (sys_user) Read Only
  • Group (sys_user_group) Read Only
  • Group Member (sys_user_grmember) Read Only
  • Table (sys_db_object) Read Only
  • Dictionary Entry (sys_dictionary) Read Only

The propagated events from Instana are stored in one of the following IBM Instana intermediate tables based on the event types:

  • IBM Instana for Incident (x_ibm_instana_ibm_instana_for_incidents)
  • IBM Instana for Issue (x_ibm_instana_ibm_instana_for_issues)
  • IBM Instana for Change (x_ibm_instana_ibm_instana_for_change)
  • IBM Instana for Monitoring Issue (x_ibm_instana_ibm_instana_for_monitoring_issues)

To send alert notifications from Instana to ServiceNow in real time, create a ServiceNow application alert channel.

Creating a ServiceNow application alert channel

Configuring the ServiceNow application at ServiceNow

The ServiceNow application is now available at the ServiceNow store. You can download and install the IBM Instana application from the ServiceNow application store.

Configuring the user at ServiceNow

You must create a user that the ServiceNow App alert channel in the Instana instance uses for accessing the IBM Instana application in ServiceNow.

  1. Click All and search User Administration. Click User Administration > Users.
  2. Click New on the upper right to create a new user.
  3. Enter the User ID. This is the username when the user signs in to this ServiceNow instance.
  4. Fill the other fields based on the user information and click Submit to create the user.
  5. Go to the newly-created user page and click Set Password. In the pop-up window, click Generate that creates a password for the user. Copy and save the password, since it is needed for when the user logs in for the first time.
  6. By default, the "Password needs reset" checkbox is checked after the password is created and saved successfully. Uncheck this checkbox.
  7. Check the checkbox "Web service access only". ServiceNow Create User
  8. Authorize the application access to the user by clicking the Role tab.
  9. Click Edit. In the search tab, search and select x_ibm_instana.user, sn_incident_write, data_lookup_admin, personalize_dictionary, and sn_cmdb_user. Then, add them into the Roles list. Alternatively create and assign a role which can access the tables listed above. ServiceNow Add Access
  10. Click Save to save the changes.
  11. Click Update to save the updates. On the user page, the roles are added to the role list. There are more than 3 roles in the list because multiple subroles are included in the sn_incident_write and data_lookup_admin. ServiceNow Save User

Configuring the alert channel in Instana

  1. To create a ServiceNow alert channel, on the left navigation bar of the Instana UI, click Settings > Global Settings > Events & Alerts > Alert Channels.

  2. Click Add Alert Channel and select ServiceNow ITSM app.

  3. Enter the name for the new channel.

  4. The integration uses the basic authorization method to interact with ServiceNow application scripted REST API.

    • The URL field must point to the endpoint of the ServiceNow instance that Instana communicates with. For example, https://example.service-now.com.

    • The Username field must be the name of an existing ServiceNow user who has the roles to access the ServiceNow application, which is mentioned and set up in the previous section. Use the user ID of the user that is created in ServiceNow as the username.

    • The Password field must contain the password of the ServiceNow user whose user ID was entered in the Username field.

  5. Click Advanced. Use the following two radio button options to enable the two-way communication feature between Instana and ServiceNow.

    • Allow Instana to send events to the ServiceNow incident table (Default): If this radio button is selected after you propagate events to the IBM Instana intermediate tables, IBM Instana application updates the incident table in ServiceNow. This opens and closes ServiceNow incidents in sync with Instana's incidents, syncing notes and activity between Instana and ServiceNow. Any existing business rules to modify your incident table in ServiceNow also function normally. All the ServiceNow users who can access the ServiceNow incident table must have the following 5 roles:

      • x_ibm_instana.ibm_instana_for_tenants_user
      • x_ibm_instana.ibm_instana_for_incidents_user
      • x_ibm_instana.ibm_instana_for_change_user
      • x_ibm_instana.ibm_instana_for_issue_user
      • x_ibm_instana.ibm_instana_for_monitoring_issue_user

    • Restrict Instana to intermediate table propagation only: If this radio button is selected, Instana propagates only events data to the IBM Instana intermediate tables without any further updates to the ServiceNow incident table. Your ServiceNow business rules can access these IBM Instana intermediate tables.

  6. Click Create to create the ServiceNow alert channel. ServiceNow Create Alert Channel

Alerting examples

When Allow Instana to send events to the ServiceNow incident table option is checked, the following information is added to corresponding field of the ServiceNow incident ticket:

  • The Short description field of the incident is set to the title of the event as it appears in the Instana UI.

  • The State field of the incident is set to New if Assigned to field is empty. If this ServiceNow incident ticket is assigned to a specific user in ServiceNow, the State becomes In Progress.

  • The Impact field is set depending on the severity of the event in Instana. Incidents for events that are detected with the type online, offline, and change have the 3 - Low impact. For events with the type issue, incident, and monitoring issue, the value of the Impact field depends on their severity in Instana. Events with the Warning severity in Instana have the 2 - Medium impact, and events with the severity Critical have the 1 - High impact.

  • The Description field is set depending on the event type. In general, it includes most of the information that is sent by using other Instana alert channels. The information is represented in Key: Value format, with -- denoting nesting of the key-value pairs. The following information is added to the Description field of the ServiceNow incident ticket:

    • The Type field is set based on the value of event type in the Instana, it includes incident, issue, change, monitoring_issue. Each type of events is saved in the corresponding intermediate table.

    • The Suggestion field is set based on the value of fixed suggestion in the Instana.

    • The Severity field is set based on the mapping Instana defined: the value -1 stands for Change, 5 stands for Warning, 10 stands for Critical, and other values stand for Info. ServiceNow supports severity promotion. When the severity of an Instana event gets promoted from Instana, the corresponding fields in ServiceNow incident change, such as Urgency and Priority. Also, the Short Description is updated with a "Severity Upgraded -" prefix. ServiceNow Severity Promotion ServiceNow Severity Promotion Because the Description field is editable, Instana does not update the Severity field value after a severity promotion. The Severity field keeps its original value.

    • The Link field contains the website link that redirects you to the page of the current incident in the Instana.

    • The Custom Payloads that are defined at Settings > Global Settings > Events & Alerts > Alerts is mapped to the corresponding field of Incident table. If there is no matching field, it is added to the Description. You can see some custom payloads fields on the ServiceNow incident information page. The field mapping does not support short_description, description, state, or priority fields. Note that this function does not support for “Monitoring Issue” event.

    • For assignment_group on ServiceNow, set the value by using the Group Name or sys_id of the Group Name.

    • For assigned_to on ServiceNow, set the value by using the User Name, User ID or sys_id of the user. If both assignment_group and assigned_to fields are added in the Custom Payloads, make sure that the assigned_to user is a member of the assignment_group group in ServiceNow. Otherwise, only assigned_to field is set and assignment_group is empty. If a valid assigned_to value is set, the State of Instana incident is set to In Progress instead of New.

    • For the remaining fields:

      • key: Column name of ServiceName Incident table.
      • value: Value of the field. To specify a value of reference type, use sys_id.

      For example, to set the IBM DLA to the Configuration Item field, use cmdb_ci as the key, which is a column name, and use 46a0583aa9fe1981002a20ec72ca72f3 as the value, which is a sys_id of IBM DLA.

    ServiceNow Custom Payloads

ServiceNow UI pages

Several UI pages in the ServiceNow app show information about Instana events.

ServiceNow incident table UI

See the following example of an Instana incident that corresponds to the event with the incident type on ServiceNow incident table UI:

ServiceNow Incident UI

IBM Instana tab UI

Below the ServiceNow incident table UI, click the tab that reads, IBM Instana, and you can see the information on the IBM Instana tab UI:

ServiceNow IBM Instana Tab

IBM Instana intermediate table UI

From the navigation bar, click All and search IBM Instana. Select the options based on the event type. For incident, click IBM Instana for Incidents. You can see the intermediate table.

ServiceNow IBM Intermediate Table UI

Click the hyperlink at column Instana Event ID, it can direct you to the IBM Instana intermediate table UI:

ServiceNow IBM Intermediate Table UI

In a similar way, you can check the IBM Instana intermediate table UI for tenant table: From the navigation bar, click All and search IBM Instana. click IBM Instana for Tenants. You can see the intermediate table.

ServiceNow IBM Intermediate Tenant Table UI

Click the hyperlink at column Instana ID, it can direct you to the IBM Instana intermediate table UI:

ServiceNow IBM Intermediate Tenant Table UI

On open issues or incidents

See the following example of the Description field of an incident that corresponds to the event with the incident type:

ServiceNow Online Incident Description

Synchronize the notes and activities

If you selected the Allow Instana to send events to the ServiceNow incident table radio button on the Instana ServiceNow application alert channel, the notes you add at an open Instana incident emit and synchronize to the corresponding incident at ServiceNow incident table. In addition, the work notes, additional comments and activities you add or operate at ServiceNow incident table synchronize to the corresponding Instana incidents.

The following scenarios describe the notes and activities synchronizing feature:

The note added at Instana incident emits and synchronizes to ServiceNow

  1. An incident is created at Instana and a note "Note Test (NB Event #3)" is added by user "Kevin Wu" in the Notes and activity window. ServiceNow Instana notes
  2. You can see this note at the "Notes" tab on the corresponding ServiceNow incident table UI, including the note content, IBM Instana instance information, IBM Instana username, and the timestamp. ServiceNow notes

The work notes and activities added or generated at ServiceNow emits and synchronizes to Instana

  1. This is the ServiceNow incident that is created by Instana. ServiceNow incidents
  2. Change the Impact fields from 1 - High to 2 - Medium and reassign this incident from Antony Alldis to Tash Dubrovska. The Priority field also changes based on the Impact field from 3 - Moderate to 2 - High. ServiceNow incidents changed
  3. Add a single work note "Work Notes Test by System admin (From ServiceNow)" and one more work note for the updates we made in step 2 by user "System Administrator". Then, click Update button. ServiceNow incidents work notes
  4. You can see the following prompt after your update complete. ServiceNow incidents prompt
  5. Go to the corresponding incident page at Instana. In the "Notes and activity" window, you can see the synchronized work notes and activities. ServiceNow Instana sync

On close issues or incidents

If you select the Allow Instana to send events to the ServiceNow incident table radio button on the Instana ServiceNow application alert channel, ServiceNow incidents are closed automatically when corresponding events are closed in Instana. In addition, Instana incidents or issues are closed when corresponding incidents are manually resolved or closed in the ServiceNow incident table.

The following scenarios describe the incident closing feature:

An incident that is closed in Instana is reflected in ServiceNow

  1. An incident is created in Instana, and the state of the incident is active.

    ServiceNow active incident

  2. You can find this incident with the New state in the ServiceNow incident table.

    ServiceNow active incident with New state

  3. When the incident is closed in the Instana, the incident status is synchronized in the ServiceNow incident table.

    ServiceNow incident closed by Instana

  4. The same Instana incident closes in ServiceNow with its resolution information populated.

    ServiceNow closed incident sync

You can choose the closure state you want to set for ServiceNow incident when corresponding events are closed in Instana. Currently, the following closure states are supported: 6 - Resolved, 7 - Closed, and 8 - Canceled. You can configure the mapping closure state in IBM Instana for Tenants table.

Go to IBM Instana for Tenants, find the corresponding record in the table via Instana ID column, which is using {tenant unit}-{tenant} format (for example, if the Instana tenant is instana and tenant unit is test, the Instana ID should be test-instana). There is a column called Map Instana Closure Event. You can set the ServiceNow incident closure state by using the state number: 6 for Resolved, 7 for Closed, and 8 for Canceled. The default value is 7 - Closed.

For example, if you change the Map Instana Closure Event value from default 7 - Closed to 6 - Resolved and when the incident is closed in Instana, the ServiceNow incident state is updated from New to Resolved.

ServiceNow closed incident sync

You can see detailed information about the state update in the Notes section.

ServiceNow closed incident sync

An incident that is closed in ServiceNow is reflected in Instana

  1. An incident is created at Instana, and the state of the incident is Active.

    ServiceNow active incident

  2. You can find this incident with New state in the ServiceNow incident table.

    ServiceNow active incident with New state in ServiceNow

  3. A user in ServiceNow changes the state of incident to Closed or Resolved with the resolution information and updates the incident.

    ServiceNow resolve or close incident

  4. The incident is closed in the ServiceNow instance and the Instana instance is made aware of this incident close call, as you can see in following prompts:

    ServiceNow close incident

  5. The state of the incident is changed to closed.

    ServiceNow incident closed in Instana

  6. The resolution information of the closed incident that the user entered in the ServiceNow incident table is sent back to Instana.

    ServiceNow incident closed info in Instana

On online, on offline, or on change events

See the following example of the Description field of an incident that corresponds to the event with the change type:

ServiceNow Online Incident Description

Uninstallation

After you uninstall the Instana ServiceNow application from the ServiceNow instance, go to Instana and remove the corresponding ServiceNow ITSM alert channel manually.

To delete the alert channel:

  1. Navigate to Settings > Global Settings > Events & Alerts > Alert Channels.
  2. Search for the ServiceNow ITSM alert channel.
  3. Click the trash icon on the right side to delete the alert channel.

If you reinstall the Instana ServiceNow application, reconfigure the newly installed application by following the previous configuration steps.

Troubleshooting

Saving updates to the ServiceNow ITSM alert channel fails with a 503 error

If you receive the following failure error message when you try to modify an existing ServiceNow App alert channel:

Failed to save: failed to send message to ServiceNow ITSM Application Integration {{ServiceNow instance URL}} with status code: 503. Reason: Service Unavailable

The 503 Service Unavailable error occurs when an HTTP request from Instana to the configured ServiceNow instance fails. This issue happens if you updated the ServiceNow instance URL and the original instance has been deleted or deactivated. If that is the case, you can safely ignore the error. Try saving the updated configuration again.