Defining ServiceNow Observer jobs

The ServiceNow Observer is installed as part of the core installation procedure. Using the ServiceNow Observer, you can retrieve the configuration management database (CMDB) data from ServiceNow via REST API. Currently, the observer only supports load job. The load job queries the configuration items (CI) from CMDB via ServiceNow 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 your user account has the rest_api_explorer and web_service_admin roles. These roles are required to access the resources from ServiceNow. Also, ensure you have the ServiceNow service details to hand, such as username, password, and URL.

Remember: Swagger documentation for the observer is available at the following default location: https://<your host>/1.0/servicenow-observer/swagger

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.

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)

servicenow_observer_common.sh: The configuration file you use to customize ServiceNow Observer settings.; The parameters defined here are then used by the servicenow_observer_load_start.sh script to trigger the ServiceNow Observer jobs.; Tip: Alternatively, you can set the appropriate environment variables. If an environment variable is set, it takes precedence over the configuration file settings.

You define and start the following job. You must edit the parameters in the configuration file before running this job.

Load job: A transient (one-off) job that loads all requested topology data.; This job is started by the servicenow_observer_load_start.sh script.; Run this job whenever you need the ServiceNow topology data refreshed. .

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

To edit the parameters in the configuration file

Open the servicenow_observer_common.sh configuration file and edit the following parameters:

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. Must be encrypted.the custom tables that start with '`u_`', such as `cmdb_ci_database` or `u_cmdb_ci_station`.
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
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.	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
Proxy Password	Specify the password for the proxy user (if `Proxy Username` has been specified).	Optional. Must be encrypted.
Proxy Secure	Specify whether to connect to the proxy in secure mode. Set to True for HTTPS proxy.	Optional. The default is 'false'.

For encryption: Run the encrypt_password.sh script in the ASM_HOME/bin directory:

./bin/encrypt_password.sh

Enter and then confirm the password. The encryption utility returns an encrypted version.

To start the Load job

To start the ServiceNow Observer Load job, use the following command:
```
$ASM_HOME/bin/servicenow_observer_load_start.sh
```
This job loads all requested topology data. Run this job whenever you need the ServiceNow topology data refreshed.

Results

You can now use data retrieved from the ServiceNow configuration management database (CMDB) to create topologies in the Agile Service Manager topology service.

What to do next

You can also use the following scripts:

servicenow_observer_load_stop.sh: Stops the Load job
servicenow_observer_job_list.sh: Lists the status of current jobs
servicenow_observer_log_level.sh: Sets the log level

Remember: As an alternative to being configured using the Observer Configuration UI, observer jobs have scripts to start and stop all available jobs, to list the status of a current job, and to set its logging levels. These scripts can be run with -h or --help to display help information, and with -v or --verbose to print out the details of the actions performed by the script, including the full cURL command. For the on-prem version of Agile Service Manager, observer scripts are configured for specific jobs by editing the script configuration files.