Create or edit a CI identification rule

Identification rules are used to uniquely identify CIs in the CMDB, as part of the identification and reconciliation process. Each CMDB class can be associated with a single identification rule.

Before you begin

Role required: itil has read access, itil_admin (on top of itil) has full access.

About this task

In a CI identification rule, specify a CI identifier, and identifier entries and related entries that uniquely identify the CI. You cannot use the CI Class Manager to create related entries for an identification rule, you need to add those directly to the cmdb_identifier table.

Review the following before creating identification rules:

Procedure

  1. Navigate to Configuration > CI Class Manager.
  2. Click Hierarchy to display the CI Classes list. Select the class for which to create an identification rule.
  3. In the class navigation bar, expand Class Info and then click Identification.
  4. Click Edit to edit an existing rule, or click Add in the Identification Rule section to create one. Fill out the form, and then click Save.
    Field Description
    Independent/Dependent Designation of whether the CI identifier can identify the CI independently of other CIs, or not.
    Note: To set the rule as Dependent, you must specify dependent relationship rules for the selected class.
    Name Name of CI identifier.
    Description Description of the CI identifier.
  5. In the Identifier Entries section, edit an existing identifier entry, or click Add to create one.
  6. Fill out the details in the Create Identifier Entry dialog box to specify criteria for matching a CI, and then click Save.
    Field Description
    Search on table
    The lookup table:
    • For a regular identifier entry: Select the same table as the table specified in Applies to on the Identifier form.
    • For a lookup identifier entry: Select a table that is different from the Applies to table specified on the Identifier form. Also, the lookup table must have a reference field to cmdb_ci, otherwise the identifier entry is considered invalid.

      The Rule Info and the Lookup Info tabs appear.

    Priority Priority of the identifier entry. Identifier entries are applied based on priority. Rules with lower priority numbers are given higher priority. Identifier entries of identical priorities are applied randomly.

    It is recommended that you keep gaps between the priority numbers, so you can assign the unused priority numbers to new entries without modifying the existing priority order.

    Criterion attributes Set of attributes that uniquely identify the CI. Attributes can belong to the current class, or to a parent class.

    Use the slushbucket to add or remove attributes from the identification rule.

    It is not possible to add reference fields as a criterion attribute. Reference fields store sys_ids that point to a record in another table, and thus is considered a weak criterion attribute (in terms of uniqueness) for the current table.

    Allow null attribute Check box to allow null values for criterion and unique attributes.
    Active Check box that specifies the identifier entry is active. At least one identifier entry in an identification rule must be active for the rule to apply.
    Allow fallback to parent's rules Designation that the identification rules of the CI's parent are used if a match is not found for this identification rule. Applies only for dependent identification rules.
    Note: If criterion attributes have only two attributes and sys_class_name is one of them (for example [name, sys_class_name], [ip_address, sys_class_name]), then the other attribute cannot be NULL, even if Allow null attribute is enabled. This restriction is due to sys_class_name being considered a special system matching attribute.
  7. If Search on table is set to a table that is different than the table on the Identifier form, then the Rule Info and the Lookup Info advanced tabs appear. Click Lookup Info and enter the information for a lookup identifier.
    Field Description
    Optional condition A filter to narrow the set of records that will be searched for a matching CI. Applies only to lookup based identification.
    Enforce exact count match (Lookup) Indicates that for lookup identification, match only on exact lookup records count match.
  8. (Optional) Add related entries to the cmdb_identifier table.
    1. In the main platform navigation bar, navigate to Configuration > Identification/Reconciliation, and click CI Identifiers.
    2. In the Identifiers view, locate and click the identification rule that you have been editing or creating.
    3. Click the Related Entries tab.
    4. In the Related Entries related list, click New or open an existing entry to specify a related entry for matching the related item. Fill out the form, and then click Submit.
      Table 1. Related Entry form
      Field Description
      Identifier The CI identifier for which this related entry belongs to. By default it is set to the identifier you previously selected.
      Related table A related table that references the CI that is being matched.
      Referenced field A referenced field in Related table that should store the referenced CI. This field always reference the cmdb_ci table, or a descendent of the cmdb_ci table.
      Criterion attributes The set of attributes to uniquely identify the related item. Attributes can belong to the current class, or to a parent class.

      Click the lock icon to view, add, or remove attributes from the identification rule.

      Optional condition Use the Add Filter Condition and the Add "OR" Clause buttons to construct a filter to narrow the set of records that will be searched for a matching related item.
      Active Check box that specifies that the related entry is active.
      Allow null attribute Check box to allow null values for criterion and unique attributes.
      Priority Priority of the related entry for the specified Related table. Rules with lower priority numbers are given higher priority while matching a related item for specific related table. Related entries for the specified related table with identical priorities are applied randomly.

      It is recommended that you keep gaps between the priority numbers, so you can assign the unused priority numbers to new entries without modifying the existing priority order.

      Note: If criterion attributes have only two attributes and sys_class_name is one of them (for example [name, sys_class_name], [ip_address, sys_class_name]), then the other attribute cannot be NULL, even if Allow null attribute is enabled. This restriction is due to sys_class_name being considered a special system matching attribute.

