Skip to main content
CloudEnterprise

Upgrading NetBox Labs CMDB Integration

Version Information​

  • Application Version: 2.0.0
  • ServiceNow Compatibility: Certified for Yokohama, Zurich, and Australia versions.

Table of Contents​

Distribution and Installation​

Upgrades, patches, and hotfixes for the NetBox Labs CMDB Integration application are delivered exclusively through the ServiceNow Store (application identifier x_nbl_cmdb_integration, display name NetBox Labs CMDB Integration). Install or update the app from the store on your instance.

Review Update Status​

After installing or upgrading the application from the store, it is essential to review the update status for potential skipped records:

  1. Access Update Status

    • Navigate to All > Upgrade Center > Upgrade History
    • Click on the related list link in column "Skipped"

  2. Identify Skipped Records

    • Skipped records indicate potential conflicts or issues
    • Common causes include:
      • Local customizations conflicting with updates
      • Missing dependencies
      • Permission restrictions
      • Data validation failures

  3. Resolution Actions

    • Review each skipped record individually
    • Determine if manual intervention is required
    • Consult with your system administrator if needed
    • Document any unresolved skips for support escalation

  4. ServiceNow Documentation

Update Types and Considerations​

Major Version Upgrades​

  • Planning Required: May include significant changes to data model or functionality
  • Testing Recommended: Test in development environment before production deployment
  • Backup Advised: Create system backup before applying major updates
  • Documentation Review: Review release notes for breaking changes or new requirements

Patches and Minor Updates​

  • Focused Changes: Target specific issues or improvements
  • Lower Risk: Generally safer to apply directly to production
  • Cumulative: May include fixes from previous patches
  • Quick Deployment: Usually faster to install and validate

Hotfixes​

  • Urgent Nature: Address critical issues requiring immediate attention
  • Emergency Process: May bypass standard testing procedures
  • Limited Scope: Focus on specific critical problems
  • Rapid Deployment: Prioritized for quick resolution

Best Practices for Application Updates Through the ServiceNow Store​

Pre-Update Preparation​

  1. Environment Assessment:

    • Document current application version
    • Note any local customizations
    • Review system compatibility

  2. Backup Strategy:

    • Export NetBox integration data and document critical configuration (see User Guide — Manage NetBox Data)
    • Document critical business processes
    • Ensure rollback plan is available

  3. Testing Protocol:

    • Test updates in development environment when possible
    • Validate core functionality after update
    • Verify integration points remain functional

During Update Process​

  1. Monitoring:

    • Monitor system performance during installation
    • Watch for error messages or warnings
    • Document any unexpected behavior

  2. Communication:

    • Notify relevant stakeholders of update schedule
    • Coordinate with business users for testing
    • Maintain communication with NetBox Labs support if needed

Post-Update Validation​

  1. Functional Testing:

    • Test core synchronization processes
    • Verify API connectivity remains stable
    • Validate data integrity between systems

  2. Performance Monitoring:

    • Monitor system performance for any degradation
    • Check Integration Hub flow execution
    • Review system logs for new errors or warnings

  3. User Acceptance:

    • Coordinate with business users for validation
    • Gather feedback on any functional changes
    • Address any user-reported issues promptly

Upgrading from Version 1.x to Version 2.x​

Version 2.x represents a significant architectural evolution of the NetBox Labs CMDB Integration application, introducing a fundamental change in how NetBox data is stored and managed within ServiceNow. This section provides critical guidance for organizations upgrading from v1.x to v2.x.

Understanding the v1.x to v2.x Migration​

Architectural Changes:

Version 1.x data modelVersion 2.x data model
  • NetBox data stored as fields directly on base ServiceNow tables
  • Fields added to: cmdb_ci, cmdb_hardware_product_model, cmn_location, cmn_department, core_company
  • Example fields: x_nbl_cmdb_netbox_synchronize, x_nbl_cmdb_netbox_correlation_id (v1.x only)
  • Fixed schema limiting extensibility
  • NetBox data stored in a centralized NetBox Attributes table (x_nbl_cmdb_netbox_attributes)
  • Flexible key-value storage allowing unlimited custom attributes
  • Enhanced extensibility for future NetBox custom fields
  • Separation of concerns between ServiceNow core data and NetBox-specific data

