> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-platform/2023-2/inventory-manager/migrate-inventory-from-iag4/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Migrate inventory from Gateway 4

> Migrate inventory data from Gateway 4 to Inventory Manager while running both systems in parallel with minimal disruption.

Inventory Manager can run in parallel with Gateway 4, enabling gradual migration without disrupting your automation workflows. You can operate both systems simultaneously, validate your new setup, and transition at your own pace.

**During migration, you can:**

* Run Gateway 4 and Inventory Manager simultaneously
* Migrate inventory data from Gateway 4 to Inventory Manager
* Continue using Configuration Manager and command templates with both systems
* Transition workflows incrementally

**Why migrate?**

Migrating from Gateway 4 to Inventory Manager is a strategic modernization that improves reliability, simplifies integrations, and aligns with Itential Platform architecture. This guide provides step-by-step guidance for planning and executing your migration with minimal disruption.

**What's changing:**

Gateway 4 tightly couples inventory with execution engines. Inventory Manager decouples these concerns by introducing centralized, platform-managed inventory. Inventory data is federated from external systems, persisted within the Itential Platform, and refreshed explicitly via APIs or workflows. Execution is handled separately by Gateway 5 using standardized drivers and services.

**Learn more:**

* [Gateway 5 vs Gateway 4 feature comparison](/itential-gateway/5/gateway-feature-comparison)
* [Gateway Manager](/itential-gateway/gateway-manager-overview)

## Before you begin

### Prerequisites

* [Inventory Manager installed and configured](./configure-inventory-manager)
* [Platform Secrets Manager configured](/itential-platform/secrets/overview)
* Gateway 5 cluster deployed and accessible
* Gateway Manager adapter configured in Device Broker
* Identified source of truth for your inventory data

### Important considerations

* **No automatic synchronization**: Inventory Manager and Gateway 4 do not synchronize automatically. You'll manage inventory separately in each system during the transition.
* **Source of truth requirement**: Inventory Manager is not a system of record. If you currently use Gateway 4 as your source of record, you'll need to migrate to an external source such as NetBox, a CMDB, or a static file in a Git repository.
* **Migration sensitivity**: Migration may impact production automation. Plan for adequate testing and schedule appropriate change windows.
* **Workflow refactoring required**: Workflows using Gateway 4 AutomationGateway adapter tasks may need to be updated to use GatewayManager tasks.

## Step 1: Assess your current state

Document your Gateway 4 deployment:

### Inventory assessment

* How many Gateway 4 instances do you have?
* How is inventory segmented (device type, environment, team)?
* What is your source of truth (NetBox, ServiceNow, CMDB, Gateway 4 itself)?
* How frequently does inventory change?

### Usage analysis

* Which workflows use AutomationGateway adapter tasks?

* What Gateway 4 actions are used (is-alive, get-config, run-command, set-config)?

* Which Configuration Manager operations use Gateway 4 devices?

* Which command templates reference Gateway 4 devices?

## Step 2: Design your inventory structure

### Choose inventory boundaries

Common patterns include segmentation by device type, environment, region, team, or vendor/platform. Choose the pattern that matches your operational structure.

### Gateway 5 service selection

Identify which Gateway 5 drivers and platforms you'll use:

* Netmiko: Widely supported, good for CLI-based automation
* Scrapli: High-performance alternative to Netmiko
* Custom services: For specialized device interactions

For more information, see Configure driver options.

Map your Gateway 4 `ansible_network_os` values to Gateway 5 platform identifiers:

| Gateway 4 (`ansible_network_os`) | Gateway 5 (`itential_platform`) - Netmiko |
| -------------------------------- | ----------------------------------------- |
| iosxr                            | cisco\_xr                                 |
| ios                              | cisco\_ios                                |
| nxos                             | cisco\_nxos                               |
| eos                              | arista\_eos                               |
| junos                            | juniper\_junos                            |

### Plan tagging strategy

Use tags for device roles, environments, locations, criticality levels, or custom business attributes. For guidance, see [Tags and organization](./inventory-manager-tags).

## Step 3: Map inventory data

### Field mappings

| Field          | Gateway 4            | Inventory Manager         |
| -------------- | -------------------- | ------------------------- |
| Username       | `ansible_user`       | `itential_user`           |
| Password       | `ansible_password`   | `itential_password`       |
| Hostname       | `ansible_host`       | `itential_host`           |
| Port           | `ansible_port`       | `itential_port`           |
| Driver         | `ansible_connection` | `itential_driver`         |
| Platform       | `ansible_network_os` | `itential_platform`       |
| Driver options | N/A                  | `itential_driver_options` |

**Example transformation:**

Gateway 4:

```json
{
  "ansible_user": "admin",
  "ansible_password": "PASSWORD",
  "ansible_host": "10.0.1.1",
  "ansible_port": 22,
  "ansible_connection": "network_cli",
  "ansible_network_os": "iosxr"
}
```

Inventory Manager:

```json
{
  "itential_user": "admin",
  "itential_password": "$SECRET_xr_vault $KEY_xr_pass",
  "itential_host": "10.0.1.1",
  "itential_port": 22,
  "itential_driver": "netmiko",
  "itential_platform": "cisco_xr"
}
```

**Secrets management**: Migrate credentials from Ansible Vault to your Platform Secrets Manager. Reference secrets using `$SECRET_<secret_name> $KEY_<key_name>` notation.

### Sample field mapping template

You can use Jinja2 templates to transform inventory data. The following example demonstrates the approach. Adapt this template to reflect your specific structure:

```jinja2
{%- set os_map = {
  'iosxr': 'cisco_xr',
  'ios': 'cisco_ios',
  'nxos': 'cisco_nxos',
  'eos': 'arista_eos',
  'junos': 'juniper_junos'
} -%}
{
  "inventory_identifier": "production-inventory",
  "nodes": [
{%- for item in data %}
    {
      "name": "{{ item.name }}",
      "attributes": {
        "itential_user": "{{ item.variables.ansible_user }}",
        "itential_password": "$SECRET_vault $KEY_{{ item.variables.ansible_network_os }}_pass",
        "itential_host": "{{ item.variables.ansible_host }}",
        "itential_port": {{ item.variables.ansible_port }},
        "itential_platform": "{{ os_map.get(item.variables.ansible_network_os) }}",
        "itential_driver": "netmiko"
      },
      "tags": {{ item.tags | tojson }}
    }{{ "," if not loop.last else "" }}
{%- endfor %}
  ]
}
```

## Step 4: Populate and test inventories

### Create inventories

Create an automated process to populate Inventory Manager by using either an Itential workflow or a Python script. The process should:

1. Extract data from your external inventory system
2. Transform the data according to your mapping template
3. Populate Inventory Manager via the API
4. Schedule regular refreshes to keep inventory current

For more information, see [Create and populate inventories](./create-and-populate-inventories).

### Validate with built-in tools

1. Configuration Manager:
   * Test `is-alive` connectivity
   * Test `get-config` retrieval
   * Run compliance checks against test devices
   * Verify output format matches expectations
2. Studio: Command Templates:
   * Test `run-command` execution
   * Verify output parsing
   * Validate command templates with rules

**Common troubleshooting:**

* **Connectivity failures**: Check Gateway 5 network access, credentials, host/port values

* **Authentication failures**: Verify `$SECRET` references and credentials in Secrets Manager

* **Command issues**: Confirm `itential_platform` is correct, try both netmiko and scrapli drivers

* **Format differences**: Compare output to Gateway 4, adjust parsing logic if needed

## Step 5: Configure parallel operation

Configure the Inventory Manager adapter in Device Broker to enable both Gateway 4 and Inventory Manager during migration. For more information, see [Device Broker support](./device-broker-support).

In the Device Broker adapter configuration properties, set `prepend_inventory_name` to `true` to prevent device name collisions:

```json
{
  "inventories": "all",
  "prepend_inventory_name": true
}
```

This prevents device name collisions:

* Gateway 4 device: `core-router-1`
* Inventory Manager device: `production::core-router-1`

You can also expose specific inventories to Device Broker incrementally:

```json
{
  "inventories": ["prod-routers", "prod-switches"],
  "prepend_inventory_name": true
}
```

