How to Verify Identification Rules for Service Graph Connectors
Introduction
When working with Service Graph Connectors, a common question arises: "Can you confirm which attributes will be used for matching during the load?"
This question reveals a fundamental difference in how Service Graph Connectors work: Service Graph Connectors don't use traditional coalesce fields. Instead, they rely on the Identification and Reconciliation Engine (IRE) with priority-based identifier entries.
Background: The Challenge
While implementing a Service Graph Connector for medical device management (Asimily), our team needed to verify which attributes would be used for device identification. The question came from a project stakeholder:
Question: "Can you confirm you will be matching on MAC address during the load?"
Context: Medical devices needed to integrate with ServiceNow CMDB without creating duplicate CIs.
Challenge: Service Graph Connectors don't show a simple "coalesce field" in their configuration.
This article documents the investigation process and provides a reusable methodology for verifying identification rules for any Service Graph Connector.
Service Graph Connectors vs Traditional Integrations
| Aspect | Traditional Integrations (Import Sets) |
Service Graph Connectors (IRE-based) |
|---|---|---|
| Matching Method | Coalesce field(s) in transform map | IRE with priority-based identifier entries |
| Configuration Location | Transform Map → Coalesce section | CI Class Manager → Identification Rule |
| Matching Logic | Single attribute or AND logic | Multiple attributes with priority order and fallbacks |
| Transform Engine | Standard transform scripts | Robust Transform Engine (RTE) |
| Duplicate Detection | Based on coalesce field match | IRE deduplication with partial/incomplete payload handling |
| Examples | CSV imports, custom integrations | SCCM, Intune, Tenable, Asimily, Azure |
How IRE Matching Works
The IRE Process Flow
- Payload Generation: Service Graph Connector generates a payload via the Robust Transform Engine (RTE)
- IRE Reception: IRE receives the payload with target CI class information
- Rule Lookup: IRE retrieves identifier entries for the target CI class
- Priority-Based Matching: IRE tries each identifier entry in priority order (lowest number first)
- First Match Wins:
- If match found → Update existing CI
- If no match → Create new CI
- Source Tracking: sys_object_source record created with source native key and target sys_id
- Subsequent Updates: If source native key exists in sys_object_source, IRE bypasses identification and updates directly
Priority Order Example
Here's how priority order works for cmdb_ci_hardware (default configuration):
Priority 1: name Priority 50: mac_address Priority 90: product_instance_id Priority 100: serial_number,serial_number_type (lookup) Priority 200: serial_number Priority 300: name Priority 400: mac_address,name (lookup)
IRE Evaluation: The IRE tries Priority 1 first, then 50, then 90, and so on. The first successful match is used.
Step-by-Step: How to Verify Identification Rules
Method 1: Via UI (Recommended for Quick Checks)
1 Navigate to CI Class Manager
- Application Navigator →
Configuration > CI Class Manager
2 Find Your Target CI Class
- Use the hierarchy tree on the left side
- Example: Hardware → Computer
- Tip: Check your Service Graph Connector's mapping properties to identify target CI classes
3 Click "Identification Rule" Tab
- This shows all identifier entries for the selected class
- Active entries are used for matching
- Inactive entries are ignored
4 Review Identifier Entries
For each entry, note:
| Field | Description | Example |
|---|---|---|
| Priority (Order) | Lower numbers are tried first | 50, 100, 200 |
| Attributes | Fields used for matching | mac_address, serial_number |
| Type | Standard (direct) or Lookup (related table) | Standard, Lookup |
| Search Table | Which table to search for matches | Hardware, Computer |
| Lookup Table | Related table for Lookup type entries | Serial Number, Network Adapter |
5 Check for Inheritance
"Identifier Rule for this class is inactive hence derived identifier rule will apply."
If present: The class inherits identification rules from its parent class.
If absent: The class uses only its own identification rules.
Method 2: Via Background Script (Recommended for Documentation)
Use this script to programmatically check identification rules and generate documentation:
/**
* Check identification rules for a specific CI class
* Usage: Change ciClassName variable to your target class
* Location: System Definition > Scripts - Background
*/
var ciClassName = 'cmdb_ci_computer'; // Change to your target class
gs.info('════════════════════════════════════════════════════════');
gs.info('IDENTIFICATION RULES FOR: ' + ciClassName);
gs.info('════════════════════════════════════════════════════════');
// Check if class has its own identifier rule
var idRule = new GlideRecord('cmdb_identifier');
idRule.addQuery('applies_to', ciClassName);
idRule.query();
if (idRule.next()) {
var ruleActive = idRule.getValue('active') == 'true';
gs.info('Identifier Rule: ' + (idRule.getValue('n') || 'Unnamed'));
gs.info('Active: ' + (ruleActive ? 'YES' : 'NO (inherits from parent)'));
gs.info('Independent: ' + idRule.getValue('independent'));
gs.info('Sys ID: ' + idRule.getUniqueValue());
} else {
gs.info('No identifier rule found - inherits from parent class');
}
gs.info('');
gs.info('ACTIVE IDENTIFIER ENTRIES:');
gs.info('────────────────────────────────────────────────────────');
// Get identifier entries
var identEntry = new GlideRecord('cmdb_identifier_entry');
identEntry.addQuery('cmdb_ci_class', ciClassName);
identEntry.addQuery('active', 'true');
identEntry.orderBy('order');
identEntry.query();
var entryCount = 0;
var macRules = [];
var serialRules = [];
while (identEntry.next()) {
entryCount++;
var attrs = identEntry.getValue('attributes') || '';
var priority = identEntry.getValue('order');
var entryType = identEntry.getValue('entry_type') || 'Standard';
var searchTable = identEntry.search_table.getDisplayValue() || 'N/A';
// Track MAC and Serial rules
if (attrs.toLowerCase().indexOf('mac') >= 0) {
macRules.push({priority: priority, attributes: attrs});
}
if (attrs.toLowerCase().indexOf('serial') >= 0) {
serialRules.push({priority: priority, attributes: attrs});
}
gs.info('');
gs.info('Rule #' + entryCount + ':');
gs.info(' Priority: ' + priority);
gs.info(' Type: ' + entryType);
gs.info(' Search Table: ' + searchTable);
gs.info(' Attributes: ' + attrs);
if (entryType.toLowerCase() === 'lookup') {
var lookupTable = identEntry.lookup_table.getDisplayValue() || 'N/A';
gs.info(' Lookup Table: ' + lookupTable);
}
}
gs.info('');
gs.info('════════════════════════════════════════════════════════');
gs.info('SUMMARY');
gs.info('════════════════════════════════════════════════════════');
gs.info('Total Active Rules: ' + entryCount);
gs.info('MAC Address Rules: ' + macRules.length);
gs.info('Serial Number Rules: ' + serialRules.length);
if (macRules.length > 0) {
gs.info('');
gs.info('✓ MAC ADDRESS MATCHING:');
for (var m = 0; m < macRules.length; m++) {
gs.info(' Priority ' + macRules[m].priority + ': ' +
macRules[m].attributes);
}
}
if (serialRules.length > 0) {
gs.info('');
gs.info('✓ SERIAL NUMBER MATCHING:');
for (var s = 0; s < serialRules.length; s++) {
gs.info(' Priority ' + serialRules[s].priority + ': ' +
serialRules[s].attributes);
}
}
Understanding CI Class Inheritance
What is Inheritance in IRE?
When a CI class has an INACTIVE identifier rule, it inherits identification rules from its parent class. This is a powerful feature but can cause confusion if not understood.
Example: cmdb_ci_computer Inheritance
Class Hierarchy: cmdb_ci → cmdb_ci_hardware → cmdb_ci_computer
Computer's Identifier Rule: EXISTS but is INACTIVE
Result: Computer inherits Hardware's identification rules
Plus: Any active Computer-specific rules (like Object ID) are added
How to Detect Inheritance
UI Method:
- Look for yellow banner in CI Class Manager
- Text: "Identifier Rule for this class is inactive hence derived identifier rule will apply"
- Rules shown may come from parent class
Script Method:
var idRule = new GlideRecord('cmdb_identifier');
idRule.addQuery('applies_to', 'cmdb_ci_computer');
idRule.query();
if (idRule.next()) {
var isActive = idRule.getValue('active') == 'true';
gs.info('Rule Active: ' + isActive);
// If false, inheritance occurs
}
Why Inheritance Matters
- Child class may have MORE identifier entries than expected
- Rules shown in UI may come from parent (not configured in child)
- Prevents confusion when troubleshooting matching behavior
- Helps explain why changes to parent class affect child classes
Real-World Example: Medical Device Integration
Business Scenario
During implementation of a medical device integration using the Asimily Service Graph Connector, the question arose:
Why This Matters: Medical devices needed accurate identification to prevent duplicate CIs and ensure proper asset tracking for compliance and security.
Investigation Process
1 Check Connector Mapping Properties
First, review the connector's mapping properties to understand which CI classes would be targeted:
| Device Category | Target CI Class |
|---|---|
| Default (uncategorized) | cmdb_ci_hardware |
| Non-Medical Devices | cmdb_ci_hardware |
| Medical Devices | cmdb_ci_computer |
| Imaging, Lab, IT, IoT, OT, Mobile | cmdb_ci_computer |
cmdb_ci_computer, not cmdb_ci_hardware. This meant focusing on Computer class identification rules.2 Check Hardware Class Identification Rules
Using CI Class Manager:
cmdb_ci_hardware - ACTIVE RULES:
Priority 1: name
Priority 50: mac_address ⭐
Priority 90: product_instance_id
Priority 100: serial_number,serial_number_type (lookup)
Priority 200: serial_number
Priority 300: name
3 Check Computer Class Identification Rules
When navigating to Computer class, a yellow banner appeared:
This confirmed that Computer class inherits from Hardware.
4 Verify Inherited Rules
cmdb_ci_computer - ACTIVE RULES (INHERITED + OWN): Priority 90: product_instance_id (from Hardware) Priority 100: serial_number,serial_number_type (from Hardware) ⭐ Priority 200: serial_number (from Hardware) Priority 300: name (from Hardware) Priority 400: mac_address,name (from Hardware) ⭐ Priority 900: object_id (Computer's own)
Conclusion
Answer:
YES - MAC address matching IS configured for the load.
Since the connector uses the IRE rather than coalesce fields, matching occurs in priority order:
- Serial Number is checked first (Priority 100-200)
- MAC Address + Name is checked as a fallback (Priority 400)
This provides robust device identification with multiple matching options to prevent duplicate CIs.
Common Questions & Answers
Q1: How do I know if my Service Graph Connector will match on MAC address?
A: Follow these steps:
- Identify your target CI class from the connector's mapping properties
- Navigate to CI Class Manager > [Your Class] > Identification Rule
- Look for entries with "mac_address" in the Attributes field
- Check the Priority to see when MAC is tried (lower = earlier)
- Verify the entry is Active (not inactive)
Q2: What is the "coalesce field" for Service Graph Connectors?
A: Service Graph Connectors don't use coalesce fields. They use the IRE with priority-based identifier entries. There is no single "primary key" - instead, multiple attributes are tried in priority order until a match is found or a new CI is created.
Q3: Why does my Computer class show MAC address rules if I didn't configure them?
A: Computer class inherits from Hardware parent class. If Computer's identifier rule is inactive, it automatically gets Hardware's rules (including MAC address matching). Look for the yellow inheritance banner in CI Class Manager to confirm.
Q4: How do I know which attribute will be tried first?
A: Check the Priority (Order) field in the identifier entries. Lower numbers are tried first.
Example:
- Priority 50 (MAC address) is tried BEFORE Priority 100 (Serial number)
- Priority 100 is tried BEFORE Priority 200
Q5: What's the difference between Standard and Lookup identifier entries?
| Type | How It Works | Example |
|---|---|---|
| Standard | Direct match on the target CI table | Serial Number field on cmdb_ci_computer |
| Lookup | Match via related table | MAC Address + Name via Network Adapter lookup table |
Q6: Can I add MAC address matching to my Computer class?
A: Yes, you have two options:
Option 1 - Use Inheritance (Recommended):
- Leave Computer identifier rule inactive
- Computer will inherit Hardware's MAC address rules
- No configuration needed
Option 2 - Add Custom Rule:
- Navigate to CI Class Manager > Computer > Identification Rule
- Click "Add" under Identifier Entries
- Set Priority: 50 (or your preferred priority)
- Set Attributes: mac_address
- Set Type: Standard
- Set Active: true
- Save
Troubleshooting Tips
Issue: Devices Creating Duplicates
// Check sys_object_source for existing mappings
var sourceCheck = new GlideRecord('sys_object_source');
sourceCheck.addQuery('name', 'SG-YourConnector'); // Your connector name
sourceCheck.addQuery('id', 'DEVICE_123'); // Source native key
sourceCheck.query();
if (sourceCheck.next()) {
gs.info('Existing mapping found:');
gs.info(' Target CI: ' + sourceCheck.target.getDisplayValue());
gs.info(' Target Sys ID: ' + sourceCheck.getValue('target'));
} else {
gs.info('No existing mapping - will go through IRE');
}
Issue: Can't Find Expected Identifier Rule
- Is the identifier rule ACTIVE? Check cmdb_identifier table
- Is the CI class correct? Verify target class from connector mapping
- Check if parent class has an active rule (may block inheritance)
- Verify identifier entry is associated with correct identifier rule
Issue: Devices Matching on Wrong Attribute
- Check Priority Order: Lower priority runs first
- Check Data Quality: Earlier priority may have matching data
- Check sys_object_source: May bypass IRE on subsequent updates
- Enable IRE Logging: See which rule matched
Enable IRE Logging
1. Navigate to: System Diagnostics > Debug Log Levels 2. Add New: Source: identification_engine Level: Debug 3. Run your Service Graph Connector 4. View logs: System Logs > System Log > All
🎯 Key Takeaways
- Service Graph Connectors use IRE, not coalesce fields
- IRE uses priority-based identifier entries (lowest number first)
- Check CI Class Manager > Identification Rule tab to see rules
- CI classes can inherit rules from parent classes when inactive
- Multiple attributes provide robust matching with fallbacks
- sys_object_source stores source native key after first match
- Understanding identification rules prevents duplicate CIs
- Always verify target CI class from connector mapping properties
Additional Resources
ServiceNow Documentation
- Identification and Reconciliation Fundamentals
- How the CMDB IRE Works
- CI Class Manager Documentation
- How to Build an IRE Payload
Related Community Articles
- ServiceGraph Connectors - IRE Processing Errors
- ServiceNow CMDB Identification and Reconciliation Engine (IRE)
Conclusion
Understanding how Service Graph Connectors use identification rules is critical for successful CMDB integration. Unlike traditional integrations with coalesce fields, Service Graph Connectors rely on the IRE's priority-based matching system.
By following the methods outlined in this article, you can:
- Verify which attributes your connector uses for matching
- Understand priority-based matching behavior
- Identify and leverage CI class inheritance
- Prevent duplicate CIs in your CMDB
- Troubleshoot identification issues effectively
Was this article helpful?
If this solution has adequately addressed your query, please mark it as 'Helpful'.
This will help other community members who might have the same question find the answer more easily.
Thank you for your consideration! 🙏
Selva Arun