Migration Impact:

  • A simple uninstall of the v1.x application and reinstall of v2.x from the store does not automatically preserve existing application parameters and synchronization metadata such as the Synchronize flag, the NetBox Location Type or the NetBox Correlation ID
  • When parameters and/or synchronization metadata must be preserved, data from v1.x base tables must be migrated to the v2.x attributes table using a migration tool. When doing so:
    • Application parameters and configuration settings are preserved
    • Synchronization relationships and correlation IDs are maintained
  • After the migration, fields that previously existed on base tables are deleted; NetBox metadata is stored in x_nbl_cmdb_netbox_attributes

Migration Options​

You can migrate the NetBox Labs CMDB Integration application with or without its existing data. This depends mainly on:

  • The environment where the NetBox Labs CMDB Integration application is installed (sub-production or production)
  • The effort already invested in data synchronization between NetBox and ServiceNow

Refer to the migration steps in the following table according to your selected option.

Without dataWith data
Installing the NetBoxDataUtils Script Include on top of the v1.x application
Performing the pre-upgrade backup of v1.x parameters and synchronization data
Performing a post-backup validation
Uninstalling the v1.x NetBox CMDB Integration applicationUninstalling the v1.x NetBox CMDB Integration application
Running the cleanup script after uninstalling the v1.x applicationRunning the cleanup script after uninstalling the v1.x application
Installing and configuring the v2.x application from the ServiceNow StoreInstalling and configuring the v2.x application from the ServiceNow Store
Restoring backed-up data in v2.x of the application
Post-Restore Validation

Migration Steps​

The following sections should be used according to the Migration option selected in the previous section.

Installing the NetBoxDataUtils Script Include on top of the v1.x application​

  • Navigate to All > System Definition > Script Includes
  • Load the provided file NetBox CMDB Integration v1.x NetBoxDataUtils.xml with the Import XML command (in the list view)
    • See your NetBox Labs CSE for the XML file, if unavailable
  • Make sure the NetBoxDataUtils script include is available in the list and can be opened

Performing the pre-upgrade backup of v1.x parameters and synchronization data​

The backup preserves:

  • All Application Parameters: Log levels, import/export settings, tenant configurations, force flags
  • NetBox Metadata: Correlation IDs, sync flags, export readiness information, NetBox Location Types
  • Metadata: Version information, backup timestamp, record counts

To proceed to the backup:

  • Follow the instructions in the NetBox CMDB Integration v1.x NetBoxDataUtils README.md file
    • See your NetBox Labs CSE for the MD file, if unavailable

To locate your backup file, look for the URL in the background script logs after the backup executed. It will look like:

DOWNLOAD URL: https://your-instance.service-now.com/sys_attachment.do?sys_id=...

IMPORTANT

  • The backup file is not preserved when the NetBox Labs CMDB Integration application is uninstalled
  • You must download a local copy of the backup file and store it for later use

Performing a post-backup validation​

  • Open the backup file in a text editor
  • Locate the metadata section
  • Validate record counts against the synchronized data you have in your ServiceNow instance

Uninstalling the v1.x NetBox CMDB Integration application​

  • If you performed a backup, double-check that the backup file has been downloaded locally
  • Navigate to All > sys_app.list
  • Locate and open the NetBox CMDB Application from the list
  • Click the Delete button and confirm the deletion

Running the cleanup script after uninstalling the v1.x application​

  • Navigate to All > System Definition > Scripts - Background
  • Copy and paste the cleanup script (v1.x uninstall)
  • Read the instructions and run it when ready

Installing and configuring the v2.x application from the ServiceNow Store​

  • Refer to instructions provided in the ServiceNow Store to install the v2.x application

Restoring backed-up data in v2.x of the application​

  • Navigate to All > NetBox > Maintenance > Manage NetBox Data
  • Follow on-screen instructions to restore the backup file

Post-Restore Validation​

