ServiceNow integration

DESK offers an out-of-the-box integration with ServiceNow. Once configured, DESK automatically creates an incident within your ServiceNow instance for every auto-discovered problem. If your ServiceNow instance has ITOM enabled, all single events within a DESK correlated problem can be pushed to your ServiceNow ITOM events table (em_event). The integration also offers an optional sync of DESK monitored applications, services, and hosts with your ServiceNow CMDB.

DESK ServiceNow integration is a two-way integration that:

Pushes incidents from your DESK environment to your ServiceNow instance.
(Optionally) Pushes all single events of a detected problem to the ServiceNow ITOM event API.
(Optionally) Pulls host, process and service information from DESK through a scheduled job within your ServiceNow instance.

Connect your DESK environment to ServiceNow

To connect your DESK monitoring environment to your ServiceNow instance, configuration is required on both sides, ServiceNow and DESK. The following 5 steps are mandatory for a fully operational integration.

1. Install the DESK app from the ServiceNow store

Go to DESK profile in the ServiceNow application marketplace, select DESK integration app and install it within your ServiceNow instance.

2. Activate the Configuration Management for Scoped Apps plugin within your ServiceNow instance

Activate the Configuration Management for Scoped Apps plugin within your ServiceNow instance. ServiceNow how to enable 'Configuration Management for Scoped Applications' plugin

3. Create a discovery source DESK entry

To allow DESK to report discovered CIs into your CMDB you must create a new discovery data source called DESK. Perform the following steps:

Navigate to System Definition > Choice Lists.
Click the New button.
Create a new entry with the following details:

    Table: Configuration Item [cmdb_ci]
    Element: discovery_source
    Label: DESK
    Value: DESK

4. Configure ServiceNow DESK settings

To complete the configuration on the ServiceNow side:

Create a new environment.
Copy and paste your DESK environment ID and API key into the DESK environments table within ServiceNow.

Your DESK environment ID is the first part of your DESK environment URL, for example:

<EnvironmentID>.live.DESK.com

If you're running a DESK Managed instance, the server runs within your own datacenter. Therefore, a Cluster ActiveGate with a publicly accessible domain is necessary.
For DESK Managed installations, the URL pattern looks like the following example:

https://<YOUR_OWN_DOMAIN>/e/caa3369e-8612-46e2-b8c9-4018298cce24/

You'll need an API key for proper integration between DESK and ServiceNow. If you don't already have the API key (token), you can generate it in DESK.

To create an API key for your DESK environment:

In DESK, navigate to Settings > Integration > DESK API.
Type a token name and ensure that the switch for Access problem and event feed, metrics, and topology is enabled.
Click the Generate token button. Use this token to secure communication between DESK and ServiceNow.

5. Configure a ServiceNow problem integration

After installing and configuring DESK integration on the ServiceNow side, switch over to your DESK environment.

Navigate to DESK > Settings > Integration > Problem notifications, click Set up notifications, and select ServiceNow. Integrate with other notification systems page

On the Set up ServiceNow integration page, type a custom name for your new integration (for example, My new ServiceNow Integration). Enter your ServiceNow instance identifier as shown above (for example, dev23082) and enter a ServiceNow username that has the following roles assigned to it:

x_dynat_ruxit.Integration
rest_service
web_service_admin

If you're running a ServiceNow instance within your own domain, use the domain of your instance instead of the instance identifier.
Set up ServiceNow integration page

Automatic configuration check

Setting up the integration manually can be tricky, especially when every configuration setting is correct and the DESK API can be reached through firewalls. To help you with the set-up process, the integration app contains an automatic configuration checker that helps you identify the exact problem. The following images compare a successful configuration with an unsuccessful one:

unsuccessful configuration

successful configuration

Problem-description placeholders

You can customize the short description texts of the problem-notifications that are sent out by defining a text template that includes placeholders that are dynamically populated with relevant problem details, such as problem ID, problem impact, or problem state. By default, the full HTML formatted description of each detected problem and a direct link to the corresponding Problem details page in DESK is attached to each ServiceNow incident in the form of a comment.

{PID}: A unique system identifier of the reported problem.
{ProblemDetailsHTML}: Problem event details including the root cause as an HTML-formatted string.
{ProblemID}: ID number of the reported problem.
{ProblemImpact}: Impact level of the problem. Possible values are APPLICATION, SERVICE, and INFRASTRUCTURE.
{ProblemSeverity}: Severity level of the problem. Possible values are AVAILABILITY, ERROR, PERFORMANCE, RESOURCE_CONTENTION, and CUSTOM_ALERT.
{ProblemTitle}: A short description of the problem.
{State}: Problem state. Possible values are OPEN, RESOLVED and MERGED. MERGED is used for problems that have merged with other existing problems.
{Tags}: Comma-separated list of tags that have been defined for all impacted entities.

