Installation and Setup
Version Information
- Application Version: 2.0.0
- ServiceNow Compatibility: Certified for Yokohama and Zurich versions.
Table of Contents
- Before Starting
- Installing from the ServiceNow Store
- Configuration Using Guided Setup
- Accessing the Guided Setup
- Plugin requirements before Guided Setup
- How Guided Setup is structured
- Step 1: NetBox Setup Questionnaire
- Step 2: Automated: Clean URL
- Step 3: Automated: Save Admin API Key
- Step 4: Automated: Save Default Company
- Step 5: Automated: Lookup NetBox API Record
- Step 6: Automated: Update Connection Record
- Step 7: Setup Credential for ServiceNow to NetBox
- Step 8: Automated: Lookup NetBox API Credential
- Step 9: Automated: Associate Credential to Connection
- Step 10: Setup Credential for NetBox to ServiceNow
- Step 11: Setup Location Type
- Step 12: Determine NetBox Tenant Mapping
- Step 13: Create Default CI Classes in NetBox
- Step 14: Customize Classes Used by the Integration
- Step 15: Test Connections and Credentials
- Step 16: Finish Up
- What is no longer a Guided Setup activity
- Common Installation Issues
- Manually Configuring the Application
Before Starting
Before you start the installation, ensure the following requirements are met:
- Administrative Privileges: You must be logged in with admin privileges on both NetBox and ServiceNow instances
- ServiceNow Version: Yokohama and Zurich are certified for the NetBox Labs CMDB Integration application
- IntegrationHub License: Your ServiceNow instance must be licensed for IntegrationHub for proper integration functionality
- Required ServiceNow Applications Versions: Ensure you have access to install Workflow Studio v26.3+ and Playbook Experience v26.3+ (see Plugin requirements)
- Plugins before Guided Setup: Missing plugins should have been installed with the application. Confirm they are installed before you start the playbook, as described under Plugin requirements.
Installing from the ServiceNow Store
Install NetBox Labs CMDB Integration from the ServiceNow Store. The scoped application identifier is x_nbl_cmdb (display name NetBox Labs CMDB Integration).
- Open the ServiceNow Application Manager (path varies by release; commonly All > Application Manager).
- Search for NetBox Labs CMDB Integration or
x_nbl_cmdb. - Start the installation and complete any on-screen prerequisites (admin rights, licensing, plugin prompts).
- When installation finishes, confirm the NetBox application appears in the application navigator.
The ServiceNow Store distribution is the only one supported for current releases.
Configuration Using Guided Setup
After successful installation, use the built-in Guided Setup to configure the application:
Accessing the Guided Setup
Navigate to Guided Setup
- Go to All > NetBox > Configuration > Guided Setup
- Review the Pre-checklist and fulfill any outstanding requirements
- Click Get Started when ready
The playbook runs in the NetBox Labs CMDB Integration application scope. The first activity reminds you to switch to that scope before continuing; staying in global or another scope will prevent system properties and setup actions from applying correctly.
Plugin requirements before Guided Setup
The process definition ships a single Setup lane. Installing suggested plugins is not a numbered step inside Guided Setup. Complete this first:
- Install all plugins the instance suggests for this playbook (for example Workflow Studio and Playbook Experience versions compatible with your release)
- Plugins are mandatory for the integration; installation may run in the background
How Guided Setup is structured
Guided Setup is defined in the **netbox_cmdb_integration** process definition. It presents 16 activities in order (some are automated “headless” steps). A questionnaire at the start collects your NetBox base URL, your company (for department imports), and a temporary NetBox admin API key. Subsequent automated steps normalize the URL, persist those answers, look up the packaged HTTP(s) connection ("NetBox API"), and write the connection URL to that record. You no longer open a separate "create connection" form before credentials unless you are troubleshooting.
Step 1: NetBox Setup Questionnaire
Collect inputs used by later automated steps
- Work in the NetBox Labs CMDB Integration scope (see the on-screen notice).
- Complete the form:
- NetBox instance URL - base URL for your NetBox server (protocol and host; a following step strips a trailing slash if present)
- Your own company - used when NetBox departments are imported into ServiceNow
- Temporary NetBox admin API key - elevated access so ServiceNow can finish NetBox-side configuration during setup; stored temporarily and removed later in the flow (see Steps 15-16 and What is no longer a Guided Setup activity)
Submit the questionnaire to continue. Your answers drive the Automated steps that follow.
Step 2: Automated: Clean URL
Normalize the NetBox URL
- Removes a trailing slash from the URL you entered so it matches the format expected on the HTTP(s) connection record.
Step 3: Automated: Save Admin API Key
Persist the temporary NetBox admin key
- Writes the temporary admin API key from the questionnaire to the application’s stored configuration so automated NetBox API calls during setup can authenticate.
Step 4: Automated: Save Default Company
Persist your company choice
- Saves the company you selected so department imports from NetBox associate to the correct core_company record.
Step 5: Automated: Lookup NetBox API Record
Locate the packaged connection
- Resolves the existing NetBox API HTTP(s) connection record (the connection installed with the application, alias
**x_nbl_cmdb.NetBox_API**) for use in the next step.
Step 6: Automated: Update Connection Record
Apply the NetBox URL to the connection
- Updates that HTTP(s) connection with the cleaned NetBox instance URL (host/path as defined in the automated action).
MID Server (if NetBox is only reachable via MID): configure the connection record when needed. Go to All > Connections & Credentials > HTTP(s) Connections, open NetBox API, enable Use MID, and set MID fields. Do this before or during testing if your architecture requires it.
Step 7: Setup Credential for ServiceNow to NetBox
Create credentials for ServiceNow to call the NetBox API
- Create API credentials
- Username, Password, and API Token as shown on the page
- API token format
- MANDATORY: The API Token MUST be a hexadecimal string of exactly 32 characters (for example
a1b2c3d4e5f67890abcdef1234567890)
- Refresh behavior
- Revisiting or refreshing the page regenerates random values; if the step fails, copy the values again
- Troubleshooting
- Confirm token format, HTTP(s) connection (Step 6), and that the temporary admin key from the questionnaire (Steps 1 and 3) is still valid
Step 8: Automated: Lookup NetBox API Credential
Resolve the credential record
- Locates the ServiceNow credential record created for the NetBox API token so it can be tied to the connection in the next step.
Step 9: Automated: Associate Credential to Connection
Attach credential to the HTTP(s) connection
- Associates the NetBox API credential with the NetBox API HTTP(s) connection record automatically (no manual “open connection and pick credential” step in the happy path).
Step 10: Setup Credential for NetBox to ServiceNow
Create credentials for NetBox to call ServiceNow
- ServiceNow integration user
- Username and Password (you may change suggested values)
- API Key is generated for ServiceNow and must be copied into NetBox (for example webhook headers) as instructed
- Refresh behavior
- Same as Step 7: refreshing changes values; re-copy if needed
- Storage
- Credentials exist in ServiceNow and in NetBox (for example webhook configuration)
- Troubleshooting
- Verify the HTTP(s) connection (Step 6) and questionnaire admin key if NetBox-side configuration fails
Step 11: Setup Location Type
Map ServiceNow location types to NetBox site/region/location semantics
- Choose the ServiceNow location type that represents NetBox Sites; types with lower sequence classify as Regions, higher as Locations (see the FAQ for detail).
Step 12: Determine NetBox Tenant Mapping
Tenant import/export behavior
- Both - requires NetBox Tenant Group ID for Customers and NetBox Tenant Group ID for Departments in Application Parameters
- Customers only / Departments only - group IDs not required for distinction
- None - tenant sync off
Change later at All > NetBox > Configuration > Setup Tenant Usage.
Step 13: Create Default CI Classes in NetBox
Create NetBox device custom field and default classes
- Creates the ServiceNow CI class field on NetBox devices and seeds default classes; you refine the list next.
Step 14: Customize Classes Used by the Integration
Register CI classes
- Select CMDB classes to expose in NetBox; prefer up to six classes at a time for performance
- Further changes: All > NetBox > Configuration > Class Management
Step 15: Test Connections and Credentials
Validate connectivity
- Run ServiceNow → NetBox, then NetBox → ServiceNow (the second test runs only if the first succeeds)
- If association errors persist, confirm the HTTP(s) connection and credential linkage (Steps 6-9)
- Temporary admin key: successful completion of testing and/or Finish Up clears the temporary key from stored configuration (see your instance behavior if you exit early)
Step 16: Finish Up
Complete the playbook
- Final guided actions (for example confirming setup completion). Follow any on-screen wrap-up instructions.
What is no longer a Guided Setup activity
Older documentation described separate playbook phases for plugin install, create application parameters, upgrade database, a standalone temporary admin channel, and a manual “associate credential” step. In the current process definition:
| Former concept | Current behavior |
|---|---|
| Phase: Install plugins | Install required plugins before Guided Setup (Plugin requirements) |
| Create / reset Application Parameters | Not a dedicated step; parameters ship with the app and are updated by setup actions and configuration UIs as needed |
| Upgrade Database | Handled by upgrade/migration flows outside this playbook, not as a Guided Setup activity |
| Temporary admin channel | Replaced by the temporary NetBox admin API key in the questionnaire (Step 1) and Automated: Save Admin API Key (Step 3) |
| Manual "Create or Update Connection" as the first hands-on step | Questionnaire URL + Lookup NetBox API Record + Automated: Update Connection Record (Steps 1, 5-6) |
| Manual associate credential | Automated: Associate credential to connection (Step 9) |
Common Installation Issues
| Issue | Possible Cause | Solution |
|---|---|---|
| Store install fails or app not visible | Licensing, permissions, or instance eligibility | Confirm store access with your ServiceNow admin; search x_nbl_cmdb |
| Plugin Installation Errors | Missing dependencies or insufficient permissions | Verify ServiceNow admin privileges and dependency requirements |
| Connection Test Fails | Network connectivity or firewall issues | Check network configuration and firewall rules |
| API Token Rejected | Incorrect token format | Ensure API token is exactly 32 hexadecimal characters |
| Credential Association Fails | Timing or configuration issues | Retry association after verifying all previous steps |
| Temporary admin API key rejected | Invalid or expired NetBox admin token from the questionnaire | Create a new token in NetBox and re-run Guided Setup from the questionnaire, or enter a valid key |
| Guided Setup procedure is blank or doesn't start properly | ServiceNow issues with playbook compatibility between versions | Follow the steps outlined in the Manually Configuring the Application section below |
Manually Configuring the Application
The NetBox Labs CMDB Integration Guided Setup can be bypassed and the application configured correctly by manually following these steps. The order below roughly follows the same sequence as Guided Setup (questionnaire answers correspond to specific sys_properties and the packaged NetBox API connection). Precede all URLs with the addresses of your NetBox or ServiceNow instances.
| Step | Description | Target | URL |
|---|---|---|---|
| 1 | Create a temporary API Token for the admin user and note it for use at step 4 | NetBox | /users/tokens/ |
| 2 | Set and save the NetBox HTTPS connection URL | ServiceNow | /now/nav/ui/classic/params/target/http_connection.do%3Fsys_id%3De8f39d68934776102c9df0586003d621 |
| 3 | Copy the sys_id of your own company from core_company and paste it in the value field | ServiceNow | /now/nav/ui/classic/params/target/sys_properties.do%3Fsys_id%3D2a6e0c86cfb6fa10ff6e70d51d851cff |
| 4 | Paste the temporary NetBox API Token in the value field | ServiceNow | /now/nav/ui/classic/params/target/sys_properties.do%3Fsys_id%3D017019decf3a725073e7d1951d851c2d |
| 5 | Modify the form as required and save | ServiceNow | /now/nav/ui/classic/params/target/ui_page.do%3Fsys_id%3D0f03c84183d212104507ad20ceaad38d |
| 6 | Set and save the HTTPS connection credential field with "NetBox API Token" (created at step 5) | ServiceNow | /now/nav/ui/classic/params/target/http_connection.do%3Fsys_id%3De8f39d68934776102c9df0586003d621 |
| 7 | (Optional) Configure your MID Server if required | ServiceNow | /now/nav/ui/classic/params/target/http_connection.do%3Fsys_id%3De8f39d68934776102c9df0586003d621 |
| 8 | Modify the form as required and save | ServiceNow | /now/nav/ui/classic/params/target/ui_page.do%3Fsys_id%3D0a5fa5d7830212104507ad20ceaad300 |
| 9 | Fill the form and save | ServiceNow | /x/nbl/netbox-integration/setup-locations-sites-and-regions/ |
| 10 | Fill the form and save | ServiceNow | /x/nbl/netbox-integration/setup-tenant-usage/ |
| 11 | Launch default CI Class creation | ServiceNow | /x/nbl/netbox-integration/link-ci-classes/ |
| 12 | Customize CI Classes used by the integration | ServiceNow | /x/nbl/netbox-integration/netbox-class-management/ |
| 13 | Test API Connections | ServiceNow | /now/nav/ui/classic/params/target/ui_page.do%3Fsys_id%3De069878c832612104507ad20ceaad36d |
| 14 | Finish the ServiceNow installation | ServiceNow | /x/nbl/netbox-integration/finish-up/ |
| 15 | Remove temporary API Token created at step 1 | NetBox | /users/tokens/ |