After completing the v1.x to v2.x upgrade, perform comprehensive validation to ensure successful migration.

  1. Verify Parameters

    • Open System Definition > System Properties, filter Application = NetBox Labs CMDB Integration
    • Confirm values show your previous v1.x version
    • If some values are missing or wrong, you can manually restore them by identifying them in the backup file:
      • Locate the parameters section
      • Refer to the file format in the reference section below

  2. Validate Attribute Data

    • Navigate to All > x_nbl_cmdb_netbox_attributes.list
    • Verify table contains records (should have entries for each device, location, etc.)
    • Sample check: Each synchronized record should have a 1:1 attributes row keyed by record_sys_id, including fields like nb_id, nb_sync, nb_class, nb_ready_exp, and nb_ready_msg
    • If some values are missing or wrong, you can manually restore them by identifying them in the backup file:
      • Locate the attributes section
      • Refer to the file format in the reference section below

  3. Test Synchronization

    • Import Test: Tag a test device in NetBox with ServiceNowSyncTo, verify import works
    • Export Test: Flag a test device in ServiceNow, verify export to NetBox succeeds
    • Bidirectional Test: Make changes in both systems, confirm synchronization functions properly

  4. Verify UI and Navigation

    • Open All > NetBox > Synchronized Data > NetBox Devices or All > NetBox > Synchronized Data > NetBox Sites (and related lists) and confirm NetBox-related views and fields work as expected
    • Optionally review the x_nbl_cmdb_netbox_attributes table (see step 2 above) to confirm attribute rows exist for synchronized records

Issue Resolution

If validation identifies problems:

  • Review NetBox logs for specific error messages
  • Check that all base table records have corresponding attribute entries
  • Verify Application parameters are correctly set (All > NetBox > Application parameters)
  • Contact NetBox Labs support with validation script output and log excerpts

Using Backups for Recovery​

If you encounter issues during or after the v1.x to v2.x upgrade, your pre-upgrade export provides multiple recovery options.

Recovery Scenarios:

Scenario 1: Migration Completed but Data Appears Incorrect

  • Restore the v1.x backup into the v2.x system
  • The restore will automatically convert table-based data to attributes format
  • Provides second opportunity for clean data migration

Scenario 2: Need to Restore Application Parameters Only

  • Restore the v1.x backup
  • Only parameters will restore (matched by name, not sys_id)
  • Record data won't overwrite (different data models)
  • Useful if parameter settings were inadvertently changed

Scenario 3: Complete Rollback to v1.x Required

  • Uninstall v2.x application
  • Reinstall v1.x version
  • Restore the v1.x backup to restore configuration
  • Note: Data in base tables remains unchanged during upgrade, so rollback is primarily configuration restoration

Restoring a Backup​

Starting the v2.x, the NetBox Labs CMDB Integration application offers a data management tool, available from All > NetBox > Maintenance > Manage NetBox Data.

Troubleshooting Update Issues​

IssuePossible CauseResolution
Store install or upgrade failsLicensing, eligibility, or missing dependenciesConfirm store access with your ServiceNow admin; verify prerequisites in Installation; search x_nbl_cmdb_integration in the store
App installed but menus or flows missingSkipped records or incomplete installReview All > Upgrade Center > Upgrade History and resolve skipped records per ServiceNow Store - Links and documents
Records skippedData validation or conflict issuesReview skipped records per ServiceNow Store - Links and documents
Post-Update ErrorsConfiguration mismatchesVerify configuration and consult support
Performance degradationResource conflicts or inefficient changesMonitor system resources and contact support

Reference - NetBox Cleanup script (after v1.x uninstall)​

Run the JavaScript code below in a Bachground scriptafter uninstalling the v1.x application to remove leftover records.

/** 
 * Deletes records from the NetBox Labs CMDB Integration application that stay behind after the application is removed from an instance
 * Instructions:
 * - Switch to the Global scope
 * - On the first run, set the testRun variable to true
 * - Examine the tables and records to be deleted
 * - If everything is ok, run again with variable testRun = false
 * 
**/

gs.invalidateCache();
var testRun = true; // true: display records only, don't delete; false: delete records

var cleanUpTables = {
	sys_ui_form_sections: "sys_ui_form_section"
};
var sysIdRegExp = /([a-f0-9]{32})/i;
var tableRegExp = /([a-z0-9_]*)_[a-f0-9]{32}/i;
var payloadSysIdRegExp = /\<sys_id\>([a-f0-9]{32})\<\/sys_id\>/i;
var payloadTableRegExp = /\<record_update\>\<([a-z_]*)\s/;


