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

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

• Restrictable
• 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

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/tasks-2/executions?period_start=2021-02-16+00:00:00&period_end=2021-02-16+23:59:59', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);

Example Response

[
    {
        "id": 155,
        "user_id": 144,
        "department_id": null,
        "last_activity_user_id": 144,
        "parent_id": null,
        "task_assignment_id": 80,
        "task_template_id": 31,
        "task_status_id": "done",
        "for_execution_date": null,
        "started_at": "2020-07-16 14:44:05",
        "ended_at": "2020-07-16 14:44:05",
        "deny_reason": null,
        "delayed_reason": null,
        "created_at": "2020-07-16 14:44:03",
        "updated_at": "2020-07-16 14:44:05",
        "deleted_at": null,
        "hash": "eyJ1aWQiOjE0NCwiZGlkIjpudWxsLCJ0YWlkIjo4MCwidHRpZCI6MzEsImZlZCI6bnVsbH0=",
        "execution_start_time": null,
        "execution_end_time": null,
        "visibility_start_time": null,
        "achieved_points": 0,
        "max_points": 0,
        "children": [],
        "task_assignment": {
            "id": 80,
            "parent_id": null,
            "inherit_parent_values": false,
            "revision_id": null,
            "origin_id": null,
            "folder_id": null,
            "title": "TaskAssignment-1",
            "description": null,
            "task_template_id": 31,
            "task_template_composition_id": null,
            "creator_user_id": 144,
            "assign_mode": "one_of",
            "priority": null,
            "start_date": null,
            "start_time": null,
            "show_before_interval": null,
            "executable_before_interval": null,
            "executable_after_interval": null,
            "interval": null,
            "interval_end": null,
            "earliest_visibility_date": "2020-07-16 14:43:10",
            "latest_execution_date": null,
            "user_confirmation_required": true,
            "dispatched_by_system": 0,
            "dispatchable_id": null,
            "dispatchable_type": null,
            "trigger_id": null,
            "active": true,
            "always_executable": false,
            "sort_number": 55,
            "created_at": "2020-07-16 14:43:10",
            "updated_at": "2021-01-01 02:15:35",
            "deleted_at": null
        },
        "task_progress_fields": [],
        "task_template": {
            "id": 31,
            "title": "Template-1",
            "description": null,
            "parent_id": null,
            "revision_id": null,
            "origin_id": null,
            "folder_id": null,
            "sort_number": 38,
            "user_id": 144,
            "created_at": "2020-07-16 14:43:08",
            "updated_at": "2020-07-16 14:43:08",
            "deleted_at": null,
            "grade_scale": null,
            "tour_enabled": true,
            "form_fields": []
        }
    },
    ...
]

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

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/tasks-2/executions/{id}', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);

Example Response

{
  "id": 155,
  "user_id": 144,
  "department_id": null,
  "last_activity_user_id": 144,
  "parent_id": null,
  "task_assignment_id": 80,
  "task_template_id": 31,
  "task_status_id": "done",
  "for_execution_date": null,
  "started_at": "2020-07-16 14:44:05",
  "ended_at": "2020-07-16 14:44:05",
  "deny_reason": null,
  "delayed_reason": null,
  "created_at": "2020-07-16 14:44:03",
  "updated_at": "2020-07-16 14:44:05",
  "deleted_at": null,
  "hash": "eyJ1aWQiOjE0NCwiZGlkIjpudWxsLCJ0YWlkIjo4MCwidHRpZCI6MzEsImZlZCI6bnVsbH0=",
  "execution_start_time": null,
  "execution_end_time": null,
  "visibility_start_time": null,
  "achieved_points": 0,
  "max_points": 0,
  "children": [],
  "task_assignment": {
    "id": 80,
    "parent_id": null,
    "inherit_parent_values": false,
    "revision_id": null,
    "origin_id": null,
    "folder_id": null,
    "title": "TaskAssignment-1",
    "description": null,
    "task_template_id": 31,
    "task_template_composition_id": null,
    "creator_user_id": 144,
    "assign_mode": "one_of",
    "priority": null,
    "start_date": null,
    "start_time": null,
    "show_before_interval": null,
    "executable_before_interval": null,
    "executable_after_interval": null,
    "interval": null,
    "interval_end": null,
    "earliest_visibility_date": "2020-07-16 14:43:10",
    "latest_execution_date": null,
    "user_confirmation_required": true,
    "dispatched_by_system": 0,
    "dispatchable_id": null,
    "dispatchable_type": null,
    "trigger_id": null,
    "active": true,
    "always_executable": false,
    "sort_number": 55,
    "created_at": "2020-07-16 14:43:10",
    "updated_at": "2021-01-01 02:15:35",
    "deleted_at": null
  },
  "task_progress_fields": [],
  "task_template": {
    "id": 31,
    "title": "Template-1",
    "description": null,
    "parent_id": null,
    "revision_id": null,
    "origin_id": null,
    "folder_id": null,
    "sort_number": 38,
    "user_id": 144,
    "created_at": "2020-07-16 14:43:08",
    "updated_at": "2020-07-16 14:43:08",
    "deleted_at": null,
    "grade_scale": null,
    "tour_enabled": true,
    "form_fields": []
  }
}

Create

Create a new TaskExecution.

Definition

POST /api/tasks-2/executions

Request Keys

Key	Type	Default	Description
task_assignment_id *	integer	-	The ID of the TaskAssignment to create the TaskExecution for.
task_template_id *	integer	-	The ID of the TaskTemplate to use for the TaskExecution.
parent_id	integer	-	The ID of the parent TaskExecution when creating a child TaskExecution
task_status_id	string	open	The initial status for the TaskExecution.
for_execution_date	datetime	-	The execution date of the TaskExecution.

Keys with * are required.

Example Request

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/tasks-2/executions', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'task_assignment_id' => 1,
        'task_template_id' => 1
    ]
]);

Example Response

{
  "status": "success",
  "data": {
    "task_assignment_id": 1,
    "task_template_id": 1,
    "task_template_id": "open",
    "user_id": 1,
    "department_id": 1,
    "last_activity_user_id": null,
    "started_at": null,
    "ended_at": null,
    "updated_at": "2024-10-01 12:00:00",
    "created_at": "2024-10-01 12:00:00",
    "id": 1,
    "hash": "eyJ0ZWlkIjo1OTQyLCJ1aWQiOjQwLCJkaWQiOjksInBpZCI6bnVsbCwidGFpZCI6NTU4LCJ0dGlkIjoyMDMsImZlZCI6bnVsbH0="
  }
}

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:

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

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:

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/executions/{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 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:

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.

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.