ServiceNow

The ServiceNow integration does three things, and one account can do any combination of them:

• Inventory discovery reads a table in your instance, typically a CMDB table, into Connect's Inventory: one item per record, with the IPs from a field you name.
• Change request export writes each Connect change request that passes a Boundary into a staging table in your instance, one row per rule.
• Decommissioned asset export writes the assets a Decommission action matches into a second staging table, one row per asset.

Connect creates and fills the staging tables. A transform map you create in ServiceNow moves each row into the target table of your choice, so Connect never writes to change_request or cmdb_ci itself.

Before you start

Prerequisite	Why it's needed	Where to check in ServiceNow
Your instance name, the subdomain of your instance URL: acme for https://acme.service-now.com	Every API call goes to it	Your browser's address bar
An OAuth client with the Client Credentials grant, and its Client ID and Client Secret	Connect signs in with them, so no user password leaves your instance	Machine Identity Console on Zurich and later, System OAuth > Application Registry before that
The client's OAuth Application User, with the roles under Create the OAuth client	Every call Connect makes runs as that user	User Administration > Users
For discovery, the table to read and the field that holds its IP addresses, for example cmdb_ci_server and ip_address	Only that table is read, and only that field becomes IPs	System Definition > Tables

Create the OAuth client in ServiceNow

Connect signs in with OAuth 2.0 client credentials, the method ServiceNow recommends for system-to-system integrations. A ServiceNow admin does this once per instance.

1. Allow the grant type. Under System Properties (sys_properties.list), create a Global property named glide.oauth.inbound.client.credential.grant_type.enabled, of type true | false, with value true.

2. Create the user Connect acts as. Under User Administration > Users, create a user with Identity type set to Machine, so it never signs in interactively. On releases before Yokohama Patch 6, check Web service access only instead. Give it these roles:

   Role	Needed for
   snc_platform_rest_api_access	Every account, when the instance enforces the Platform REST API access control
   Read access to the table you import, such as cmdb_read	Discovery
   personalize_dictionary	Export: creating the staging tables and their columns
   import_admin, or import_set_loader plus import_transformer	Export: loading rows through the Import Set API
   A role that reads sys_db_object, such as itil, asset or sn_change_read	Export: finding the staging tables. personalize_dictionary writes that table but does not read it

3. Register the client.

   Zurich and later. Under Machine Identity Console > Inbound integrations, click New integration and choose OAuth - Client credential grant.

   • Set a Name, a Provider name such as FireMon Connect, and the OAuth application user from step 2. Leave the token lifespan at its default.
   • Leave Scopes empty and Allow access only to APIs in selected scope unchecked, and choose Skip for now if asked to assign an auth scope.
   • Leave Enforce token restriction unchecked unless your instance already defines REST API Access Policies for Connect.
   • Save and copy the Client ID and Client Secret. Then open the record under System OAuth > Application Registry and set Scope Restriction to Broadly Scoped: a new client is securely scoped, which refuses the APIs Connect uses.

   Yokohama and earlier. Under System OAuth > Application Registry, click New, then Create an OAuth API endpoint for external clients.

   • Set Default Grant type to Client Credentials and OAuth Application User to the user from step 2. If that field is missing, add it through Configure > Form Layout.
   • Leave Public Client unchecked and Scope Restriction at Broadly Scoped.
   • Save and copy the Client ID and Client Secret.

If your instance uses REST API Access Policies, the policies covering the Table, Import Set and Batch APIs must include an OAuth inbound authentication profile. Without it the token is issued and then rejected, and Test says so.

Set up a ServiceNow account

1. In Connect, go to Integrations and click New Integration Account.
2. Choose ServiceNow as the Provider, give the account a name your team will recognize, and pick a project.
3. Click Continue to Provisioning.
4. Under Configure for, keep Import checked for discovery. Clearing it hides the Import Settings, and no discovery runs. Both exports are available either way.
5. Under Credentials, enter the Instance Name, Client ID and Client Secret. The secret is write-only: it opens blank on later visits, and leaving it blank keeps the saved value.
6. Under Import Settings, enter the Table Name (cmdb_ci_server), the IP Field Name (ip_address) and, optionally, Tag Field Names: a comma-separated list of fields to carry as tags.
7. Click Provision Account, then Test. The test signs in and reads what the account needs: the table and its IP field for discovery, and the table registry for exports. The first discovery starts on its own.

Inventory discovery

Each record becomes one inventory item of type Table Record, sourced from ServiceNow:

Record field	Where it lands
sys_class_name and sys_id	The item's name, as <class>/<sys_id>
The field named in IP Field Name	The item's IP addresses
Each field named in Tag Field Names	A tag, keyed by the field name
last_discovered	The item's last-seen time, which Decommission uses to spot idle assets
mac_address	The item's MAC address

The IP field must be a text field holding an address, a CIDR, a comma-separated list, or a range such as 10.0.0.1-10.0.0.20, which is expanded to the CIDRs that cover it. A reference field gives the item no IPs.

Records are matched between runs by sys_id, and a record dropped from the table is removed on the next run. Rows the application user's access rules hide are simply absent.

Verify it landed

What to check	Where to look
The account is healthy	Integrations: the ServiceNow row's Status stays clear, and its Provision page shows a Provisioned tag
The item count	Integrations: the ServiceNow row's Assets count roughly matches the table's row count
The items themselves	Inventory > Resources, filtered by Vendor > ServiceNow. Open one: its IPs should match the record's IP field

Exports

Saving the Provision page creates two staging tables in your instance, each extending sys_import_set_row, whether or not Export is checked. An existing table is kept: columns it lacks are added and narrow ones are widened. If creation fails, usually because the application user lacks personalize_dictionary, the save still succeeds and the first sign is a missing table. Confirm both exist under System Definition > Tables before building the transform maps, and if one is missing, fix the roles and save the Provision page again.

