Tasks

Introduction

Tasks represent a specific task a user or user group should execute. When creating a TaskAssignment with recurr configuration, the tasks will be created automatically.

All information which is reported for an execution such as TaskProgressStates or TaskProgressField information will be attached to a Task.

There will never be the need to create a task directly as it is always a result of TaskAssignments configuration and TaskTemplate information.

Note

Tasks are always subject of entity based permissions. Thus given, you're API user may not be able to alter every task's information.

Model & Relations

Namespace

Modules\Tasks\Entities\Task

Relations

Relation Key Type Relation Field(s)
TaskProgressFields taskProgressFields Has many task_progress_fields.task_id
TaskAssignment taskAssignment Belongs to task_assignment_id
TaskTemplate taskTemplate Belongs to task_template_id
TaskStatus taskStatus hasOne tasks_status_id
User lastActivityUser Belongs to last_activity_user_id
Task parent Belongs to parent_id
Tasks children Has many parent_id

Computed Properties

  • achieved_points - Calculated achieved points from TaskProgressFields
  • max_points - Calculated maximum achievable points from TaskProgressFields

Traits

  • Sortable
  • Restrictable

Task status indicators

A task can have the following states:

  • open
  • in_progress
  • in_progress_delayed
  • done
  • done_delayed
  • denied
  • missed

All _delayed states are determined by the api itself based on the calculated execution date.

The "done" state is, with one exception, only granted by the finish route if all necessary FormFields were passed.

If there are no FormFields defined for the tasks TaskTemplate, the "done" status can be granted through update-status route, too.

List

To get a list of tasks for the user, create a GET request to:

/api/tasks-2/.

Count

To get a count of all tasks for the current user, create a GET request to:

/api/tasks-2/count.

Get

To get a task, create a GET request to:

/api/tasks-2/{id}.

Progress

Will save all information passed according to the configured FormFields of the related TaskTemplate without applying any validation rules. When a FormField value is passed, there will be an according TaskProgressField created which holds information about the passed value. This is meant to be called when a user fills a FormField for a Task but is not finishing the execution yet.

To update the progress fields of a Task, create a PUT request to:

/api/tasks-2/{id}/progress/

The request must have a JSON body with the following keys:

Key Type Default Description
{field-key}* {fieldType} - Valid FieldKey defined on TaskTemplate
{field-key_additional_information} string - Additional information text for field key.

Keys with * are required.

Advanced Key-Specifications

  • field-key - This represents the field to save a value for. Has to be a valid key of a FormField related to the Tasks TaskTemplate. The type is determined from FormField definition. You can pass many fields and values at once.
  • field-key_additional_information - You can pass additional_information for every TaskProgressField. Just suffix the field-key with _additional_information

Note

The TaskStatus will be automatically set to in_progress or in_progress_delayed, respecting the time the request is received.

Finish

Will save all information passed for FormFields while applying all related FormFieldValidations. If validation doesn't fail, the information will be saved as TaskProgressFields and the task will be marked as finished.

To update the progress fields of a Task and finish it, create a PUT request to:

/api/tasks-2/{id}/progress/finish

The request must have a JSON body with the following keys:

Key Type Default Description
{field-key}* {fieldType} - Valid FieldKey defined on TaskTemplate
delayed_reason* string - Delayed reason as text.

Keys with * are required.

Advanced Key-Specifications

  • field-key - This represents the field to save a value for. Has to be a valid key of a FormField related to the Tasks TaskTemplate. The type and validation is determined from FormField definition. Thus given, all required FormFields have to be passed to finish a Task.
  • field-key_additional_information - You can pass additional_information for every TaskProgressField. Just suffix the field-key with _additional_information
  • delayed_reason - Required if the TaskStatus is in_progress_delayed

Deny

This will set the task status to denied.

To deny a task, create a PUT request to:

/api/tasks-2/{id}/deny/

The request must have a JSON body with the following keys:

Key Type Default Description
deny_reason* string - Reason for denying the task.

Keys with * are required.

Reset

Removes all attached information from given task and resets the status to in_progress.

To reset a task, create a PUT request to:

/api/tasks-2/{id}/reset/

Update state

To update the state of a task, create a PUT request to:

/api/tasks-2/{id}/status/

The request must have a JSON body with the following keys:

Key Type Default Description
task_status_id* string - The TaskStatus that should be set.

Keys with * are required.

Advanced Key-Specifications

  • task_status_id - Has to be a valid `task status identifier.

Note

You can only set the status "done" if there are no open child tasks and there are no FormFields defined for the Tasks TaskTemplate

If the task has a _delayed state, you must not set a status without _delayed suffix.

Last Updated: 10/14/2019