> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-platform/6/studio/tasks/reference/run-service/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# runService

> Reference for the runService workflow task, which runs an Itential Gateway 5 service from a workflow.

The **runService** task runs a registered Itential Gateway service from a workflow, using the gateway cluster and service you specify in the task panel. Use it to orchestrate gateway services, such as network automation scripts or infrastructure provisioning plans, as part of a larger Itential Platform workflow.

For steps on adding and configuring this task in a workflow, see [Add gateway services to workflows](/itential-gateway/add-services-to-workflows).

## Task properties

### Incoming

| Variable                | Type                          | Required    | Description                                                                                                                                                                                                                   |
| ----------------------- | ----------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clusterId`             | String                        | Yes         | The Gateway 5 cluster that runs the service. Configured in the task panel as **Gateway Cluster ID**.                                                                                                                          |
| `serviceName`           | String                        | Yes         | The name of the registered Gateway 5 service to run. Configured in the task panel as **Service Name**.                                                                                                                        |
| `params`                | Object                        | No          | Parameters passed to the service at execution. Configure these as input parameters using the key-value form or JSON code block. See [Set input parameters](/itential-gateway/add-services-to-workflows#set-input-parameters). |
| `params.action`         | String (`apply` \| `destroy`) | Conditional | Required for `opentofu-plan` services. Specifies whether to apply or destroy the plan.                                                                                                                                        |
| `inventory`             | Array of objects              | No          | Target inventory for the service, if the service accepts inventory-scoped execution.                                                                                                                                          |
| `inventory[].inventory` | String                        | Yes         | The inventory identifier.                                                                                                                                                                                                     |
| `inventory[].nodeNames` | Array of strings              | No          | Specific node names within the inventory to target.                                                                                                                                                                           |

### Outgoing

The task returns the execution status as a top-level field, alongside a nested `result` object with the execution details.

| Field                | Type                            | Description                                                                                              |
| -------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `id`                 | String                          | Identifier for the execution request.                                                                    |
| `jsonrpc`            | String                          | JSON-RPC protocol version. Always `2.0`.                                                                 |
| `status`             | String (`completed` \| `error`) | Execution status of the service run.                                                                     |
| `result.return_code` | Integer                         | Process exit code from the service execution. `0` indicates success; any other value indicates an error. |
| `result.stdout`      | String                          | Raw standard output from the service execution.                                                          |
| `result.stdout_json` | Any                             | The `stdout` content parsed as JSON. Present only when `stdout` is valid JSON.                           |
| `result.stderr`      | String                          | Standard error from the service execution.                                                               |

## Use runService output in downstream tasks

To use the runService output in a downstream task, configure that task's input with:

* **Previous Task**: the **runService** task
* **Task Variable**: `result.stdout_json` for the parsed JSON result, or any other output field

If you need a specific nested value from `result.stdout_json`, use a task query to extract it directly on the input field instead of adding a separate task to the canvas. See [Task query](/itential-platform/studio/workflows/tasks/configure-manage-tasks#task-query) for details.

## Errors

When execution fails, `status` returns `error`. Check `result.stderr` for the underlying failure or traceback.

## Related information

* [Add gateway services to workflows](/itential-gateway/add-services-to-workflows)
* [Configure and manage tasks](/itential-platform/studio/workflows/tasks/configure-manage-tasks)

> Reference for the runService workflow task, which runs an Itential Gateway 5 service from a workflow.