.. task:: Confirm

Confirm task
------------

This :ref:`wait task <task-type-wait>` blocks a workflow until a user
confirms that the workflow can continue.
Users who can confirm are either the creator of the work request/parent
workflow, or owners of the workspace.
This task is equivalent to a confirmation prompt in a traditional user
interface.

The ``task_data`` for this task may contain the following keys:

* ``auto_confirm_if_no_failure`` (boolean, defaults to False): when this
  parameter is set, the wait task is immediately marked as successful if all
  its dependencies are successful. It is useful to generate a confirmation
  prompt only when something has gone wrong and we want to offer the
  possibility to recover from it, instead of aborting the rest of the
  dependency chain.
* ``deny_action`` (string, defaults to 'abort-workflow'): allowed values are
  'fail', 'abort', 'abort-workflow'. For 'fail', the wait work request is
  completed with result set to FAILURE. For 'abort', the wait work request
  is "terminated" with status set to ABORTED. For 'abort-workflow', the root
  workflow is aborted.
* ``confirm_label`` (string, defaults to "Continue the workflow"): the label
  to show in the "Confirm" button
* ``deny_label`` (string, defaults to "Abort the workflow"): the label to
  show in the "Deny" button.

UI changes
~~~~~~~~~~

When showing a running :task:`Confirm` work request, the web UI shows
two buttons with the labels provided in the task data. It also shows
a "Comment" field where the user can input some text justifying the
choice made.

When one of the buttons is clicked, it is equivalent to calling
the ``confirm`` API view described below, with either ``confirm: True``
or ``confirm: False`` depending on the button clicked.

When showing a completed/aborted work request, the web UI displays:

* the user who took the decision
* the actual decision taken (show the label of the button "clicked"?)
* the timestamp of the confirmation
* the action performed as a result

API changes
~~~~~~~~~~~

A new ``/api/1.0/work-request/<int:work_request_id>/confirm/`` POST view
allows handling the new :task:`Confirm` wait task.  The view takes two
parameters:

* ``confirm`` (boolean, defaults to True): True indicates a confirmation,
  False a denial
* ``comment`` (string, defaults to empty string): a textual message
  justifying the decision

The view works as follows:

* it checks that the work request is ``WAIT/Confirm`` and is running, and
  otherwise returns HTTP 400
* it checks that the requesting user has the permissions to confirm (creator
  or workspace owner), and otherwise returns HTTP 403
* when ``confirm`` is True, it terminates the work request with
  status=COMPLETED and result=SUCCESS
* when ``confirm`` is False, the behaviour is dictated by the
  ``deny_action`` task data (see above)
* the ``output_data`` field of the work request is updated (so that
  the web UI can show information about who confirmed what & when, etc.)
* it returns HTTP 200