Configuring ServiceNow Observer jobs

Using the ServiceNow Observer job, you can retrieve the configuration management database (CMDB) data from ServiceNow through REST API, using basic authentication credentials.

Important: The ServiceNow Observer supports the cloud and SaaS ServiceNow versions New York, Quebec, Paris, Tokyo.

Before you begin

  • Important: If you have any restrictive EgressNetworkPolicies in place, ensure that they are updated to allow for this inbound connection. For more information, see Create an EgressNetworkPolicy.

  • Important: Ensure that your ServiceNow user account has the required roles to configure this observer and to access resources from ServiceNow. You need the following roles:

    • rest_api_explorer
    • web_service_admin

  • Ensure that you have the ServiceNow service details to hand to complete this observer configuration, such as username, password, and URL.

To add a role to your user account, complete the following steps:

  1. Log in to your ServiceNow instance using an admin account.

  2. Go to User Administration and select Users from the menu.

  3. Select to create or edit a user:

    • To create a user, click New.
    • To edit an existing user, search for, and then select, the user.

  4. From the user's information tab, select the Roles tab, then click Edit.

  5. Assign the required roles to the user.

  6. Click Save, then Update.

For more detailed descriptions of available roles, go to User Administration and select the Roles page. You can also assign other roles with similar privileges to the non-admin account. To find other roles with similar privileges, navigate to System Security and select Access Control (ACL).

Enabling access to the URL routes

To access the URL routes for the topology Swagger documentation, see the Enabling access to URL routes topic.

About this task

ServiceNow jobs retrieve configuration management database (CMDB) data from ServiceNow through REST API. The Observer loads and updates the resources and their relationships within the topology service.

By default, the observer discovers the following relationship tables:

  • /api/now/table/cmdb_ci_service_discovered (services data)
  • /api/now/table/cmdb_rel_ci (connectivity information for inventory data)
  • /api/now/table/cmdb_ci_service_calculated (calculated service data)
  • /api/now/table/cmdb_ci_query_based_service (query-based service data)

The observer supports all system-created or user-created child tables of cmdb_ci, as well as the following resource:

  • /api/now/table/sys_user (user data)

ServiceNow job: By default, Load jobs are one-off, transient jobs that do a full upload of all requested topology data as soon as they are triggered. You can also run these jobs (again) manually from the Observer UI, or schedule them to run at set times when configuring them. Run this job whenever you want to refresh the ServiceNow topology data.

Mapping of ServiceNow object types to topology entity types

Table. ServiceNow object and entity types
ServiceNow object types Entity types
cmdb_ci, cmdb_ci_service_discovered based on sys_class_name attribute
sys_user person

Tip

Important: Specify cmdb_ci_{name} tables to discover using the ServiceNow tables to be discovered parameter.

Follow these steps to run the ServiceNow glide script that lists availabe cmdb_ci tables.

Note: You must have admin access to run the script.

  1. Login to the ServiceNow instance as the admin user.

  2. Go to System Definition > Scripts - Background.

  3. Paste the following script into the text box:

    var g = new GlideAggregate('cmdb_ci');
g.addAggregate('COUNT', 'sys_class_name')
g.orderByAggregate('COUNT', 'sys_class_name');
g.query();
while (g.next()) {
gs.info(g.sys_class_name + ': ' + g.getAggregate('COUNT', 'sys_class_name'));
}

  4. Run the script.

  5. ServiceNow will list all cmdb_ci tables in the environment. Sample output:

    *** Script: cmdb_ci_spkg: 1767
*** Script: cmdb_ci_computer: 814
*** Script: cmdb_ci_service: 41
*** Script: cmdb_ci_printer: 28
*** Script: cmdb_ci_server: 19
*** Script: cmdb_ci_win_cluster_node: 14
*** Script: cmdb_ci_database: 13
*** Script: cmdb_ci_web_server: 9
*** Script: cmdb_ci_win_server: 8
*** Script: cmdb_ci_unix_server: 7
*** Script: cmdb_ci_ups: 6
*** Script: cmdb_ci_email_server: 5
*** Script: cmdb_ci_netgear: 5
*** Script: cmdb_ci_rack: 5
*** Script: cmdb_ci_zone: 5
*** Script: cmdb_ci_linux_server: 4
*** Script: cmdb_ci_win_cluster: 4
*** Script: cmdb_ci_cluster_node: 3
*** Script: cmdb_ci_ip_router: 3
*** Script: cmdb_ci_msd: 3
*** Script: cmdb_ci_network_adapter: 3
*** Script: cmdb_ci_aix_server: 2
*** Script: cmdb_ci_computer_room: 2
*** Script: cmdb_ci_disk: 2
*** Script: cmdb_ci_peripheral: 2
*** Script: cmdb_ci: 1
*** Script: cmdb_ci_appl: 1
*** Script: cmdb_ci_app_server_java: 1
*** Script: cmdb_ci_cluster: 1
*** Script: cmdb_ci_datacenter: 1
*** Script: cmdb_ci_db_mysql_catalog: 1
*** Script: cmdb_ci_db_ora_catalog: 1
*** Script: cmdb_ci_ip_switch: 1
*** Script: cmdb_ci_service_group: 1
*** Script: cmdb_ci_storage_switch: 1

