Introduction
Often your third-party API provides data that is not supported in the existing CMDB data model. When this occurs, there are several options:
- Normalize the data and use an existing field
- Create a custom extended class
- Create a custom field on an existing class
- Map the data to a new related table
Normalizing the data to the existing data format and using an existing field enables the most functionality. Any ServiceNow applications that use the existing fields do not require modification to use your data.
Creating an extended class can adversely affect Discovery and data from other sources. If your class is reclassified, your custom fields are lost. For example, if you have a machine in My Custom Computer Class and Discovery reclassifies it to Linux Server it gains the fields of the Linux Server class but loses your custom fields. If you choose to create a custom extended class, your app requires additional approval from the ServiceNow Model Council.
Creating custom fields on a parent class increases installation time because the fields are added to existing tables. It can also pollute the CI model and trigger unnecessary changes to the core CI. If you choose this option your app needs additional approval from the ServiceNow Model Council.
The final option is to create a custom table with whatever fields best model the source data. This does not impact existing CIs, does not require custom columns on source data, and generally provides the cleanest model. This guide outlines that approach.
Example Use Case
In this example, the computer data from the API source includes the following fields:
"last_boot": "2020-02-20 13:22:23",
"last_login_datetime": "2020-02-19 01:56:05",
"last_login_user": "john.adams",
"agent_version": "1.10",
"vpn_enabled": true,
"last_scan_for_threats": "2020-02-24 03:13:29"
There are no existing fields for this data. In this example, this data is monitored by an agent named Tutorial Agent. To store the new fields in the CMDB, store them in a new table and relate that table to the CI.
This example uses the following schema to persist the data:
Create a Custom Table
The first step is to create a custom table.
Note: This table should not extend the CMDB_CI table because it is not a Configuration Item. It is only related to a configuration item.
- Navigate to System Definition -> Tables and click New.
- Name your table appropriately.
The name should include your company or application name so that it is easily identifiable.
- Add the columns you need.
The first column needs to be a reference to the CI you want to use. This should reference the Configuration Item [cmdb_ci] class. You might choose a more specific CI class based on the hierarchy you are targeting. However, if you select something too specific, your data might be lost if the item is reclassified. For example, if you are targeting Linux Server but the machine might be reclassified as a personal computer, you need to select a common parent such as Computer or Hardware. There is generally no drawback to selecting the cmdb_ci class.
- Under the column list, click New to create a new column.
- Set the type to Reference.
- Enter the name and label.
- Set the reference field appropriately.
- Save this column and then add columns for each of your other fields.
- Create a field for the id because each machine needs a unique identifier.
Create a Related Entity Record
This data is being consumed by the Robust Transform Engine (RTE) and populated using the Identification and Reconciliation Engine (IRE). To use the IRE to create your record when importing CMDB data, you need to create a new entry in the Related Entry table.
- Navigate to the table by entering cmdb_related_entry.list in the filter navigator and clicking New.
- Enter your Identifier table.
This is the table you used to create your reference column when creating your new table. This example uses the cmdb_ci_hardware table. This table should match the CI’s Identification Rules. For example, if you are targeting computer, which inherits its rules from Hardware, select Hardware as your identifier.
- Find your new table under the Related Table list and add your id field to the Criterion attributes.
A criterion attribute is required even if you are using a one-to-one relationship.
The Related Entry form has an Application field that shows the current application. In this example it is Tutorial2.
- Click Submit to continue.
This adds your related entry record to your application by default. The example related entry record shows the application as Tutorial 2.
Verify the Related Entry record is part of your app.
- Navigate to My Company Applications.
- Click the name of your current app.
- Review the Application Files related list for the Related Entry class.
This shows the newly created Related Entry record.
