TaskExecutions
Introduction
TaskExecutions 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.
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 Definition
Alias
taskExecution
Relations
Computed Properties
achieved_points
- Calculated achieved points from TaskProgressFields.max_points
- Calculated maximum achievable points from TaskProgressFields.
Traits
Sortable
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 by DateRange
To get a list of TaskExecutions in a DateRange, create a GET request to:
/api/tasks-2/executions?period_start={StartDate}&period_end={EndDate}
.
Example Request
Example Response
Count
To get a count of all tasks for the current user, create a GET request to:
/api/tasks-2/executions/count
.
Show
To show a TaskExecution, create a GET request to:
/api/tasks-2/executions/{id}
.
Example Request
Example Response
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/executions/{id}/progress/
The request must have a JSON body with the following keys:
Keys with *
are required.
Advanced Key-Specifications
field-key
- This represents the field to save a value for. Has to be a validkey
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
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/executions/{id}/progress/finish
The request must have a JSON body with the following keys:
Keys with *
are required.
Advanced Key-Specifications
field-key
- This represents the field to save a value for. Has to be a validkey
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_informationdelayed_reason
- Required if the TaskStatus isin_progress_delayed
Deny
This will set the task status to denied
.
To deny a task, create a PUT request to:
/api/tasks-2/executions/{id}/deny/
The request must have a JSON body with the following keys:
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 POST request to:
/api/tasks-2/executions/{id}/reset/
Update state
To update the state of a task, create a PUT request to:
/api/tasks-2/executions/{id}/status/
The request must have a JSON body with the following keys:
Keys with *
are required.
Advanced Key-Specifications
task_status_id
- Has to be a valid `task status identifier.
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