ServiceNow JSON Payloads
ServiceNow JSON Payloads (commonly referred to as simply “the payload” in our documentation) - are blocks of JSON containing parameters in place of actual values. The cookdown Discovery engine replaces these parameters with actual values for each object.
This article will explain the components of these payloads. For more information on how these payloads are set up in the product see this page.
Once you understand payloads, check out the Discovery Payload Library for payloads covering some common technologies that we have made for you.
Example Payload for Windows Servers
Payload added to Cookdown Discovery for Windows Server
Payload passed from Cookdown Discover to ServiceNow for a single Windows Server
The Basics: Understanding Payloads
The below payload (again for Windows Server) is an example of the sort of payload you would create for a new discovery, it is highlighted to explain the components that make it up.
"lookup": [ ],
"related": [ ],
"short_description": "SID: Microsoft.Windows.Computer:::ActiveDirectoryObjectSid AD OU:Microsoft.Windows.Computer:::OrganizationalUnit",
"relations": [ ]
Grey = ServiceNow Identification and reconcilliation syntax/format for JSON payloads. Relations, Lookups and Related entries are explained in another article
Orange = the table in your ServiceNow CMDB that you with to push CIs from the selected SCM class into (in this case cmdb_ci_win_server). Note that the Identification and Reconcilliation Engine which will be consuming the payloads expects the table label rather than its name (the name of the cmdb_ci_win_server table is “Windows Server” for example). The list of tables present in your CMDB can be found by opening CI Class Manager in your ServiceNow instance and for a generic list see here.
Purple = attributes of the CI Class into which you plan to push values. Each CI Class will contain a set of attributes that must contain values. These will either be attributes set as mandatory in your CMDB or attributes set in Identification Rules' Identification Entries for each CI Class (used to identify discovered CIs as unique or not based on rules and attribute matching.) If data is not provided for a mandatory attribute, the Identification and Reconciliation engine will reject the incoming CI. Read more on Identification Rules/Entries here.
Green = the values to be pushed into the defined attribute. These are typically Cookdown Discovery keys (explained on the Create Discovery page), strings, integers, and booleans. You can provide multiple keys for a single attribute and mix them in with regular strings (assuming the attribute supports the type of data you plan to push to it). It is worth noting that some attribute has a max character length so be careful to not push more to an attribute than it can hold (or excess characters are stripped from the provided data).
A critical aspect of creating useful payloads is the relationships they contain. At their simplest, Relationships link together CIs and some CI Classes cannot exist without a relationship to something else (EG SQL Databases cannot exist without a relationship to a SQL DB Engine). All CIs have recommended relationship types and possible relationship types. Read more about relationships in ServiceNow. ServiceNow instances ship with these but as they are customizable in each CMDB, the best place to see the suggested/available relationship types is to look in CI Class manager in your ServiceNow instance:
Example Relationships: SQL Database, SQL DB Instance, and Windows Server
The below payload will push SQL Databases, SQL DB Instances, and Windows Servers
Looking at the Relationship portion of this payload, we see the type of relationship defined (EG “Contains::Contained By”) and the parent/child of the relationship with Parent referring to the first half of the relationship type (in this example Contains). The numbers relate to each CIs position in the payload, with the first CI occupying position 0. In the example above, cmdb_ci_db_mssql_database (SQL Database) is in position 0 and cmdb_ci_db_mssql_instance (SQL Instance) is in position 1. The relationship between then is a containment relationship which read in English essentially says the SQL Database is contained by the SQL Instance
Lookups and Related entries
The Lookup and Related sections of the payload allow you to fill in reference attributes with values from other CMDB tables. Creating payloads to fill in these fields is simple in principle but is hard to get right as if you create a lookup for a CI type that already has an identifier entry somewhere else in your CMDB duplicate CIs can be created. The below examples for Windows Servers with Network adapters + Clusters with cluster nodes show you how to construct payloads with lookups and related entries
Lookup Example: Windows Servers with Network Adapters
Related Entry Example: Windows Clusters with Cluster Nodes
You will notice in both of these examples that the CI you want to lookup/relate to is mentioned but the reference field on the main CI class is not. That is because both Lookups and Related Entries depend on Identification and Reconciliation rule changes to work. See the below rules that facilitate this (which can be found in your ServiceNow instance by searching for “CI Identifiers” in the navbar on the left-hand side of the screen):
Identifier Entry for Network Adapter for example Lookup payload
Note that this identifier Entry is shipped by default with ServiceNow. It is used by ServiceNow’s own SCCM Discovery product. Also, note that this Identifier is for cmdb_ci_hardware - the Windows Server CI Class is parented by cmdb_ci_hardware so inherits its Identifier Entries by default
Related Entry for Windows Cluster, for example, Related Entry payload
Note that this related entry is not shipped by default with ServiceNow.
When getting started with creating payloads they can seem daunting, but once you get going you will see they are simple enough.
Your ServiceNow instance contains a useful tool that can help build payloads called Identification Simulator. It is designed to see what the result of pushing payloads into ServiceNow would be on the CIs that already exist in your CMDB.
It creates all the JSON syntax that surrounds the data you select, builds the JSON for relationships between CI types where CI Classes are dependant on each other, it lets you know which attributes can be used for identifying a CI as unique (as defined in your CMDB for each CI class) and warns you if you try and build a payload without an attribute that has been made mandatory for the CI Class in your CMDB.
It is a valuable tool when building Cookdown Discovery payloads!
The ServiceNow documentation on the Identification Simulator is good and will amply explain how the tool works, but as we are using the tool to build payloads containing Cookdown Discovery keys we have created the below as supplemental documentation
Identification and Reconciliation engine limitations
The only limitation with the Identification and Reconciliation engine itself (and so with Cookdown Discovery) is there is no way to search for records from a table outside of the CMDB itself. Some examples:
Company table (core_company)
We seen customers implement two workarounds for this limitation:
Store the sys_id for the entries in the table Identification and Reconciliation cannot search in SCOM as data in extended classes. The sys_id can simply be pushed into a reference attribute that references data from a table outside of the CMDB
Add a custom attribute into ServiceNow, push data from SCOM into the field (like the owner of a SCOM object) and write scripts in ServiceNow to find the attribute’s value in the desired table (eg search for an email address from the custom attribute in the users table and return the sys_id of that user to store in a user reference attribute)