Export	Staging table	Label in ServiceNow	Typical target table
Change requests	u_connect_change_requests_staging	Connect Change Requests	change_request
Decommissioned assets	u_connect_decommissioned_assets_staging	Connect Decommissioned Assets	cmdb_ci

Rows land in the staging table whether or not a transform map exists. Every evaluation or match exports again, so coalesce in the transform map or the target fills with duplicates. JSON columns hold up to 100,000 characters; a longer list is cut to the entries that fit and ends with an entry such as "+1234 more", so it still parses.

Create the transform maps

Under System Import Sets > Administration > Transform Maps, create one map per export you use. The name is yours. What matters is the Source table, since ServiceNow runs every active map whose source is the staging table. Add Field Maps from the u_ columns to your target's fields, and coalesce on u_id plus u_rule_id for change requests and on u_workflow_id plus u_id for decommissioned assets, so a re-export updates rather than duplicates. ServiceNow's guide: Create a transform map.

Change request export

When a change request is evaluated against a Boundary with a Pass or Review result, Connect exports it to every target on that Boundary. Fail and error results do not export.

1. Open or create the Boundary under Boundaries.
2. Under Target(s), select your ServiceNow account.
3. Save.

Each rule becomes one row. The request's columns repeat on every row and the rule's columns are per row. u_sources and u_destinations hold the resolved addresses of every rule in the request combined, so with several rules a row lists more than its own rule allows. Map a rule's own sources and destinations from u_raw.

Staging columns

Date columns hold UTC in ServiceNow's YYYY-MM-DD HH:MM:SS form. JSON columns hold text that parses as JSON.

Column	Label	Holds
u_id	Connect Change Request ID	The request's ID in Connect
u_name	Change Request Name	The request's name
u_created_at	Created At	When the request was created
u_created_by	Created By	Who created it
u_updated_at	Updated At	When it was last changed
u_updated_by	Updated By	Who last changed it
u_score	Score	The score from the evaluation, when there is one
u_rule_id	Rule ID	The rule's ID
u_action	Action	The rule's action
u_sources	Sources	JSON array of the request's resolved source addresses and CIDRs
u_destinations	Destinations	JSON array of the request's resolved destination addresses and CIDRs
u_services	Services	JSON array of the rule's services as written, one object per service: type, plus portStart and portEnd for TCP and UDP, icmpType and icmpCode for ICMP, or protocol for a custom protocol (see the Schema)
u_justification	Justification	The rule's justification
u_comment	Comment	The rule's comment
u_owner	Owner	The rule's owner
u_expiration	Expiration	When the rule expires, when set
u_raw	Raw	The rule exactly as it was written, as JSON, including its own sources and destinations

To verify, submit a change request that passes the Boundary, then check u_connect_change_requests_staging for the rows and your target table for the transformed records. Connect records the Boundary result on the change request; whether the rows arrived is visible only in ServiceNow.

Decommissioned asset export

1. Under Decommission > Actions, create or edit an action.
2. Under Destination, select your ServiceNow account.
3. Save. Every asset the action matches from then on is exported.

Each matched asset becomes one row: the match context, the export itself, and the asset's own fields.

Staging columns

Date columns hold UTC in ServiceNow's YYYY-MM-DD HH:MM:SS form. JSON columns hold text that parses as JSON.

Column	Label	Holds
u_workflow_id	Workflow ID	The ID of the Decommission action that matched the asset
u_hit_count	Hit Count	The match's hit count, from the integrations that report one
u_hit_count_source	Hit Count Source	Which integration reported it
u_last_hit_at	Last Hit At	When the asset was last hit
u_last_hit_at_source	Last Hit At Source	Which integration reported it
u_last_seen_at	Last Seen At	When the asset was last seen
u_last_seen_at_source	Last Seen At Source	Which integration reported it
u_sent_to_integration	Sent To Integration	The name of the Connect account the row went through
u_sent_to_integration_at	Sent To Integration At	When Connect exported the row
u_other_items	Other Matched Items	JSON array of the other inventory items matched with this one, when there are any. Each carries the same information as the asset columns below under Connect's own field names, such as hostname, ips and cloudAccountId
u_account_id	Account ID	The Connect account the asset was discovered through
u_region	Region	The asset's region
u_type	Type	The asset's type identifier
u_id	ID	The asset's ID in its source system
u_cloud_account_env	Cloud Account Env	The account's Environment label
u_cloud_account_id	Cloud Account ID	The cloud provider's account ID
u_cloud_account_name	Cloud Account Name	The account's name
u_item_hit_count	Item Hit Count	The asset's own hit count
u_hostname	Hostname	The asset's hostname, when known
u_ips	IPs	JSON array of the asset's IP addresses
u_item_last_hit_at	Item Last Hit At	When the asset itself was last hit
u_item_last_seen_at	Item Last Seen At	When the asset itself was last seen
u_mac_address	MAC Address	The asset's MAC address, when known
u_name	Name	The asset's name
u_type_name	Type Name	The asset type's display name
u_updated_at	Updated At	When the inventory record was last updated
u_vendor	Vendor	The integration the asset came from, such as aws or azure

To verify, open Decommission > History. Each export shows Pending, Success or Error; hover an Error tag for the message. Success means the row loaded and every transform map accepted it. A transform map error, such as no map for the staging table, shows as Error with ServiceNow's message, and the row stays in the staging table.

For common issues, see Troubleshooting.

ServiceNow documentation

• Client credentials grant workflow and Create the client credentials system property: the sign-in Connect uses and the property that allows it
• Create a transform map: the one piece of setup done in ServiceNow