// Step 1 : Delete Update XML records

gs.info("Deleting entries from sys_update_xml and their targets");
var recordsToDelete = new GlideRecord('sys_update_xml');
recordsToDelete.addQuery('target_name','CONTAINS', 'netbox');
recordsToDelete.addQuery('target_name','CONTAINS', 'cmdb');
recordsToDelete.orderBy('type');
recordsToDelete.query();
gs.info("Examining " + recordsToDelete.getRowCount() + " entries in sys_update_xml");
var entry = 0;

while (recordsToDelete.next()) {
	entry++;
	var sysId = '';
	var table = '';
	var type = recordsToDelete.getValue('type');
	var name = recordsToDelete.getValue('name');
	var target = recordsToDelete.getValue('target_name');
	var payload = recordsToDelete.getValue('payload');
	gs.info(`Entry ${entry}: ${type} - ${name} targets ${target}`);
	
	// Get the sys_id and table in the name or payload fields
	var nameResult = name.match(sysIdRegExp);
	if (Array.isArray(nameResult) && nameResult.length > 0) {
		sysId = nameResult[0];
		var tableResult = name.match(tableRegExp);
		if (Array.isArray(tableResult) && tableResult.length > 0) {
			table = tableResult[1];
		}
	}
	else {
		var payloadResult = payload.match(payloadSysIdRegExp);
		if (Array.isArray(payloadResult) && payloadResult.length > 0) {
			sysId = payloadResult[0].match(sysIdRegExp)[0];
			tableResult = payload.match(payloadTableRegExp);
			if (Array.isArray(tableResult) && tableResult.length > 0) {
				table = tableResult[1];
			}
		}
	}

	if (table && sysId) {
		// Clean some misspelled table names
		if (typeof(cleanUpTables[table]) !== 'undefined') {
			table = cleanUpTables[table];
		}

		// check for the existence of a record
		try {
			var t = new GlideRecord(table);
			if (t.get(sysId)) {
				gs.info('    !! Target record exists -- Deleting sys_id=' + sysId + ' from table ' + table);
				if (!testRun) {
					t.deleteRecord();
				}
			}
			else {
				gs.info('    XX No target record in ' + table + ' with sys_id=' + sysId);
			}
		} catch {
			gs.info('    XX Target table and/or record don\'t exist');
			continue;
		}
		
		
	}

	gs.info(`Deleting sys_update_xml entry ${entry}`);
	if (!testRun) {
		recordsToDelete.deleteRecord();
	}

	gs.info('\n');
}
gs.info('\n');

// Step 2: delete records from sys_update_version

gs.info("Deleting entries from sys_update_version and their related records");
entry = 0;
recordsToDelete = new GlideRecord('sys_update_version');
recordsToDelete.addQuery('record_name', 'CONTAINS', 'netbox');
recordsToDelete.addQuery('record_name', 'CONTAINS', 'cmdb');
recordsToDelete.query();
gs.info("Examining " + recordsToDelete.getRowCount() + " entries in sys_update_version:");
while(recordsToDelete.next()) {
	entry++;
	sysId = '';
	table = '';
	type = recordsToDelete.getValue('type');
	name = recordsToDelete.getValue('name');
	payload = recordsToDelete.getValue('payload');
	gs.info(`Entry ${entry}: ${type} - ${name}`);
	
	// Get the sys_id and table in the name or payload fields
	nameResult = name.match(sysIdRegExp);
	if (Array.isArray(nameResult) && nameResult.length > 0) {
		sysId = nameResult[0];
		tableResult = name.match(tableRegExp);
		if (Array.isArray(tableResult) && tableResult.length > 0) {
			table = tableResult[1];
		}
	}
	else {
		var payloadResult = payload.match(payloadSysIdRegExp);
		if (Array.isArray(payloadResult) && payloadResult.length > 0) {
			sysId = payloadResult[0].match(sysIdRegExp)[0];
			tableResult = payload.match(payloadTableRegExp);
			if (Array.isArray(tableResult) && tableResult.length > 0) {
				table = tableResult[1];
			}
		}
	}

	if (table && sysId) {
		// Clean some errored table names
		if (typeof(cleanUpTables[table]) !== 'undefined') {
			table = cleanUpTables[table];
		}

		// check for the existence of a record
		try {
			var t = new GlideRecord(table);
			if (t.get(sysId)) {
				gs.info('    !! Related record exists -- Deleting sys_id=' + sysId + ' from table ' + table);
				if (!testRun) {
					t.deleteRecord();
				}
			}
			else {
				gs.info('    XX No related record in ' + table + ' with sys_id=' + sysId);
			}
		} catch {
			gs.info('    XX Related table and/or record don\'t exist');
			continue;
		}
		
		
	}

	gs.info(`Deleting sys_update_version entry ${entry}`);
	if (!testRun) {
		recordsToDelete.deleteRecord();
	}

	gs.info('\n');
}
gs.info('\n');


