Skip to main content
CloudEnterprise

Upgrades and Bug Fixes

Version Information​

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

Table of Contents​

Distribution and Installation​

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

Critical: 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:

    • For detailed guidance on handling skipped records, refer to the official 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

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 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

Version 2.x Data Model:

  • 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:

  • All NetBox field data from v1.x base tables must be migrated to the v2.x attributes table
  • Application parameters and configuration settings are preserved
  • Synchronization relationships and correlation IDs are maintained
  • Base table fields are no longer used by the v2.x application logic; NetBox metadata is stored in x_nbl_cmdb_netbox_attributes

Pre-Upgrade Backup (Critical)​

CRITICAL RECOMMENDATION: Create a backup of your NetBox configuration and data before upgrading from v1.x to v2.x.

Why Create a Backup Before Upgrading:

  1. Safety Net: Provides a complete backup of NetBox configuration and field data
  2. Recovery Option: Enables quick restoration if upgrade encounters unexpected issues
  3. Validation Reference: Allows comparison of pre-upgrade vs post-upgrade data
  4. Rollback Support: Facilitates reversion to v1.x if necessary
  5. Documentation: Creates timestamped snapshot of your NetBox integration state

What the Backup Preserves:

  • All Application Parameters: Log levels, import/export settings, tenant configurations, force flags
  • NetBox Metadata: Correlation IDs, sync flags, export readiness, and object class stored in x_nbl_cmdb_netbox_attributes
  • Metadata: Version information, backup timestamp, record counts

When to Create a Backup:

  • Immediately before installing v2.x from the ServiceNow Store (after uninstalling v1.x per the migration procedure)
  • After confirming all synchronization is complete and stable
  • Before any configuration changes related to the upgrade
  • During a maintenance window when synchronization is paused

How to Create a Backup:

Execute the backup through a ServiceNow background script:

// Execute in ServiceNow Scripts - Background
var exporter = new x_nbl_cmdb.NetBoxDataUtils();
var result = exporter.exportNetBoxData();

// Log the results
gs.info('Backup Status: ' + (result.success ? 'SUCCESS' : 'FAILED'));
gs.info('File sys_id: ' + result.fileSysId);
gs.info('Messages: ' + result.messages.join('; '));

// Output for manual record-keeping
gs.info('===== BACKUP COMPLETE =====');
gs.info('Success: ' + result.success);
gs.info('File sys_id: ' + result.fileSysId);
gs.info('Timestamp: ' + new GlideDateTime().getDisplayValue());

if (result.success && result.fileSysId) {
    // Generate download URL (clickable in ServiceNow logs)
    var instanceUrl = gs.getProperty('glide.servlet.uri');
    var downloadUrl = instanceUrl + '/sys_attachment.do?sys_id=' + result.fileSysId;
    gs.info('DOWNLOAD URL: ' + downloadUrl);
    gs.info('Click the link above to download your backup file');
}

gs.info('========================');

Locating Your Backup File:

The backup script will output a direct download URL in the logs. Look for:

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

Alternative - Manual Access:

  1. Navigate to All > NetBox > Maintenance > Manage NetBox Data (backup/restore UI) or, for v1.x backups, open All > NetBox > Application parameters > System and the NetBox Log Level record
  2. On the Manage NetBox Data page, use the file management section to list attachments on the netbox_data_files NetBox Attributes record (v2.x+), or open the parameter record’s attachments (v1.x)
  3. Download the JSON backup file
  4. Filenames follow netbox_backup_<app_version>_<date_time>.json (for example, netbox_backup_2_0_0_2026-04-08_14:30:00.json); version segments use underscores and the date/time portion matches your instance display format
  5. Store the file securely for the v2.x restore process

Storage and Retention:

  • ServiceNow: Backup stored as a JSON attachment on the application record used for file storage (see the User Guide), not on sys_export_set
  • External Backup: Download and store JSON file in secure location outside ServiceNow
  • Multiple Copies: Consider storing copies in multiple locations (local, network share, cloud storage)
  • Retention: Maintain backups for at least 90 days post-upgrade or per organizational policy

Automatic Data Migration Process​

The NetBox Labs CMDB Integration application includes built-in automated migration logic that executes during the upgrade from v1.x to v2.x.

Migration Sequence:

  1. Upgrade Detection

    • Application detects previous version during installation
    • Identifies v1.x to v2.x upgrade scenario
    • Initiates NetBoxUpgrade class procedures

  2. Synchronization Pause

    • Import and export parameters automatically disabled during migration
    • Prevents data conflicts during transformation
    • Ensures data consistency throughout process

  3. Data Migration Execution

    • Reads NetBox fields from all base tables:
      • cmdb_ci and all CI subclasses
      • cmdb_hardware_product_model
      • cmn_location
      • cmn_department
      • core_company
    • Creates corresponding attribute records in x_nbl_cmdb_netbox_attributes
    • Preserves all field values, correlation IDs, and synchronization flags
    • Maintains relationships and dependencies

  4. Validation and Verification

    • Compares record counts between base tables and attributes table
    • Validates data integrity and completeness
    • Logs migration progress and any issues

  5. Synchronization Restoration

    • Re-enables import and export parameters to previous states
    • Resumes normal synchronization operations
    • Updates version tracking parameters

