Create and populate inventories

This topic explains how to create inventories and populate them with nodes using workflows, API calls, or webhooks.

Create an inventory

Create inventories using Inventory Manager tasks in workflows or by calling the API directly.

Required attributes:

• Name: Unique identifier (globally unique across all inventories)
• Groups: One or more user groups for RBAC

Optional attributes:

• Description: Optional descriptive text
• Actions: Array of operations for nodes in this inventory (optional at creation)
• Tags: Labels for organization and filtering

Use workflows

Use the createInventory task in Studio.

Use the API

1
POST /inventory_manager/v1/inventories

Example request body:

1
{
2
  "name": "prod-routers",
3
  "description": "Production router inventory",
4
  "groups": ["network-ops", "network-admins"],
5
  "tags": ["production", "routers"]
6
}

Example response:

1
{
2
  "status": "Success",
3
  "result": {
4
    "_id": "60a7c8e9f1234567890abcde",
5
    "name": "prod-routers",
6
    "description": "Production router inventory",
7
    "groups": ["network-ops", "network-admins"],
8
    "tags": ["production", "routers"],
9
    "actions": [],
10
    "created_at": "2025-01-08T10:30:00.000Z",
11
    "updated_at": "2025-01-08T10:30:00.000Z",
12
    "created_by": "admin@example.com",
13
    "updated_by": "admin@example.com"
14
  }
15
}

Populate inventories with nodes

The populateInventory task replaces all nodes in an inventory with new node data. Inventory Manager federates data from your external inventory systems — it does not act as the authoritative source for device information. This full-replacement model ensures Inventory Manager accurately reflects your inventory system.

How it works:

1. Deletes all existing nodes in the inventory
2. Inserts the new nodes
3. Returns success or failure

Node data format

Each node in the nodes array requires only a name (unique within the inventory). The attributes and tags properties are optional.

Example node data:

1
{
2
  "name": "core-router-1",
3
  "attributes": {
4
    "itential_host": "10.1.1.1",
5
    "itential_platform": "iosxr",
6
    "cluster_id": "cluster_east",
7
    "itential_user": "admin",
8
    "itential_password": "$SECRET_path $KEY_name"
9
  },
10
  "tags": ["production", "core"]
11
}

Use workflows to populate inventories

Workflows are the recommended approach for populating inventories because they can:

• Extract data from your source of truth
• Transform data to the required format
• Handle errors and retries
• Run on schedules to keep inventories synchronized

Common workflow pattern:

1. Extract device data from source system (Netbox, ServiceNow, spreadsheet, database, etc.)
2. Transform data to Inventory Manager node format
3. Call populateInventory task with inventory identifier and node array
4. Handle success or error responses

Use the API to populate inventories

External systems can populate inventories by calling the API directly:

1
POST /inventory_manager/v1/nodes/bulk

This approach is useful for:

• External automation systems pushing updates
• Python scripts managing inventory
• CI/CD pipelines updating inventories

Example request body:

1
{
2
  "inventory_identifier": "prod-routers",
3
  "nodes": [
4
    {
5
      "name": "core-router-1",
6
      "attributes": {
7
        "itential_host": "10.1.1.1",
8
        "itential_platform": "iosxr",
9
        "cluster_id": "cluster_east",
10
        "itential_user": "$SECRET.network_devices.username",
11
        "itential_password": "$SECRET.network_devices.password"
12
      },
13
      "tags": ["core", "datacenter-1"]
14
    },
15
    {
16
      "name": "core-router-2",
17
      "attributes": {
18
        "itential_host": "10.1.1.2",
19
        "itential_platform": "iosxr",
20
        "cluster_id": "cluster_east",
21
        "itential_user": "$SECRET.network_devices.username",
22
        "itential_password": "$SECRET.network_devices.password"
23
      },
24
      "tags": ["core", "datacenter-1"]
25
    }
26
  ]
27
}

Example response:

1
{
2
  "status": "Success",
3
  "result": {
4
    "total": 2,
5
    "inserted": 2,
6
    "skipped": 0,
7
    "errors": []
8
  }
9
}

Use webhooks to populate inventories

Configure external systems to push inventory updates to Inventory Manager via webhooks by calling the populateInventory API endpoint.

This approach is useful when:

• Your inventory system can push updates on changes
• You want real-time inventory synchronization
• You’re using systems like Netbox with webhook capabilities

Webhook configuration:

Configure your external system (Netbox, ServiceNow, etc.) to POST to:

https://your-platform-instance/inventory_manager/v1/nodes/bulk

Webhook payload format:

1
{
2
  "inventory_identifier": "inventory-name",
3
  "nodes": [
4
    { "name": "device-1", "attributes": {...} },
5
    { "name": "device-2", "attributes": {...} }
6
  ]
7
}

Best practices

Source of truth discipline:

• Always populate from your actual source of truth
• Don’t manually edit inventory data that should come from the source
• Document which source populates each inventory

Error handling:

• Include retry logic in population workflows
• Log population attempts and failures
• Alert on repeated failures

Testing:

• Test population workflows with small datasets first
• Validate node data format before populating
• Use non-production inventories for testing