Create and manage actions

Actions define reusable operations you can execute against nodes in an inventory. This section explains how to create, configure, and delete actions.

Broker actions

When you enable createBrokerActions, Inventory Manager automatically creates four actions configured to built-in Gateway Manager broker services:

• get-config
• set-config
• is-alive
• run-command

Device Broker operations (such as those used in command templates and Configuration Manager) require actions with these specific names. These actions can point to either the default built-in broker services or your own custom Gateway Manager services.

If you enable createBrokerActions and also define custom actions in the actions parameter, the inventory is populated with both the built-in and custom actions. If a custom action has the same name as a built-in action, the custom action takes priority.

For more information about broker services, see Built-in broker services.

Create actions

You can create actions when creating an inventory or add them afterward.

Create actions during inventory creation

Include actions in the inventory creation request using the actions parameter. You can also use the createBrokerActions parameter to automatically populate the inventory with built-in broker service actions.

API endpoint: POST /inventory_manager/v1/inventories

Required roles: inventory:create

Parameters:

Example request:

This request creates an inventory with the default broker actions. This example specifies custom parameters for the run-command action, while the remaining actions (get-config, is-alive, and set-config) use the default parameters configured to the built-in broker services.

1
{
2
  "name": "testInventory",
3
  "description": "",
4
  "groups": ["pronghorn_admin"],
5
  "tags": ["development"],
6
  "actions": [
7
    {
8
      "name": "run-command",
9
      "action_type": "iag5-service",
10
      "action_config": {
11
        "service_name": "custom-iag5-service",
12
        "cluster_id": "cluster_1"
13
      },
14
      "action_parameters": {
15
        "command": "show version"
16
      }
17
    }
18
  ],
19
  "createBrokerActions": true,
20
  "defaultClusterId": "cluster_1"
21
}

Add actions to existing inventories

Add actions to an inventory after creation using the create action endpoint.

API endpoint: POST /inventory_manager/v1/inventories/:inventoryIdentifier/actions

Required roles: inventory:update

Parameters:

For attribute details, see Inventory Manager concepts.

Example request:

1
{
2
  "name": "run-command",
3
  "action_type": "iag5-service",
4
  "action_config": {
5
    "service_name": "custom-iag5-service",
6
    "cluster_id": "cluster_1"
7
  },
8
  "action_parameters": {
9
    "command": "show version"
10
  }
11
}

Configure IAG 5 service actions

For the iag5-service action type, configure the IAG 5 service to execute and which Gateway Manager cluster to route the execution to.

Action configuration

action_config: Static configuration that doesn’t change between executions:

• service_name: The IAG 5 service to execute
• cluster_id: The Gateway Manager cluster to route execution to (optional, can be overridden by node attributes)

action_parameters: Default parameters that can be overridden at runtime, such as:

• timeout: Execution timeout in seconds
• Command-specific parameters

Example:

1
{
2
  "name": "get-config",
3
  "action_type": "iag5-service",
4
  "action_config": {
5
    "service_name": "get-config",
6
    "cluster_id": "cluster_1"
7
  },
8
  "action_parameters": {
9
    "timeout": 60
10
  }
11
}

Parameter resolution

When Inventory Manager executes an action, it merges parameters from multiple sources with the following priorities:

1. Runtime parameters (provided at execution)
2. Action parameters (defaults in action definition)
3. Action config (static configuration)
4. Node attributes (from target node)

Example:

Action definition:

1
{
2
  "name": "get-config",
3
  "action_config": {
4
    "service_name": "get-config",
5
    "cluster_id": "cluster_1"
6
  },
7
  "action_parameters": {
8
    "timeout": 60
9
  }
10
}

Node attributes:

1
{
2
  "name": "router-1",
3
  "attributes": {
4
    "cluster_id": "cluster_2",
5
    "ipaddress": "10.1.1.1"
6
  }
7
}

Runtime execution request:

1
{
2
  "nodeIdentifier": "router-1",
3
  "parameters": {
4
    "timeout": 120,
5
    "command": "show clock"
6
  }
7
}

Merged parameters sent to IAG 5:

1
{
2
  "service_name": "get-config",
3
  "cluster_id": "cluster_2",      // From node attributes
4
  "timeout": 120,                  // From runtime parameters
5
  "command": "show clock",         // From runtime parameters
6
  "ipaddress": "10.1.1.1"         // From node attributes
7
}

For IAG 5 service actions, the cluster_id from node attributes takes precedence over all other sources, allowing you to route execution based on device properties.

Delete actions

Remove an action from an inventory using the delete action endpoint.

API endpoint: DELETE /inventory_manager/v1/inventories/:inventoryIdentifier/actions/:actionIdentifier

Required roles: inventory:delete

Parameters: