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

# Role execution parameters

> Reference for the JSON input parameters and response objects used when executing roles via the Itential Gateway REST API.

Itential Gateway clients execute roles on a device using the REST `/roles/{role_name}/execute` route. The role execution input parameter is a JSON object that contains an array of host strings and an `args` object that includes a set of key/value pairs specific to the role. A JSON schema describing each role's argument parameters is available via the `/roles/{role_name}` route. Detailed documentation on role endpoints can be found in the API Documentation section of the Itential Gateway UI.

## Role request object

Below is a sample role input parameter for the `itential_set_config` role:

```json
{
  "hosts":["eos_host"],
  "args":
  {  
    "transactions": [
      {
        "action": "add",
        "parents": ["interface Management 1"],
        "config_line": "ip address 10.1.2.3/24",
        "id": "anyIDString"
      }
    ]
  },
  "strict_args": true
}
```

An Ansible role consists of a number of tasks, each of which produces its own results object, as discussed in the section that follows.

Gateway collects the task results objects and returns them as an array in the order in which they were executed.

> **Info**
>
> For information on execution flow in the release versions of Gateway, see [Execution flow by role type](./ansible-execution-paths).

## Task results object and key

The Itential Ansible roles include a task results object with a task key whose value always takes the form of the **task key naming convention** shown below:

```json
{role} response
```

Where `{role}` is replaced with the name of the role executed.

*Example:* `itential_set_config response`

The `results` object from that `response` task contains the response data from the role for the device.

All other task results can be ignored and are available for informational and debugging purposes only.

The format of the data contained within the results object varies per role.

A status key also indicates whether the task succeeded (`SUCCESS`) or failed (`FAILURE`).

Roles that contain multiple requests will have multiple `response` objects, each with their own status and results keys.

## Role response

Below is the sample role response for the `itential_set_config` role:

```json
[
    {
        "role": "itential_set_config",
        "task": "execute config module on eos platform",
        "host": "eos_host",
        "status": "SUCCESS",
        "argument_warnings": null,
        "results": {
            "commands": [
                "interface Management 1",
                "ip address 10.0.5.17/24"
            ],
            "changed": true,
            "session": "ansible_1548718829",
            "updates": [
                "interface Management 1",
                "ip address 10.0.5.17/24"
            ],
            "diff": {
                "prepared": "--- system:/running-config\n+++ session:/ansible_1548718829-session-config\n@@ -27,6 +27,7 @@\n
    ip address 192.168.32.20/24\n !\n interface Management1\n+   ip address 10.0.5.17/24\n !\n ip route 0.0.0.0/0 10.0.2.2\n !"
            }
        }
    },
    {
        "role": "itential_set_config",
        "task": "itential_set_config response",
        "host": "eos_host",
        "status": "SUCCESS",
        "argument_warnings": null,
        "results": {
            "config_request": {
                "action": "add",
                "config_line": "ip address 10.0.5.17/24",
                "parents": [
                    "interface Management 1"
                ],
                "id": "anyIDString"
            },
            "config_response": {
                "failed": false,
                "changed": true,
                "id": "anyIDString"
            },
            "changed": false
        }
    }
]
```

> Reference for the JSON input parameters and response objects used when executing roles via the Itential Gateway REST API.