## Step 6: Refactor workflows

Workflows using Gateway 4 AutomationGateway adapter tasks need to be refactored to use the new GatewayManager tasks designed for Inventory Manager. The new sendCommand and sendConfig services are built for workflow automation and provide batch operation support with workflow-optimized inputs and outputs.

Task inputs and outputs have changed. The new architecture enhances performance and capabilities, but you must update workflows to ensure valid execution and data manipulation.

### Why refactor

Gateway 4 AutomationGateway tasks (isAlive, runCommand, getConfig, setConfig) were designed for internal Itential application use through Device Broker. Inventory Manager introduces sendCommand and sendConfig services that are:

* **Purpose-built for workflows**: Designed specifically for customer workflow automation
* **Optimized for batch operations**: Execute operations across multiple devices in a single task
* **User-friendly**: Simplified inputs and outputs tailored for workflow use
* **Better performance**: Optimized for workflow execution patterns

### Task mapping

If you're migrating workflows from Gateway 4, use this mapping to update your workflow tasks:

| Gateway 4 task                 | Description                                | Inventory Manager task       | Notes                                                                                                    |
| ------------------------------ | ------------------------------------------ | ---------------------------- | -------------------------------------------------------------------------------------------------------- |
| `AutomationGateway.isAlive`    | Verifies device is reachable               | `GatewayManager.sendCommand` | Use sendCommand with an appropriate command (for example, `show version`) to verify device accessibility |
| `AutomationGateway.runCommand` | Executes CLI command on device             | `GatewayManager.sendCommand` | Direct replacement with updated input structure                                                          |
| `AutomationGateway.getConfig`  | Retrieves running or startup configuration | `GatewayManager.sendCommand` | Use sendCommand with an appropriate show command (for example, `show running-config`)                    |
| `AutomationGateway.setConfig`  | Applies configuration change to device     | `GatewayManager.sendConfig`  | Direct replacement with updated input structure                                                          |

For more information on sendCommand and sendConfig, including required inventory node attributes, see [Send commands and configurations to devices via workflows](./sendcommand-sendconfig-workflows).

### Input structure

**Gateway 4 AutomationGateway tasks** required full device attributes in each task:

* Device connection details (host, user, password, platform) provided in task inputs
* Each task configured device attributes individually
* Limited batch operation support

**Gateway 5 GatewayManager tasks** leverage inventory data:

* Device attributes retrieved from Inventory Manager
* Tasks reference inventory names and node names
* Native batch operation support across multiple devices
* Simplified input parameters

### Refactoring process

For each workflow that uses Gateway 4, complete these steps:

1. Identify AutomationGateway adapter tasks
2. Replace with equivalent GatewayManager tasks
3. Update task inputs and outputs (formats have changed)
4. Update device references to use Inventory Manager inventories
5. Test thoroughly

**Recommended approach**: Start with low-risk workflows, refactor incrementally, and keep Gateway 4 versions as backup during transition.

## Step 7: Update Configuration Manager and command templates

### Configuration Manager

Update Configuration Manager components to use Inventory Manager devices:

* Create equivalent compliance policies for Inventory Manager devices
* Test golden configuration templates
* Validate backup and restore operations

For more information, see [Configuration Manager integration](./device-broker-support#configuration-manager).

### Command templates

Update command template operations:

* Test command templates against Inventory Manager devices
* Update device selection in automated workflows
* Verify result capture and processing

For more information, see [Command templates integration](./device-broker-support#command-templates).

## Step 8: Validate and decommission

### Validation

Run both systems in parallel to verify:

* All inventories migrated successfully
* All workflows refactored and tested
* Configuration Manager and command template operations working
* Performance meets or exceeds Gateway 4

### Decommission Gateway 4

1. Stop new Gateway 4 usage

2. Monitor for 48–72 hours for unexpected dependencies

3. Remove or disable Gateway 4 in Device Broker

4. Archive Gateway 4 configurations

5. Shut down Gateway 4 instances

> Migrate inventory data from Gateway 4 to Inventory Manager while running both systems in parallel with minimal disruption.