Procedure

Define or edit the following parameters, then click Run job to save and run the job.

Encryption requirement: See the Configuring observer jobs security topic for more information.

Remember: To improve performance and to focus your topology, do not include all ServiceNow tables. Instead (before running an observer job) identify the ServiceNow tables that are most useful to your requirements, and exclude the ones you do not require. For example, you may want to exclude the vast number of records of SIM cards from being displayed in the topology, and include only servers, services or applications.

Table. Parameter action details
Parameter Action Details
Unique ID Enter a unique name for the job Required
ServiceNow instance Specify the ServiceNow instance Required
ServiceNow username Specify the ServiceNow username Required
ServiceNow password Specify the ServiceNow password Required
ServiceNow tables to be discovered The supported tables are sys_user, and all system-created or user-created child tables of cmdb_ci. Using a comma as delimiter for multiple entries, specify either sys_user or tables that are either system-created or user-created children of the cmdb_ci table, such as cmdb_ci_database (the system table), u_ibm_database (the global scope custom table), or sn_app_ws_u_ibm_database (the application scope custom table). Note that the following relationship tables are added by default: cmdb_rel_ci, cmdb_ci_service_discovered, cmdb_ci_service_calculated, and cmdb_ci_query_based_service. Required
Number of records to fetch per API call from a table Enter the number of records to fetch per API call from a table. The default value is 10000. The value you enter should be in the range of 100 to 10000. Optional
Entity mapping for sysClassNames This parameter will override the default observer mapping for the sys_class_name entity type with a user-defined entity type. Enter the class name and the new entity type name, where the values of the class and the new entity type name are separated by a colon.
Example: cmdb_ci_linux_server:node.		 Optional
Options to exclude entity edges Select an exclude option to exclude resource edges Optional
List of entities to exclude edge modelling Enter the entities to exclude resource edges. The listed entities will be not have any edge connectivity to any entities Optional
Use include or exclude filter Specify the type of filter to use when retrieving resources. The options are include (default), or exclude. Specify whether to include or exclude an API filter in every ServiceNow API call. Optional. If you select include, you specify the filter next.
Filter resources based on JSON attributes Specify a filter using the JSON key:value attribute. The format used is key=value, where value can be more than one:
key=value1,value2,value3
For more than one key, use the vertical bar symbol ( | ) as delimiter:
key=value1|key2=value1,value2,value3		 Optional. Required only if the include option has been set.
Number of connection retry times Set the number of connection retries. Optional. The default is 2.
Delay in (milliseconds) before a connection retry Set the delay in milliseconds before a connection retry. Optional. The default is 5000ms.
Maximum number of tables Enter the number of batch calls into which you want to split each API query. Defining a number greater than one (up to a maximum of 10) can avoid the query from being too long, thereby avoiding query too long ServiceNow API errors. Optional. The default and maximum is 10.
Connection timeout (milliseconds) Set the connection timeout in milliseconds. Optional. The default is 5000ms.
Read timeout (milliseconds) Set the read timeout in milliseconds. Optional. The default is 5000ms.
Proxy Host Specify the proxy host to connect to. Optional
Proxy Port Specify the proxy port; defaults to 8080. Optional
Proxy Username Specify the proxy user name to connect as. Set for basic auth proxy. Optional
Trust all certificates by bypassing certificate verification Set to true to allow connection to target environment without verification. Optional. The default is 'false'.
Proxy Password Specify the password for the proxy user (if Proxy Username has been specified). Optional
Proxy Secure Specify whether to connect to the proxy in secure mode. Set to True for HTTPS proxy. Optional. The default is false.
Access scope Enter text to provide a scope for the resources. Access scope can help map alerts to resources when resources in different scopes share the same parameters, such as matchTokens. Optional. Tip: You can define access scope for locations, project names, namespaces, etc.
Generate debug support file Set this parameter to 'True' in order to capture the output of the next scheduled job run as a file. This file will be stored with an observer's log files and can be used to debug observer issues, for example at the request of your designated support team, or while using a test environment. For one-off jobs (that is, Load jobs), this parameter reverts to 'False' after the next completed run. To examine the output produced, you can load the generated debug file using the File Observer. Optional
Observer job description Enter additional information to describe the job Optional
Job schedule Specify when the job runs Optional. Load jobs only.