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

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": []
  }
}

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 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:

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:

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