Example

For example, the pre-defined Hardware Rule applies to the Hardware [cmdb_ci_hardware] table. It has an identifier entry with the criterion attribute Serial Number, Serial Number Type and its Search on table field is set to Serial Number.

The following payload snippet adds a CI to the cmdb_ci_linux_server class, that is a child of the Hardware class. It also shows how you can add related items in the payload for which you should create Related Entries on the CI Identifier page for the Hardware [cmdb_ci_hardware] table:

{
    "items": [
        {
            "className": "cmdb_ci_linux_server",
            "lookup": [
                {
                    "className": "cmdb_serial_number",
                    "values": {
                        "serial_number": "VMware-42 21 e3 da 44 14 5a a6-56 48 2b 0a 28 53 42 4c",
                        "serial_number_type": "system",
                        "valid": "true"
                    }
                },
                {
                    "className": "cmdb_serial_number",
                    "values": {
                        "serial_number": "4221E3DA-4414-5AA6-5648-2B0A2853424C",
                        "serial_number_type": "uuid",
                        "valid": "true"
                    }
                },                }
            ],

    “related": [
                {
                    "className": "cmdb_ci_ucs_chassis",
                    "values": {
                        “name": “chassis1",
                        “category": “category1",
                        “short_description": “My Chassis 1"
                    }
                },
                {
                    "className": "cmdb_ci_ucs_chassis",
                    "values": {
                        “name": "chassis2",
                        "category": "category2",
                        "short_description": "My Chassis 2"
                    }
                },    }
     ],

            "values": {
                ......
                "name": "xpolog2.lab3",
                "os_name": "Linux",
                "output": "Linux xpolog2.lab3 2.6.32-431.el6.x86_64 #1 SMP Fri Nov 22 03:15:09 UTC 2013 x86_64 x86_64 x86_64 GNU/Linux",
                "serial_number": "VMware-42 21 e3 da 44 14 5a a6-56 48 2b 0a 28 53 42 4c",
                "sys_class_name": "cmdb_ci_linux_server"
            }
        }
    ]
}
                         

When the Hardware Rule is applied, the Serial Number [cmdb_serial_number] table is searched for a match with the values specified within the lookup key. Unless Enforce exact count match (Lookup) is checked, it is not necessary for every lookup key to return a match, as long as there is at least one match. If all matches reference the same CI, then that CI is considered to be the existing CI record. If no match is found, then the identification search continues to the next rule entry. If after all the rules are exhausted without finding a match, a new CI record is created in the database.

What to do next

You can optionally create an inclusion rule to narrow the scope of CIs that are included in identification.