ServiceNow Object Payloads
This article assumes that you are already familiar with the basics of object payloads and creating ServiceNow object connections. If you have not looked at these articles we strongly recommend that you read these first.
A Basic Payload
The payload below (for Windows Servers) 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.
{
"items": [
{
"className": "cmdb_ci_win_server",
"lookup": [ ],
"related": [ ],
"values": {
"ip_address": "Microsoft.Windows.Computer:::IPAddress",
"dns_domain": "Microsoft.Windows.Computer:::DomainDnsName",
"os_domain": "Microsoft.Windows.Computer:::DomainDnsName",
"os_version": "Microsoft.Windows.OperatingSystem:::OSVersion",
"cpu_core_count": "Microsoft.Windows.OperatingSystem:::LogicalProcessors",
"ram": "Microsoft.Windows.OperatingSystem:::PhysicalMemory",
"os": "Microsoft.Windows.OperatingSystem:::OSVersionDisplayName",
"virtual": "Microsoft.Windows.Computer:::IsVirtualMachine",
"short_description": "SID: Microsoft.Windows.Computer:::ActiveDirectoryObjectSid AD OU:Microsoft.Windows.Computer:::OrganizationalUnit",
"host_name": "Microsoft.Windows.Computer:::HostServerName",
"name": "Microsoft.Windows.Computer:::NetbiosComputerName"
}
}
],
"relations": [ ]
}
Grey = ServiceNow Identification and reconciliation syntax/format for JSON payloads. Relations, Lookups, and Related entries are explained later in the article.
Orange = The table in your ServiceNow CMDB that you wish to push CIs from the selected SCOM class into (in this case cmdb_ci_win_server). Note that the Identification and Reconciliation 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 object keys from the Sample Object 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 attributes have a max character length so be careful to not push more to an attribute than it can hold (or excess characters will be stripped from the sent data).
Example Payload for Windows Servers
Payload added to Cookdown Discovery for Windows Server
{
"items": [
{
"className": "cmdb_ci_win_server",
"lookup": [],
"related": [],
"values": {
"ip_address": "Microsoft.Windows.Computer:::IPAddress",
"dns_domain": "Microsoft.Windows.Computer:::DomainDnsName",
"os_domain": "Microsoft.Windows.Computer:::DomainDnsName",
"os_version": "Microsoft.Windows.OperatingSystem:::OSVersion",
"cpu_core_count": "Microsoft.Windows.OperatingSystem:::LogicalProcessors",
"ram": "Microsoft.Windows.OperatingSystem:::PhysicalMemory",
"os": "Microsoft.Windows.OperatingSystem:::OSVersionDisplayName",
"virtual": "Microsoft.Windows.Computer:::IsVirtualMachine",
"short_description": "SID: Microsoft.Windows.Computer:::ActiveDirectoryObjectSid AD OU:Microsoft.Windows.Computer:::OrganizationalUnit",
"host_name": "Microsoft.Windows.Computer:::HostServerName",
"name": "Microsoft.Windows.Computer:::NetbiosComputerName"
}
}
],
"relations": [ ]
}
Payload passed from Cookdown Discover to ServiceNow for a single Windows Server
{
"items": [
{
"className": "cmdb_ci_win_server",
"lookup": [],
"related": [],
"values": {
"ip_address": "192.168.1.201, fa80::b900:ef93:d1bc:53fc",
"dns_domain": "cookdown.com",
"os_domain": "cookdown.com",
"os_version": "10.0.14393",
"cpu_core_count": "2",
"ram": "4193844",
"os": "Microsoft Windows Server 2016 Datacenter",
"virtual": "True",
"short_description": "SID: S-1-5-21-1291999999-842597620-722999999-8601 AD OU:CN=Computers,DC=cookdown,DC=com",
"host_name": "AzureHost1",
"name": "Admin02"
}
}
],
"relations": []
}
Relationships
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 the CI Class manager of 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:
{
"items": [
{
"className": "cmdb_ci_db_mssql_database",
"lookup": [],
"values": {
"short_description": "Collation: Microsoft.SQLServer.Windows.Database::Microsoft.SQLServer.Core.Database::Collation Recovery Model: Microsoft.SQLServer.Windows.Database::Microsoft.SQLServer.Core.Database::RecoveryModel Udatability: Microsoft.SQLServer.Windows.Database::Microsoft.SQLServer.Core.Database::Updateability",
"name": "Microsoft.SQLServer.Windows.Database::Microsoft.SQLServer.Core.Database::DatabaseName",
"database": "Microsoft.SQLServer.Windows.Database::Microsoft.SQLServer.Core.Database::DatabaseName",
"sys_class_name": "cmdb_ci_db_mssql_database"
}
},
{
"className": "cmdb_ci_db_mssql_instance",
"lookup": [],
"values": {
"instance_name": "Microsoft.SQLServer.Windows.Database::Microsoft.SQLServer.Core.DBEngine::InstanceName@Microsoft.Windows.Computer:::NetbiosComputerName",
"sys_class_name": "cmdb_ci_db_mssql_instance"
}
},
{
"className": "cmdb_ci_win_server",
"lookup": [],
"values": {
"name": "Microsoft.Windows.Computer:::NetbiosComputerName"
}
}
],
"relations": [
{
"type": "Contains::Contained by",
"parent": 1,
"child": 0
},
{
"type": "Runs on::Runs",
"parent": 1,
"child": 2
}
]
}
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 the 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 them is a containment relationship which read in English essentially says the SQL Database is contained by the SQL Instance
{
"type": "Contains::Contained by",
"parent": 1,
"child": 0
}
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 it is hard to get right. If, for example, 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 following 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
{
"items": [
{
"className": "cmdb_ci_win_server",
"lookup": [
{
"className": "cmdb_ci_network_adapter",
"values": {
"ip_address": "Microsoft.Windows.Computer:::IPAddress",
"mac_address": "Microsoft.Windows.Server.10.0.NetworkAdapter::Microsoft.Windows.Server.NetworkAdapter::MACAddress"
}
}
],
"values": {
"name": "Microsoft.Windows.Computer:::NetbiosComputerName"
}
}
],
"relations": [
]
}
Related Entry Example: Windows Clusters with Cluster Nodes
{
"items": [
{
"className": "cmdb_ci_win_cluster",
"lookup": [],
"related": [
{
"className": "cmdb_ci_win_cluster_node",
"values": {
"name": "Microsoft.Windows.Computer::Microsoft.Windows.Cluster.Node::ClusterName",
"cluster": "Microsoft.Windows.Computer::Microsoft.Windows.Cluster.Node::ClusterName"
}
}
],
"values": {
"fqdn": "Microsoft.Windows.Cluster.NodeRole::Microsoft.Windows.Computer::PrincipalName",
"cluster_type": "Microsoft.Windows.Cluster:::VendorId",
"cluster_version": "Microsoft.Windows.Cluster:::HighestVersion",
"cluster_status": "Microsoft.Windows.Cluster::System.ConfigItem::ObjectStatus",
"cluster_id": "Microsoft.Windows.Cluster.NodeRole::System.Entity::DisplayName",
"name": "Microsoft.Windows.Cluster.NodeRole::System.Entity::DisplayName"
}
}
],
"relations": [
]
}
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.
Read more about lookup and related entries.
Reference Fields
<TODO>
But loosely:
Give each item an internal_id field of a unique string
Use a referenceItems array
referenced: internal_id
referencedBy: internal_id
referenceField: name of field to put the reference in
Creating payloads
Getting started with payload development can seem daunting. However, once you get going you will see that they are simple enough.
Your ServiceNow instance contains a useful tool that can help build payloads called Identification Simulation. 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 dependent 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 object payloads!
The ServiceNow documentation on Identification Simulation is good and will amply explain how the tool works, but as we are using the tool to build payloads containing Cookdown object keys we have created the following article as supplemental documentation.
Identification and Reconciliation engine limitations
The only limitation with the Identification and Reconciliation engine itself (and so with Cookdown Objects) is that there is no way to search for records from a table outside of the CMDB itself. Some examples:
Company table (core_company)
Users table
We have 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 user table and return the sys_id of that user to store in a user reference attribute).
Further Reading
There is a lot of extra reading in this article already. In summary, we think you should take a look at:
CI relationships in ServiceNow
Using Identification Simulation for building Object payloads
If you have Distributed or Enterprise Applications in SCOM you may also want to take a look at Creating Application Payloads.