// Step 3: delete other records here and there

gs.info("Deleting entries from help_user_interaction");
entry = 0;
recordsToDelete = new GlideRecord('help_user_interaction');
recordsToDelete.addQuery('setup_name', 'CONTAINS', 'NetBox');
recordsToDelete.addQuery('setup_name', 'CONTAINS', 'CMDB');
recordsToDelete.query();
gs.info("Examining " + recordsToDelete.getRowCount() + " entries:");
while(recordsToDelete.next()) {
	entry++;
	gs.info(`Deleting entry ${entry}: ${recordsToDelete.getValue('setup_name')}`);
	if (!testRun) {
		recordsToDelete.deleteRecord();
	}
}

gs.info("Deleting entries from api_key_credentials");
entry = 0;
recordsToDelete = new GlideRecord('api_key_credentials');
recordsToDelete.addQuery('setup_name', 'CONTAINS', 'NetBox');
recordsToDelete.addQuery('setup_name', 'CONTAINS', 'Token');
recordsToDelete.query();
gs.info("Examining " + recordsToDelete.getRowCount() + " entries:");
while(recordsToDelete.next()) {
	entry++;
	gs.info(`Deleting entry ${entry}: ${recordsToDelete.getValue('name')}`);
	if (!testRun) {
		recordsToDelete.deleteRecord();
	}
}

Reference - NetBox Backup Data Format​

Overview​

The NetBox Labs CMDB Integration uses a unified JSON format for data export and import that is compatible across versions 1.x and 2.x+. This allows data to be exported from one version and imported into another seamlessly.

Unified JSON Structure​

{
  "metadata": {
    "exportDate": "2026-01-30 14:30:00",
    "exportTimestamp": "20260130143000",
    "version": "1.4.0",
    "majorVersion": "1.4",
    "sourceVersion": "1.x",
    "dataModel": "table-based",
    "formatVersion": "1.0",
    "description": "NetBox Labs CMDB Integration data export - compatible across versions",
    "exportedSections": {
      "parameters": true,
      "tables": true,
      "attributes": false
    },
    "counts": {
      "parameters": 15,
      "tables": 5,
      "records": 250,
      "attributes": 0
    }
  },
  "parameters": [
    {
      "sys_id": "xyz123...",
      "parameter": "NetBox Log Level",
      "value": "medium",
      "parameter_description": "Logging level for NetBox operations",
      "order": "100"
    },
    {
      "sys_id": "xyz456...",
      "parameter": "Application previous version",
      "value": "1.3.0",
      "parameter_description": "Previous application version",
      "order": "200"
    }
  ],
  "attributes": [
    {
      "sys_id": "d15789...",
      "record_table": "cmdb_ci",
      "record_sys_id": "abc123...",
      "record_name": "Server-01",
      "nb_id": "123",
      "nb_class": "device",
      "nb_sync": "true",
      "nb_ready_exp": "false",
      "nb_ready_msg": "",
      "sn_location_level": null,
      "record_updated": "2026-01-30 14:25:00"
    },
    {
      "sys_id": "0e3012...",
      "record_table": "cmn_location",
      "record_sys_id": "def456...",
      "record_name": "Building A",
      "nb_id": "456",
      "nb_class": "site",
      "nb_sync": "true",
      "nb_ready_exp": "true",
      "nb_ready_msg": "Ready for export",
      "sn_location_level": "1",
      "record_updated": "2026-01-30 14:26:00"
    }
  ]
}

