---
title: Ansible job actions
source: https://docs.newrelic.com/docs/workflow-automation/setup-and-configure/actions-catalog/ansible/ansible-job-launch
---

This page provides a comprehensive reference for Ansible job actions available in the workflow automation actions catalog. These actions enable you to launch and manage Ansible Automation Platform (Automation Controller) job templates.

## Prerequisites

Before using Ansible actions in workflow automation, ensure you have:

-   An Ansible Automation Platform (Automation Controller) instance accessible over HTTPS.
-   An OAuth2 token with write scope to launch jobs (create one under **Automation Controller > Users > Tokens**).
-   The numeric ID of the job template you want to launch.
-   The `ask_*_on_launch` setting enabled on the job template for each optional input you plan to use (`extraVars`, `limit`, `inventory`).

## Job actions

**Launch an Ansible job template**

Launches an Ansible Automation Platform (Automation Controller) job template and returns the created job. This action builds on the `http.post` base action.

The endpoint is `POST https://{host}/api/controller/v2/job_templates/{jobTemplateId}/launch/`

### Inputs

| Input Field       | Optionality | Type   | Example                                                                                                                                                                          |
| ----------------- | ----------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **host**          | Required    | String | `${{ :secrets:host }}` Hostname (and optional port) of the Automation Controller, without scheme, for example aap.example.com.                                                   |
| **authToken**     | Required    | String | `${{ :secrets:ansibleControllerToken }}` OAuth2 token, sent as Authorization: Bearer <token>. Create under Automation Controller → Users → Tokens with write scope to launch. |
| **jobTemplateId** | Required    | Int    | `42`                                                                                                                                                                             |
| **extraVars**     | Optional    | Map    | ```yaml {"target_env": "staging", "app_version": "1.2.3"} ``` Mapped to `extra_vars`. Takes effect only if the template has `ask_variables_on_launch` (or a survey) enabled.     |
| **limit**         | Optional    | String | `web-servers` Ansible host pattern. Mapped to limit. Requires ask_limit_on_launch.                                                                                               |
| **inventory**     | Optional    | String | `7` Numeric inventory ID (overrides the template default). Mapped to inventory. Requires ask_inventory_on_launch.                                                                |
| **jobTags**       | Optional    | String | `deploy,restart` Comma-separated tags. Mapped to job_tags. Requires ask_tags_on_launch.                                                                                          |
| **skipTags**      | Optional    | String | `notifications` Comma-separated tags to skip. Mapped to skip_tags. Requires ask_skip_tags_on_launch.                                                                             |
| **selectors**     | Optional    | List   | ```yaml [{"name": "jobId", "expression": ".id"}, {"name": "status", "expression": ".status"}] ```                                                                                |

### Outputs

| Output Field     | Type    | Example                                                                                                           |
| ---------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| **success**      | Boolean | `success: true | false`                                                                                           |
| **response**     | Object  | ```yaml {   "id": 128,   "status": "pending",   "job_template": 42,   "url": "/api/controller/v2/jobs/128/" } ``` |
| **errorMessage** | String  | `{ "detail": "Variables not allowed on launch." }`                                                                |

### Example

| Workflow example                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ```yaml name: launch-ansible-remediation description: 'Launches an Ansible job template to remediate an incident' steps:   - name: launch_job     type: action     action: ansible.job.launch     version: 1     inputs:       host: ${{ :secrets:host }}       authToken: ${{ :secrets:ansibleControllerToken }}       jobTemplateId: "42"       extraVars:         target_env: staging         app_version: "1.2.3"     next: end ``` |