Using the Identification Simulator

Identification Simulation can be found by searching for it in the Navbar in your ServiceNow instance. Once you have found it click the Start button under “Start with CI Class” to get going:

To explain how to use the Identification Simulator to build Cookdown Discovery payloads, we will use a worked example - SQL databases.

SQL Databases CI class (cmdb_ci_mssql_database) is by default a dependant CI (meaning its Identification rules are configured such that a Database cannot exist in isolation in your CMDB). It is dependant on a SQL instance and SQL instances are dependant on a computer (typically a Windows server).

In the Identification Simulator this information is clearly shown to you through the “Container level x” items:

Criterion Attributes

For each class you are asked to “Select an Identifier” under heading “Criterion Attributes” - Identifiers are rules in ServiceNow which exist for each CI Class. They contain Identification Entries which hold Criterion Attributes - the criterion attributes are the CI Class properties that should be used for matching incoming CIs of the given class as unique (or not). an Identifier can have multiple Identification Entries. Read more on Identifiers.

For SQL Database in our example here is the list of Criterion Attributes we can use to identify the CI as unique when pushed to ServiceNow:

Values pushed to Criterion Attributes are used for identification but are also stored as attributes on any CI that is to be created/updated.

Additional Attributes

In addition to Criterion Attributes for each CI Class, there will be many other attributes that can contain values into which we can push data using Cookdown Discovery. To see the list of attributes available, click the Select attributes dropdown for each CI Class:

Mandatory attributes

Some attributes may have been made mandatory by your CMDB expert but aren't required for identification. If you attempt to build a payload which is missing one of these mandatory attributes Identification Simulator will error when you hit the Generate button and tell you which attribute is mandatory. You will need to add the missing attribute following the steps to add additional attributes above.

Generating Payloads

Once you have filled in values for all Criterion Attributes + mandatory attributes, hit Generate and Identification Simulator will create a JSON payload from the values you entered. In the below example you can see in the blue highlighted sections what happens with database values and in the yellow highlighted section you can see the simulator automatically builds the relationships between the CIs for you based on ServiceNow’s best practice (or whatever you have configured in your CMDB). You can see below how this tool was intended to be used, input actual values for a CI or set of CIs to insert, get a JSON payload you can push to the Identification and Reconciliation API to push the CIs up.

When used with Cookdown Discovery, instead of entering specific machine values we use the Keys copied from the Create Discovery UI in SCOM (added with our management pack) which will be parsed by the Cookdown Discovery engine and replaced with the specific values for actual SCOM Objects - see the below examples

Keys for a SQL Database (and objects in its hierarchy)

The resultant payload using keys

Copying the generated payload from the Identification Simulator

When you have hit Generate and created your payload, the view will not let you copy and paste the generated JSON. To get the payload hit execute (which is intended to show you what would happen if you were to push the created payload to the Identification Engine’s APIs - are new CIs created or updated, etc.), expand the run, and select input. From this screen, the payload can be copied out:

Identification Simulator limitations

The Identification Simulator is a great tool for getting started but has some limitations when used for Cookdown Discovery payload creation:

  • It only builds relationships between CI classes that are dependant on each other (as defined in each CIs Identification Rule). Read more on dependant vs independent identification rules. To build relationships between independent CI classes, you will need to build payloads in Identification Simulator for each independent CI Class, combine them manually, and manually build the JSON for their relationship using the suggested relationship/all relationship data exposed in CI Class Manager.

  • It cannot build the JSON for reference attributes that require the sys_id of the CI to be referenced or a search on the correct CMDB table to return the sys_id (done by use of related or lookup parameters). We have explained how to construct the JSON for these parameters of the payload on another page