Section Descriptions​

Metadata​

The backup file includes rich metadata for tracking and future-proofing:

FieldDescriptionExample
exportDateHuman-readable export date/time"2026-01-30 14:30:00"
exportTimestampNumeric timestamp for sorting"20260130143000"
versionFull source version"1.4.0"
majorVersionMajor version string"1.4"
sourceVersionVersion category"1.x" or "2.x+"
dataModelData storage model"table-based" or "attribute-based"
formatVersionExport format version"1.0"
exportedSectionsWhich sections contain data{parameters: true, tables: true, attributes: false}
countsCount of exported items{parameters: 15, tables: 5, records: 250, attributes: 0}

At restore time, logs are produced showing detailed metadata information:

  • Source version and data model
  • Target version and data model
  • Whether data conversion is required
  • Expected counts for validation

Parameters (Common to Both Versions)​

  • Backup populates the parameters section with all NetBox configuration parameters
  • Parameters are exported from the sys_properties table or, if the backup was performed in v1.x version of the application, from the x_990381_netbox_cl_netbox_parameters table
  • Parameters include configuration settings like log levels, version tracking, sync settings, etc.
  • Parameters are restored by matching the parameter name field

Attributes​

  • Backup populates the attributes section with all rows from x_nbl_cmdb_netbox_attributes table or, if the backup was performed in v1.x version of the application, from the NetBox fields on base tables.
  • Each attribute row represents all NetBox metadata for one ServiceNow record (1:1 relationship)
  • Contains fields: record_table, record_sys_id, nb_id, nb_class, nb_sync, nb_ready_exp, nb_ready_msg, sn_location_level, record_updated

Notes​

  1. Rich Metadata: Exports include detailed metadata for tracking and future version-specific logic
  2. Parameters First: Parameters are always imported before data, ensuring configuration is set correctly
  3. Data Validation: The import process validates that records exist before updating them
  4. Error Handling: All errors are logged and collected in the result object
  5. Field Validation: Only valid fields are updated during import
  6. Idempotent: Imports can be run multiple times safely
  7. File Storage: Export files are attached to sys_export_set records
  8. Backward Compatible: The format includes metadata to ensure proper handling
  9. Parameter Matching: Parameters are matched by name, not sys_id, for better portability
  10. Future-Proof: Metadata enables version-specific import logic to be added later without breaking compatibility

Table-Specific Fields​

Base Tables (v1.x)​

All base tables include these NetBox fields:

  • x_990381_netbox_cl_netbox_synchronize
  • x_990381_netbox_cl_netbox_correlation_id
  • x_990381_netbox_cl_netbox_ready_export
  • x_990381_netbox_cl_netbox_ready_message

Location Table Additional Fields (v1.x)​

  • x_990381_netbox_cl_netbox_type
  • x_990381_netbox_cl_is_netbox_region (v1.3 or earlier)
  • x_990381_netbox_cl_is_netbox_site (v1.3 or earlier)
  • x_990381_netbox_cl_netbox_type (v1.4)
  • x_990381_netbox_cl_level

Attributes Table (v2.x+)​

Each row in x_nbl_cmdb_netbox_attributes contains all NetBox metadata for one ServiceNow record:

  • record_table - Source table name (e.g., 'cmdb_ci', 'cmn_location')
  • record_sys_id - Reference to the ServiceNow record
  • nb_id - NetBox correlation ID (unique identifier in NetBox)
  • nb_class - NetBox object class/type (e.g., 'device', 'site', 'region', 'location')
  • nb_sync - Boolean synchronization flag
  • nb_ready_exp - Boolean export readiness flag (read-only)
  • nb_ready_msg - Export readiness validation message (read-only)
  • sn_location_level - Hierarchical level for location records (integer)
  • record_updated - Last update timestamp

Parameters Table (All Versions)​

  • parameter - Parameter name (unique identifier)
  • value - Parameter value
  • parameter_description - Description of what the parameter controls
  • order - Display order for UI presentation
Related Topics
IntegrationNetBox
Last updated on