HomeDocsWebsite

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

Traits

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

$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

$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

$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.

PreviousTaskAssignmentsNextTaskProgressFields

Last updated