Create and populate inventories

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

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

Using workflows:

Use the createInventory task in Automation Studio.

Using API:

POST /inventory_manager/v1/inventories

Example request body:

{
  "name": "prod-routers",
  "description": "Production router inventory",
  "groups": ["network-ops", "network-admins"],
  "tags": ["production", "routers"]
}

Example response:

{
  "status": "Success",
  "result": {
    "_id": "60a7c8e9f1234567890abcde",
    "name": "prod-routers",
    "description": "Production router inventory",
    "groups": ["network-ops", "network-admins"],
    "tags": ["production", "routers"],
    "actions": [],
    "created_at": "2025-01-08T10:30:00.000Z",
    "updated_at": "2025-01-08T10:30:00.000Z",
    "created_by": "admin@example.com",
    "updated_by": "admin@example.com"
  }
}

Populate inventories with nodes

The populateInventory task replaces all nodes in an inventory with new node data. This replacement approach ensures your inventory exactly matches your source of truth.

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:

{
  "name": "core-router-1",
  "attributes": {
    "itential_host": "10.1.1.1",
    "itential_platform": "iosxr",
    "cluster_id": "cluster_east",
    "itential_user": "admin",
    "itential_password": "$SECRET_path $KEY_name"
  },
  "tags": ["production", "core"]
}

Using 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

Using API to populate inventories

External systems can populate inventories by calling the API directly:

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:

{
  "inventory_identifier": "prod-routers",
  "nodes": [
    {
      "name": "core-router-1",
      "attributes": {
        "itential_host": "10.1.1.1",
        "itential_platform": "iosxr",
        "cluster_id": "cluster_east",
        "itential_user": "$SECRET.network_devices.username",
        "itential_password": "$SECRET.network_devices.password"
      },
      "tags": ["core", "datacenter-1"]
    },
    {
      "name": "core-router-2",
      "attributes": {
        "itential_host": "10.1.1.2",
        "itential_platform": "iosxr",
        "cluster_id": "cluster_east",
        "itential_user": "$SECRET.network_devices.username",
        "itential_password": "$SECRET.network_devices.password"
      },
      "tags": ["core", "datacenter-1"]
    }
  ]
}

Example response:

{
  "status": "Success",
  "result": {
    "total": 2,
    "inserted": 2,
    "skipped": 0,
    "errors": []
  }
}

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

{
  "inventory_identifier": "inventory-name",
  "nodes": [
    { "name": "device-1", "attributes": {...} },
    { "name": "device-2", "attributes": {...} }
  ]
}

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