diff --git a/docs/reference/pages/model_reference.rst b/docs/reference/pages/model_reference.rst index a37ca6b2b9..89f3ad8238 100644 --- a/docs/reference/pages/model_reference.rst +++ b/docs/reference/pages/model_reference.rst @@ -481,3 +481,288 @@ Database fields .. attribute:: sort_order (number) + + +``Workflow`` +============ + +Workflows represent sequences of tasks which much be approved for an action to be performed on a page - typically publication. + +Database fields +~~~~~~~~~~~~~~~ + +.. class:: Workflow + + .. attribute:: name + + (text) + + Human-readable name of the workflow. + + .. attribute:: active + + (boolean) + + Whether or not the workflow is active: active workflows can be added to pages, and started. Inactive workflows cannot. + + +Methods and properties +~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: Workflow + + .. automethod:: start + + .. autoattribute:: tasks + + .. automethod:: deactivate + + +``WorkflowState`` +================= + +Workflow states represent the status of a started workflow on a page. + +Database fields +~~~~~~~~~~~~~~~ + +.. class:: WorkflowState + + .. attribute:: page + + (foreign key to ``Page``) + + The page on which the workflow has been started + + .. attribute:: workflow + + (foreign key to ``Workflow``) + + The workflow whose state the ``WorkflowState`` represents + + .. attribute:: status + + (text) + + The current status of the workflow (options are ``WorkflowState.STATUS_CHOICES``) + + .. attribute:: created_at + + (date/time) + + When this instance of ``WorkflowState`` was created - when the workflow was started + + .. attribute:: requested_by + + (foreign key to user model) + + The user who started this workflow + + .. attribute:: current_task_state + + (foreign key to ``TaskState``) + + The ``TaskState`` model for the task the workflow is currently at: either completing (if in progress) or the final task state (if finished) + +Methods and properties +~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: WorkflowState + + .. attribute:: STATUS_CHOICES + + A tuple of the possible options for the ``status`` field, and their verbose names. Options are ``STATUS_IN_PROGRESS``, ``STATUS_APPROVED``, + ``STATUS_CANCELLED`` and ``STATUS_REJECTED``. + + .. automethod:: update + + .. automethod:: get_next_task + + .. automethod:: cancel + + .. automethod:: finish + + .. automethod:: copy_approved_task_states_to_revision + + +``Task`` +======== + +Tasks represent stages in a workflow which must be approved for the workflow to complete successfully. + +Database fields +~~~~~~~~~~~~~~~ + +.. class:: Task + + .. attribute:: name + + (text) + + Human-readable name of the task. + + .. attribute:: active + + (boolean) + + Whether or not the task is active: active workflows can be added to workflows, and started. Inactive workflows cannot, and are skipped when in + an existing workflow. + + .. attribute:: content_type + + (foreign key to ``django.contrib.contenttypes.models.ContentType``) + + A foreign key to the :class:`~django.contrib.contenttypes.models.ContentType` object that represents the specific model of this task. + + +Methods and properties +~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: Task + + .. attribute:: task_state_class + + The specific task state class to generate to store state information for this task. If not specified, this will be ``TaskState``. + + .. automethod:: get_verbose_name + + .. automethod:: specific + + .. automethod:: start + + .. automethod:: on_action + + .. automethod:: user_can_access_editor + + .. automethod:: user_can_lock + + .. automethod:: user_can_unlock + + .. automethod:: get_actions + + .. automethod:: get_task_states_user_can_moderate + + .. automethod:: deactivate + + +``TaskState`` +============= + +Task states store state information about the progress of a task on a particular page revision. + +Database fields +~~~~~~~~~~~~~~~ + +.. class:: TaskState + + .. attribute:: workflow_state + + (foreign key to ``WorkflowState``) + + The workflow state which started this task state. + + .. attribute:: page revision + + (foreign key to ``PageRevision``) + + Whether or not the task is active: active workflows can be added to workflows, and started. Inactive workflows cannot, and are skipped when in + an existing workflow. + + .. attribute:: task + + (foreign key to ``Task``) + + The task that this task state is storing state information for. + + .. attribute:: status + + (text) + + The completion status of the task on this revision. Options are available in ``TaskState.STATUS_CHOICES``) + + .. attribute:: content_type + + (foreign key to ``django.contrib.contenttypes.models.ContentType``) + + A foreign key to the :class:`~django.contrib.contenttypes.models.ContentType` object that represents the specific model of this task. + + .. attribute:: started_at + + (date/time) + + When this task state was created. + + .. attribute:: finished_at + + (date/time) + + When this task state was cancelled, rejected, or approved. + + +Methods and properties +~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: TaskState + + .. attribute:: STATUS_CHOICES + + A tuple of the possible options for the ``status`` field, and their verbose names. Options are ``STATUS_IN_PROGRESS``, ``STATUS_APPROVED``, + ``STATUS_CANCELLED``, ``STATUS_REJECTED`` and ``STATUS_SKIPPED``. + + .. attribute:: exclude_fields_in_copy + + A list of fields not to copy when the ``TaskState.copy()`` method is called. + + .. automethod:: specific + + .. automethod:: approve + + .. automethod:: reject + + .. automethod:: task_type_started_at + + .. automethod:: cancel + + .. automethod:: copy + +``WorkflowTask`` +================ + +Represents the ordering of a task in a specific workflow. + +Database fields +~~~~~~~~~~~~~~~ + +.. class:: WorkflowTask + + .. attribute:: workflow + + (foreign key to ``Workflow``) + + .. attribute:: task + + (foreign key to ``Task``) + + .. attribute:: sort_order + + (number) + + The ordering of the task in the workflow. + +``WorkflowPage`` +================ + +Represents the assignment of a workflow to a page and its descendants. + +Database fields +~~~~~~~~~~~~~~~ + +.. class:: WorkflowPage + + .. attribute:: workflow + + (foreign key to ``Workflow``) + + .. attribute:: page + + (foreign key to ``Page``)