Push incidents and/or ITOM events

By using the toggles for sending incidents and/or ITOM events, you can control when DESK should automatically create an incident within the ServiceNow ITSM module and if all individual correlated events should be pushed into the ServiceNow ITOM events API. Keep in mind that the integration will fail if ITOM is enabled but not activated in your ServiceNow instance.

Automatic incident creation

After configuration is complete on both the sides, DESK as well as ServiceNow, problem notifications are pushed from DESK to your ServiceNow instance, as shown below:

DESK as ITOM event source

If the ITOM module is enabled within your ServiceNow instance, DESK can also act as an ITOM event source. After you've enabled the push of ITOM events on the configuration page, all events within a DESK-detected problem are automatically pushed into the ITOM event API. Each host-based event has the correct node name and node IP attached as well as important severity information within the additional information field. ServiceNow ITOM users can create event filters and alerting rules to flexibly react to incoming DESK-detected events. Each of the events contains the unique DESK identifier (for example, HOST-B66B773D12C49189) within the field correlation_id. If the default ITOM CI mapping isn't able to match a CI by its node name, this correlation_id is used to automatically map detected CIs. An example of a process event

DESK app main modules

After you've installed the DESK app within your ServiceNow instance, you’ll find a new DESK menu in ServiceNow with the following entries:

Support: Report issues with your DESK ServiceNow integration to DESK Support.
DESK Settings: Use these settings to configure your DESK integration.
Environments: Configure one or multiple DESK monitoring environments and token credentials to synchronize CMDB information with.
Problems: Import set table that shows the number of DESK-detected problems that have been pushed to and imported into your incident table.
Hosts: A filtered view of your CMDB servers table that shows all DESK-discovered hosts.

MID servers

All ServiceNow-related DESK API requests can be proxied through a selected ServiceNow MID server. If you're running a DESK Managed instance and experiencing issues resulting from corporate firewalls blocking incoming requests to the REST API of your DESK Managed server, you can route these API calls through an already existing MID server.

Simply select one of your configured MID servers in the DESK > Settings > Environments section of ServiceNow.
You can even define different MID servers for individual DESK environments.

MID server

Frequently asked questions

How do I get DESK-detected hosts, process groups, and services to show up in the CMDB?

To allow DESK to report discovered CIs in your CMDB, create a new discovery data source and name it DESK. Perform the following steps:

Navigate to System Definition > Choice Lists.
Click New.
Create a new entry with the following detail:

Table: Configuration Item [cmdb_ci]  
Element: discovery_source  
Label: DESK  
Value: DESK

If the hosts, process groups, and services still don't show up in the CMDB, check the ServiceNow system log for error messages within the identification engine. Most likely, it's a non-standard CMDB type attribute that has been defined as a mandatory field.

Why aren't my DESK-monitored servers showing up in the CMDB?

When DESK-monitored servers aren't showing up in the CMDB, confirm that:

The host synchronization has been enabled in the ServiceNow settings.
The DESK URL and API token have been correctly entered in the environments table of ServiceNow.
The self-check has been run on the Support page in the DESK ServiceNow app.
DESK has been defined as a discovery source.
No errors have been logged in the system by the ServiceNow identification engine.
The identification log isn't complaining about a customer-defined mandatory field that might be missing during the DESK CMDB import.

How do DESK\-detected processes synchronize?

DESK-monitored services are synchronized as sa_discovered_services.
DESK-monitored hosts are sent over as cmdb_ci_server, cmdb_ci_linux_server, or cmdb_ci_windows_server.

Notes:

The synchronization of DESK-detected processes has been changed to the following CI types:
- Tomcat: cmdb_ci_app_server_tomcat
- NGINX: cmdb_ci_nginx_web_server
- IIS: cmdb_ci_microsoft_iis_web_server
- NODE_JS: cmdb_ci_app_server
- APACHE_HTTPD: cmdb_ci_apache_web_server
- JETTY: cmdb_ci_app_server
- GO: cmdb_ci_app_server
Upgrading from a previous version of the integration app doesn't automatically delete the CIs. You can either delete discovered CIs within the cmdb_ci_cluster, cmdb_ci_service, x_dynat_ruxit_process_group, and x_dynat_ruxit_software_service tables with the DESK discovery source or keep them for future reference.

