AppsStudioTasksTask reference

runService

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.

Task properties

Incoming

VariableTypeRequiredDescription
clusterIdStringYesThe Gateway 5 cluster that runs the service. Configured in the task panel as Gateway Cluster ID.
serviceNameStringYesThe name of the registered Gateway 5 service to run. Configured in the task panel as Service Name.
paramsObjectNoParameters passed to the service at execution. Configure these as input parameters using the key-value form or JSON code block. See Set input parameters.
params.actionString (apply | destroy)ConditionalRequired for opentofu-plan services. Specifies whether to apply or destroy the plan.
inventoryArray of objectsNoTarget inventory for the service, if the service accepts inventory-scoped execution.
inventory[].inventoryStringYesThe inventory identifier.
inventory[].nodeNamesArray of stringsNoSpecific 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.

FieldTypeDescription
idStringIdentifier for the execution request.
jsonrpcStringJSON-RPC protocol version. Always 2.0.
statusString (completed | error)Execution status of the service run.
result.return_codeIntegerProcess exit code from the service execution. 0 indicates success; any other value indicates an error.
result.stdoutStringRaw standard output from the service execution.
result.stdout_jsonAnyThe stdout content parsed as JSON. Present only when stdout is valid JSON.
result.stderrStringStandard 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 for details.

Errors

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