Configuring ServiceNow Observer jobs

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

Before you begin

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

Ensure you have the ServiceNow service details to hand, such as username, password, and URL

Ensure your user account has the rest_api_explorer and web_service_admin roles. These roles are required to access the resources from ServiceNow.

To run a load job using a non-admin account, you need the following roles in ServiceNow to provide read privileges for the list of API paths:

cmdb_read
service_viewer

The ServiceNow Observer is installed as part of the core installation procedure.

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

Log into the ServiceNow instance using an admin account.
Navigate to User Adminstration and select Users from the menu.
- To create a new user, click New.
- To edit an existing user, search for and then select the user.
From the user's information tab, select the Roles tab, then click Edit.
Assign the required roles to the user.
Click Save, then Update.

For more detailed descriptions of available roles, navigate to User Adminstration 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).

Tip:

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

Follow these steps to run ServiceNow glide script that lists availabe cmdb_ci tables. Admin access is required to run the script.

Login to the Servicenow instance as the admin user.
Go to System Definition > Scripts - Background

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'));
}

Run the script.

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

About this task

ServiceNow jobs retrieve the configuration management database (CMDB) data from ServiceNow via REST API. The Observer loads and updates the resources and their relationships within the Netcool Agile Service Manager core 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)

You define and start the following job.

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

Table 1. Default mapping of ServiceNow object types to Agile Service Manager entity types
ServiceNow object types	Entity types
cmdb_ci, cmdb_ci_service_discovered	based on sys_class_name attribute
sys_user	person

Procedure

On the Observer jobs page, perform one of the following actions:

To edit an existing job

Open the List of options overflow menu next to the job and click View & edit.

To create a new job

Click Add a new job + and select the ServiceNow Observer tile.

Configure the following parameters for the ServiceNow job, then click Save to save and run the job.

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 2. ServiceNow Observer job parameters
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. Use plain text.
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) `sn_app_ws_u_ibm_database` (the application scope custom table) Note: The following relationship tables are added by default: cmdb_rel_ci cmdb_ci_service_discovered cmdb_ci_service_calculated 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	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 '\|' as delimiter: `key=value1\|key2=value1,value2,value3`	Optional. Required only if the include/exclude 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. Set for basic auth proxy.	Optional
Trust all certificates by bypassing certificate verification	Set to true to allow connection to target environment without verification.	Required. The default is 'true'.
Proxy Password	Specify the password for the proxy user (if `Proxy Username` has been specified).	Optional. Use plain text.
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 parameters, such as matchTokens.	Optional. Tip: You can define access scope for locations, project names, namespaces, and so on.
Generate debug support file	Set the optional Generate debug support file parameter to `True` to capture the output of the next scheduled job run as a file. This file is 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. The file is saved to the following locations: On-premises $ASM_HOME/logs/<obs>-observer/ On OpenShift Container Platform /var/log/itsm/<obs>-observer	Optional
Observer job description	Enter additional information to describe the job.	Optional
Job schedule	Specify when the job should run, and whether it should run at regular intervals. By default the job runs immediately, and only once. Optionally you can specify a future date and time for the job to run, and then set it to run at regular intervals after that.	Optional. Transient (one-off) jobs only. If you set a job schedule, the run intervals must be at least 90 seconds apart. If you set them at less than 15 minutes, a warning is displayed, as the frequency can impact system performance.

What to do next

Run this job whenever you want to refresh the ServiceNow topology data.