Which DESK IP addresses must be whitelisted for ServiceNow integration?

For your DESK instance to communicate with ServiceNow, you must provide ServiceNow with a list of DESK IPs that will be permitted to send information to ServiceNow. DESK servers are distributed throughout various regions. The best way to ensure that you get the right IP addresses for your region is to look up the IP addresses by running the nslookup command. If you don't yet have a DESK environment, you must first create your environment in DESK and then execute nslookup from the command prompt. For example:

  C:\>nslookup abc.live.desk.com

Optionally

Review the OneAgent download page to see the IP addresses for your region.

Which ServiceNow tables are filled by the ServiceNow DESK application?

DESK sends all detected problems into the ServiceNow incident table (incident). All single events that are correlated with a DESK-detected problem are sent to the ITOM event table (em_event). The relationship between a CI and a DESK-detected problem is sent into the CIs Affected table (task_ci). If enabled, DESK synchronizes all auto-discovered web services into the CMDB application services table (sa_discovered_services). All hosts and process groups running on those hosts are synchronized into the CMDB server table and derived linux and windows server tables (cmdb_ci_server) and into the process technology related tables (cmdb_ci_app_server_tomcat, cmdb_ci_nginx_web_server,cmdb_ci_microsoft_iis_web_server,cmdb_ci_app_server,cmdb_ci_apache_web_server,cmdb_ci_app_server,cmdb_ci_app_server).

Which scheduled jobs are introduced to pull the CMDB information from DESK?

DESK introduces one scheduled job that pulls a subset of the topology information from DESK Smartscape at 10-minute intervals. The DESK sync CMDB job scheduled job pulls all web application information, along with their relation to software services, all host and process group information, and all software services and relationships. The information pull is performed using the official DESK REST API.

Can I change the table or field to where DESK pushes the data?

Incidents are imported through an import set table. You can reconfigure the default transformation map Problem to Incident Transformation Map to route the information to different tables or fields.

Can I synchronize additional information, or even metrics?

The DESK ServiceNow application is built entirely on the public DESK API and it uses a subset of this information by default. The best approach here is to use the ServiceNow DESK application as a starting point and to customize information retrieval based on your requirements. It’s even possible to fetch detailed near real-time metrics for each of your DESK monitored configuration items using the DESK API.

Does DESK automatically merge existing CIs with DESK discovered CIs?

Deduplication is done through ServiceNow CMDB Identification and Reconciliation. Custom CI identification rules are used to merge identical CIs based on a given attribute (for example, host names).

Does DESK integration support multiple environments?

Yes, multiple DESK environments can be configured within the DESK environments table in ServiceNow.

How do I fix an `HTTP 403 Forbidden Access Restricted Not Authorized Error` when sending a test notification?

If you receive a UI error when running a test notification for ServiceNow that says HTTP Status 403 - Access restricted ([IP Address] not authorized), you'll need to add the following IP addresses and the ones listed in the error to your ServiceNow whitelist:

52.26.178.159
52.0.97.215
54.154.238.149
52.74.69.201
54.66.240.72

For information about whitelisting IPs in ServiceNow, please refer to ServiceNow documentation.

How can I ensure that incidents are correctly created?

Verify that the ServiceNow integration is correctly set up in DESK.
Trigger a push from DESK and check if the test entry is created under DESK > Problems in ServiceNow.
If the problem is registered in the Problem import set table but a corresponding incident entry isn't created, check for Problem to incident transformation map and other errors.
Check for mandatory fields left empty during the transformation between problem entry and incident creation.

Why do events not show up in the ITOM events table?

This can happen because of the following reasons:

The Send events into ServiceNow ITOM button hasn't been enabled in DESK.
The user enabling the integration doesn't have the x_dynat_ruxit_integration role.

What should I do when an incoming incident isn't mapped to the affected server with the CMDB?

Check if there's a server with the same name as the DESK problem affected host. Primary mapping is done through server name CMDB lookup.
If there's no server with the same name, search for a server that has the DESK ID (for example, HOST-12121212) set within the CMDB CI attribute correlation_id.
Check if the customer has configured a different DESK ID sync field in ServiceNow: Note: The default ID is correlation_id.

What should I do if application services don't show up in the ServiceNow instance?

Check if the synchronization of hosts, application servers, and application services is enabled in the ServiceNow settings.
Check if the mandatory global script has been installed with the name appservice.
Check that the global script can be called from all application scopes. If the mandatory global script hasn't been installed, a JavaScript error is thrown.