Job actions

Launch, abort, relaunch, approve or reject, and delete a job

  1. Launch a job
    1. Who can launch a form
    2. Before you submit
    3. Choices at launch time
    4. What can stop a launch
    5. Other ways to start a job
  2. Abort a job
  3. Relaunch a job
    1. Relaunch with pre-filled data
  4. Approve or reject a job
  5. Delete a job

Launch a job

Every job starts from a form. Open it from the Forms page, fill in the fields and press Submit:

  1. The form is validated in the browser, and the field values are posted to the server.
  2. The server creates the job and returns its number; the form’s onSubmit actions run.
  3. The job’s output appears under the form and refreshes every two seconds until the job ends.

The job also appears on the Jobs page, where you can follow it later.

Who can launch a form

A form is listed, and can be launched, for users who have one of the roles in its roles list. The default role, which every user has, makes a form available to everyone who can sign in.

Before you submit

The bar above the fields offers a few tools, each shown only when your role allows it:

Button What it does Role option
Show extravars Previews the extravars the job will receive, as you fill in the fields showExtraVars
verbose Runs the job in verbose mode allowVerboseMode
Load from store Fills the fields from a stored job allowStoredJobs
Reload this form Loads the form again, with its default values none

Choices at launch time

A form can let its users pick some Ansible options when they launch it, by declaring a field with a reserved name. The value of the field then overrides the form’s own setting:

Field name Overrides Typical field type
__check__ Check mode, a dry run that changes nothing checkbox
__diff__ Diff mode, which shows what would change checkbox
__limit__ The hosts the playbook runs on text or enum
__tags__ The tags to run text or enum
__inventory__ The inventory enum
__playbook__, __template__ The playbook, or the AWX / AAP template enum

For example, a form that offers a dry run and a host limit:

fields:
  - name: __check__
    type: checkbox
    label: Dry run (check mode)
  - name: __limit__
    type: text
    label: Limit to these hosts

The server only accepts these names from a form that declares them as fields, so a launch from the API cannot add them on its own. The properties they override are described with Ansible forms and AWX forms.

What can stop a launch

A launch does not always become a running job straight away:

  • Invalid fields : the form is not submitted, and each field that fails its validation shows why.
  • Launch validation : with launch validation set to enforce, the server checks the values again and refuses a launch that breaks the form’s rules.
  • Approval : a form with an approval point creates the job, which then waits in status approve; see Approve or reject a job.

When the job ends, the form’s notifications send their mails and channel messages, and its job status actions run.

Other ways to start a job

A form can also start a job without a person pressing Submit:

Started by How Page
Run later or a cron schedule Run later (one-time) or Schedule (recurring) next to Submit Schedules
A script or a pipeline POST /api/v2/job with an API token REST API jobs
An AI agent The MCP server’s launch_job tool MCP tools
A conversation The chat assistant fills in the form and launches it Chat assistant
An earlier job Relaunch, below Relaunch a job

Abort a job

Abort in the row’s menu (⋮) of the list, or Abort job on the job’s page, stops a job with status running. After you confirm, AnsibleForms marks the job for abort:

  • ansible: the RTE stops the playbook process (with all its workers), and the job ends as aborted with ... was aborted by the operator. A job still waiting for a free RTE is aborted before it starts.
  • A template job (AWX, AAP, Ascender, Semaphore, Rundeck, Jenkins): AnsibleForms asks the runner to cancel or stop the job, and the job ends as aborted. When the runner refuses, the output shows Abort request denied, followed by reverting abort request, and the job keeps running. A Jenkins build still in the queue is taken out of it.
  • workflow: the running node jobs are aborted and nothing more starts (see Running a workflow).
  • multistep: the steps that have not started yet are skipped (skipping: [Abort is requested]), and the main job ends as aborted. A step that is already running is a job of its own: open it and abort it to stop it as well.

You can abort your own jobs; an admin, or from 7.3.0 a user whose role sets manageAllJobs, can abort any job. showAllJobLogs lets a user see other users’ jobs, not abort them.

Relaunch a job

Relaunch in the row’s menu (⋮) of the list, or Relaunch job on the job’s page, starts a new job from a finished one. It is offered on any job that is neither running nor waiting for approval, to users whose role sets the allowJobRelaunch role option.

The dialog offers:

  • Relaunch: runs the job again with the values it ran with, as a new job under your name.
  • Verbose mode: relaunches in verbose mode; shown with the allowVerboseMode role option.
  • Edit values before relaunching, then Edit & relaunch: opens the form pre-filled with the job’s values, so you can change them before you submit.

A relaunch also requires the form to allow it (allowRelaunch, true by default) and the job to be your own, unless you are an admin or, from 7.3.0, have manageAllJobs; showAllJobLogs, which relaunched any job up to 7.2, no longer does. How a relaunch is checked against the form’s rules, and why a form with a password field may refuse it, is described in Relaunching.

Relaunch with pre-filled data

Edit & relaunch opens the form with the prefillJobId URL parameter, which you can also use in a link of your own:

https://af.example.com/form?form=New%20Virtual%20Machine&prefillJobId=61

The form loads the field values stored with job 61 and shows Form pre-filled with data from previous job #61. Submitting it starts a new job, checked like any other launch. The pre-fill follows the same rules as a relaunch:

  • Password fields are never stored, so they are never pre-filled: enter them again. Constants are not stored either.
  • The allowJobRelaunch role option is required, and the job must be your own (or you are an admin or have manageAllJobs).
  • A form with allowRelaunch: false cannot be relaunched or pre-filled:
- name: New Virtual Machine
  type: ansible
  playbook: create-vm.yaml
  allowRelaunch: false

A job from before the field values were stored cannot be pre-filled, and the form shows an error instead:

No saved form data found for job <id>. This job may have been created before the relaunch feature was enabled.

Approve or reject a job

A job with an approval point stops in status approve and waits. It is listed on the Jobs page of its approvers, the users with one of the approval’s roles, so they can find it; from 7.3.0 other users no longer see it.

Review approval is offered to admins and to users who have one of the approval’s roles: a click on the job’s row, Review approval in the row menu, or the Review approval button on the job’s page. The dialog shows the approval’s message, with the job’s values filled in (or a generic line without one), and the form, the job id, who launched it and when, with a link to the job; Reject and Approve answer it:

  • Approve: the job continues and its status returns to running.
  • Reject: the job ends as rejected, and its output records rejected by <username>.

A job waiting for approval cannot be relaunched or deleted from the Jobs page; approve or reject it first.

From 7.3.0 the user who launched a job cannot approve it, so a second person always looks at it, though they can still reject it to withdraw it. An admin can always approve, their own jobs included. A form whose approval point sets allowSelf: true lets its launcher approve their own job too.

Delete a job

Delete in the row’s menu (⋮) of the list, or Delete job on the job’s page, deletes a job with its output after you confirm. Deleting a multistep job deletes its steps too. To delete several jobs at once, tick them in the list’s first column and click Delete (n) above it.

You can delete your own jobs. Admins and, from 7.3.0, users with the manageAllJobs role option can delete any job; showAllJobLogs no longer can. A role that sets allowJobDeletion: false deletes no job at all, not even its own, so the job history stays whole. On the job’s page the button is hidden while the job is running or aborting (except for admins and manageAllJobs) and while it waits for approval; in the list, the menu entry and the checkbox are greyed out for a job you cannot delete.