> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/cisco-nso/itential-tools-actions/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Itential Tools actions

> Reference for the workflow actions provided by the itential_tools package, with parameter examples for each action.

The `itential_tools` package exposes a set of actions that Platform workflows use to interact with NSO via JSON-RPC. These actions cover device configuration, interface management, NED translation, and configuration staging.

Actions are invoked from a workflow using the `runAction` task from the NSO adapter. The task takes the action `path` and a `params` object as inputs.

Actions that commit a change to NSO — such as `set_config`, `set_config_transactions`, `stage_device`, and `load_config` — participate in the adapter's trace-id propagation over JSON-RPC. See [Trace-ID propagation](./trace-id-propagation) for how to find the trace-id in a task's result and correlate it with NSO's own logs.

## How to call an action

#### Open Studio and create a workflow

Navigate to **Workflows** in Studio and create a new workflow.

#### Add the runAction task

Add the `runAction` task from the NSO/NSOManager task library to the workflow canvas.

#### Set the task inputs

Provide the `params` variable with the action `path` and any required parameters. See the reference below for each action's path and parameter structure.

## Actions reference

| Action                    | Description                                          |
| ------------------------- | ---------------------------------------------------- |
| `admin_down_device`       | Admin-down all admin-up interfaces on a device       |
| `admin_down_interfaces`   | Admin-down specific interfaces                       |
| `admin_up_interfaces`     | Admin-up specific interfaces                         |
| `getNamespaces`           | Return the namespace URI for a given prefix          |
| `get_config`              | Get the current device configuration                 |
| `load_config`             | Load configuration XML onto a device                 |
| `native2Pronghorn`        | Use the NED to convert native config into XPath      |
| `set_config`              | Set device configuration from a native config string |
| `set_config_transactions` | Set device configuration using a transaction object  |
| `stage_device`            | Stage a device from a native config string           |
| `translate_config`        | Translate config from native format to set format    |
| `verify_config`           | Verify that the NED can read a given config string   |

## Examples

Each example shows the complete `params` variable as entered in the `runAction` task dialog. The `path` field identifies the action endpoint on the NSO server.

### admin\_down\_device

Admin-down all admin-up interfaces on a device.

```json
{
  "params": {
    "device": "ios.1"
  },
  "path": "/itential_commands/admin_down_device"
}
```

### admin\_down\_interfaces

Admin-down specific interfaces on a device. Interfaces are passed as a JSON-encoded array string.

```json
{
  "params": {
    "device": "ios.0",
    "interfaces": "[\"GigabitEthernet{0}\",\"Ethernet{0/0/0}\"]"
  },
  "path": "/itential_commands/admin_down_interfaces"
}
```

### admin\_up\_interfaces

Admin-up specific interfaces on a device.

```json
{
  "params": {
    "device": "ios.0",
    "interfaces": "[\"GigabitEthernet{0}\"]"
  },
  "path": "/itential_commands/admin_up_interfaces"
}
```

### getNamespaces

Return the namespace URI for a given prefix.

```json
{
  "params": {
    "deviceName": "ios.0",
    "prefixes": "ncs"
  },
  "path": "/itential_commands/getNamespaces"
}
```

### get\_config

Retrieve the current configuration from a device. The `format` field controls whether config is returned in `NATIVE` format or another supported format.

```json
{
  "params": {
    "device": "ios.0",
    "format": "NATIVE"
  },
  "path": "/itential_commands/get_config"
}
```

### load\_config

Load configuration XML onto a device. The `action` field controls the merge strategy (`MERGE`, `REPLACE`, etc.).

```json
{
  "params": {
    "device": "ios.0",
    "action": "MERGE",
    "config": "<config xmlns=\"http://tail-f.com/ns/config/1.0\"><devices xmlns=\"http://tail-f.com/ns/ncs\"><device><n>ios.0</n><config><tailfned xmlns=\"urn:ios\"><police>cirmode</police></tailfned><ip xmlns=\"urn:ios\"><source-route>true</source-route><gratuitous-arps-conf><gratuitous-arps>true</gratuitous-arps></gratuitous-arps-conf><http><server>true</server><secure-server>true</secure-server></http></ip></config></device></devices></config>"
  },
  "path": "/itential_commands/load_config"
}
```

### native2Pronghorn

Use the NED to convert native CLI configuration into XPath format.

```json
{
  "params": {
    "ned_id": "cisco-ios-cli-6.72",
    "commands": "hostname test"
  },
  "path": "/itential_commands/native2Pronghorn"
}
```

### set\_config

Push a native CLI configuration string to a device. The `dryRun` field specifies the output format for a dry-run operation (`cli`, `native`, etc.). Omit `dryRun` to commit the change.

```json
{
  "params": {
    "device": "ios.0",
    "config": "hostname test",
    "deviceType": "cisco-ios-cli-6.72",
    "dryRun": "cli"
  },
  "path": "/itential_commands/set_config"
}
```

### set\_config\_transactions

Push configuration using a transaction object. The transaction tracks old and new values and supports multi-step rollback.

```json
{
  "params": {
    "device": "ios.0",
    "deviceType": "cisco-ios-cli-6.72",
    "transactions": {
      "id": 1,
      "new": "hostname test",
      "old": "",
      "parents": ""
    }
  },
  "path": "/itential_commands/set_config_transactions"
}
```

### stage\_device

Stage a device in NSO from a native CLI configuration string. Used to pre-provision device configuration before onboarding.

```json
{
  "params": {
    "device_name": "ios.1",
    "ned_id": "cisco-ios-cli-6.72",
    "commands": "hostname test"
  },
  "path": "/itential_commands/stage_device"
}
```

### translate\_config

Translate a native CLI configuration string into set-format commands. The `strategy` field controls the translation approach.

```json
{
  "params": {
    "ned_id": "cisco-ios-cli-6.72",
    "commands": "hostname test",
    "strategy": "access_list"
  },
  "path": "/itential_commands/translate_config"
}
```

### verify\_config

Verify that the NED can parse a given native CLI configuration string. Useful for validating configuration before pushing it to a device.

```json
{
  "params": {
    "ned_id": "cisco-ios-cli-6.72",
    "commands": "hostname test"
  },
  "path": "/itential_commands/verify_config"
}
```

## Related reading

* [Configure the NSO adapter](./configure-adapter)
* [RESTCONF API](./restconf-api)
* [Device customization](./device-customization)
* [Supported NSO versions](./supported-versions)
* [Trace-ID propagation](./trace-id-propagation)

> Reference for the workflow actions provided by the itential_tools package, with parameter examples for each action.