.. _workflow-template:

WorkflowTemplate
================

The ``WorkflowTemplate`` model has (at least) the following fields:

* ``name``: a unique name given to the workflow within the workspace
* ``workspace``: a foreign key to the workspace containing the workflow
* ``task_name``: a name that refers back to the ``Workflow`` class to
  use to manage the execution of the workflow
* ``static_parameters``: JSON dict field representing the default values
  for workflows created from this template.
* ``runtime_parameters``: JSON field representing the range of
  configurable parameters for workflows created from this template.
* ``extra_groups``: permission checks within workflow instances created from
  this template will act as though their creator were a member of these
  additional groups
* ``restricted``: normally, anyone with the ``CONTRIBUTOR`` role on the
  containing workspace can start workflow instances from this template;
  workflow templates with ``restricted: True`` instead require the ``OWNER``
  role

``runtime_parameters`` values
-----------------------------

By default (``{}``) no parameters can be configured when starting a
workflow.

Parameters that should be configured can be listed in a JSON object,
with a list of permitted values, or the special value ``any``. For
example, this would allow any source artifact to be used for a build in
``sid``, ``forky``, or ``trixie``:

.. code-block:: yaml

   suite: ['sid', 'forky', 'trixie']
   source_artifact: 'any'

Only string parameters at the root level can have permitted values
specified. More complex objects can either be left out (not
configurable) or have their root level option listed as ``any`` (fully
configurable).

The special ``runtime_parameters`` value of ``'any'`` (a string, not a
dict) allows all parameters to be configured.

Workflow Creation
-----------------

The root ``WorkRequest`` of the workflow copies the following fields from
``WorkflowTemplate``:

* ``workspace``
* ``task_name``
* ``task_data``, combining the user-supplied data and the
  ``static_parameters``. The user-supplied data must comply with
  ``runtime_parameters``.