Migration Logging:

  • All migration activities logged to All > NetBox > Maintenance > NetBox Logs
  • Search for [NetBoxUpgrade] prefix in log messages
  • Log level automatically set to High during migration for detailed tracking

Expected Duration:

  • Migration time varies based on data volume
  • Estimate: ~1-2 minutes per 1,000 records
  • Large installations (10,000+ devices) may require 15-30 minutes

Post-Upgrade Validation​

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

Immediate Validation Steps:

  1. Check Upgrade Logs

    • Navigate to All > NetBox > Maintenance > NetBox Logs
    • Filter for [NetBoxUpgrade] messages
    • Verify "Successfully upgraded NetBox Labs CMDB Integration application" appears
    • Review any error or warning messages

  2. Verify Version Parameter

    • Open System Definition > System Properties, filter Application = NetBox Labs CMDB Integration, and locate x_nbl_cmdb.application_previous_version (this property is not on the Application parameters menu; see User Guide, Additional Parameters)
    • Find Application previous version
    • Confirm value shows your previous v1.x version (e.g., "1.4.0")
    • This indicates upgrade process completed successfully

  3. Validate Attribute Data

    • Review the x_nbl_cmdb_netbox_attributes table (for example All search NetBox Attributes, or System Definition > Tables, table NetBox Attributes). There is no separate NetBox Attributes item in the NetBox application menu (new in v2.x)
    • 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

  4. Compare Record Counts

Execute validation script in Scripts - Background:

// Validation Script for v2.x Upgrade
var validator = {
    tables: ['cmdb_ci', 'cmdb_hardware_product_model', 'cmn_location', 'cmn_department', 'core_company'],
    
    countAttributes: function(tableName) {
        var attrGr = new GlideRecord('x_nbl_cmdb_netbox_attributes');
        attrGr.addQuery('record_table', tableName);
        attrGr.query();
        return attrGr.getRowCount();
    },
    
    validate: function() {
        gs.print('===== V2.X UPGRADE VALIDATION =====');
        for (var i = 0; i < this.tables.length; i++) {
            var table = this.tables[i];
            var attrRecords = this.countAttributes(table);
            gs.print(table + ':');
            gs.print('  Attribute records: ' + attrRecords);
            gs.print('  Status: REVIEW (compare counts to expected synchronized records)');
            gs.print('');
        }
        gs.print('===================================');
    }
};

validator.validate();

  1. 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

  2. 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 3 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 back 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

How to Restore a Backup:

// Execute in ServiceNow Scripts - Background
var importer = new x_nbl_cmdb.NetBoxDataUtils();
var attachmentSysId = 'YOUR_EXPORT_FILE_ATTACHMENT_SYS_ID'; // From export step

var result = importer.importNetBoxData(attachmentSysId);

// Review results
gs.info('Import Status: ' + (result.success ? 'SUCCESS' : 'FAILED'));
gs.info('Parameters Imported: ' + result.importedParameters);
gs.info('Records Imported: ' + result.importedRecords);
gs.info('Attributes Imported: ' + result.importedAttributes);
gs.info('Errors: ' + result.errors.length);

if (result.errors.length > 0) {
    gs.info('Error Details: ' + result.errors.join('; '));
}

Important Considerations:

  • Import is safe to run multiple times (idempotent operation)
  • Only updates existing records; doesn't create new ones
  • Parameter import always succeeds (name-based matching)
  • Data import requires records to exist in target system
  • Review import results carefully for any errors or skipped records

Documentation and Support:

  • Document your backup file location and attachment sys_id
  • Maintain export/import logs for troubleshooting
  • Contact NetBox Labs support if recovery assistance needed
  • Provide validation script output and log excerpts when requesting support

Best Practice Summary:

  1. Export data before upgrading
  2. Store the backup file in multiple secure locations
  3. Validate migration immediately after upgrade
  4. Keep backup files for at least 90 days post-upgrade
  5. Test the restore procedure in a development environment if possible

Best Practices for Updates​

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 IntegrationHub 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

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 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 documentation
Records SkippedData validation or conflict issuesReview skipped records per ServiceNow documentation
Post-Update ErrorsConfiguration mismatchesVerify configuration and consult support
Performance DegradationResource conflicts or inefficient changesMonitor system resources and contact support
Related Topics
IntegrationNetBox
Last updated on