Zum Hauptinhalt springen

Tasks

Tasks provide a shared backlog for work such as contacting a customer or inspecting equipment. A task has a title, open or done status, an optional user assignee, and zero or more record links. A Task may also require a human response through its optional interaction. These Tasks appear in the same backlog and filters as ordinary work.

Each task has an immutable, server-assigned positive sequence number. REST and MCP responses expose natural_id as a string, including the definition's current optional natural_id_key prefix: "INS-123", or "123" without a prefix. Do not add the prefix again on the client. Numbers are unique within a tenant and shared across all task types, including workflow questions. They are never reused after deletion; gaps are permitted. The UUID id continues to identify API resources and relationships. Create and update requests cannot choose or change the number. Interleaved definitions might display INS-41, VIS-42, INS-43: prefixes share the same numeric sequence. Changing or clearing a prefix changes subsequent representations without changing record UUIDs, numbers, versions or timestamps. There are no per-definition sequence starts or resets. The numeric natural_id filter and numeric sorting use the underlying number. GraphQL also exposes the formatted string. Task webhook snapshots retain their numeric contract.

Task types​

The execution_type discriminator identifies the execution behavior of a task response. type identifies its concrete definition: a built-in name or a custom definition slug:

Execution typeWork
simpleOrdinary work completed by marking the task done
visitWork at a required location, exposed through visit.location
workflow_free_text_questionA workflow question answered with free text
workflow_single_choice_questionA workflow question answered by selecting one option

Creation requires one type selector: simple, visit, a custom Task definition slug, or a concrete Task definition UUID. The server resolves the definition and derives its execution type. A Visit requires visit.location; a Simple Task rejects a non-null visit. Missing, unknown, wrong-family or workflow-question selectors return field-level 422 errors at #/type. Do not send definition_id or execution_type on instance creation. Workflows create question tasks and their interactions. Response schemas use oneOf so clients can narrow by execution_type before reading variant-specific fields.

For a visit task, include its location:

{
"type": "visit",
"title": "Inspect the rooftop HVAC unit",
"visit": {"location": {"lat": 48.2082, "lon": 16.3738}}
}

Visit locations use the same fixed value fields as custom-object locations: lat, lon, street, street_additional, city, region, postal_code, country_code, address_label, and located_at. Supply both coordinates, or at least street and country_code. A label alone is not a destination. An address-only visit is valid; map markers and distance estimates need coordinates. Tourfold does not silently geocode addresses.

Copy the complete fixed value between a record's location attribute and visit.location without renaming fields. For a tracked source, read the resolved value and remove tracking before copying; an unresolved source needs a concrete address or coordinates first. Preserve located_at as the source observation time. A copy is independent of later source movement.

Task PATCH merges nested location fields: omitted fields stay unchanged and explicit null clears a field. The resulting location must remain complete. For example, changing only lat preserves lon and the full address. Clear both coordinates together when switching to an address-only value. Custom-object writes instead replace a supplied location attribute as a whole. To copy over an existing Task location, also explicitly clear destination fields absent from the source; the first-party editor does this when submitting its complete location value.

Tour membership is managed through a separate tour task assignment. It does not add tour fields to the task or replace its individual assignee.

CRUD​

MethodPathResult
POST/api/v2/tasks201, complete task and absolute Location header
GET/api/v2/tasks200, items and page metadata
GET/api/v2/tasks/{task_id}200, complete task
PATCH/api/v2/tasks/{task_id}200, complete updated task
DELETE/api/v2/tasks/{task_id}204, no body

Create requires a definition selector in type and a nonblank title of at most 255 characters:

{"type":"simple","title":"Inspect the rooftop HVAC unit"}

The server assigns a UUID and a task number, defaults status to open, and returns linked_records: []. Ordinary creation does not add an interaction. An unassigned task omits assignee_user_id. Tasks are scoped to the authenticated tenant.

Use Content-Type: application/merge-patch+json for updates (application/json is also accepted):

{"status":"done","lock_version":0}

Omitted fields remain unchanged. assignee_user_id: null clears the assignee. Null title, status, record arrays and roles are rejected. linked_records replaces the entire array; [] clears it. A supplied stale lock_version returns 409; omitted or null skips this precondition. An unchanged patch preserves the version and produces no update event.

A Task assigned to a finished Tour cannot be updated or deleted: these operations return 409 tours/finished. Deleting an ordinary Task in an editable Tour removes its assignment in the same transaction; deleting the last Task at an automatic Stop removes that Stop too. Task and Stop locations are independent snapshots: editing either one does not update the other.

Task definitions​

GET /api/v2/definitions/tasks lists the four protected system definitions first: Simple, Visit, single-choice question and free-text question. Tenant definitions follow, ordered by slug and UUID. Use page, size (1–100) and optional search; search matches slugs and localized names before pagination. The internal Task family root is not a selectable definition.

Read with tasks:read or schemas:write; author with schemas:write. Schema administration does not grant Task record access. A caller with only tasks:write can create a Task with a known definition ID without gaining definition browsing permission.

Method and path, relative to /api/v2Result
GET /definitions/tasks/{definition_ref}200, concrete definition by UUID or slug
POST /definitions/tasks201, complete definition and absolute Location
PATCH /definitions/tasks/{definition_ref}200, merge names, slug, optional prefix or presentation
PUT /definitions/tasks/{definition_ref}200, replace the full authored schema
POST /definitions/tasks/{definition_ref}/attributes201, updated definition; Location identifies that definition
PATCH /definitions/tasks/{definition_ref}/attributes/{attribute_ref}200, merge one authored attribute
DELETE /definitions/tasks/{definition_ref}/attributes/{attribute_ref}200, updated definition
DELETE /definitions/tasks/{definition_ref}204, delete an unused tenant definition

Both references accept UUIDs or slugs within the routed Task definition family. These operations are exposed only under /api/v2, with matching task_definitions_* / task_attributes_* MCP tools. Lists place the four system definitions first, followed by custom definitions ordered by slug, then ID.

Create a Simple-based inspection definition:

{
"slug": "inspection",
"natural_id_key": "INS",
"execution_type": "simple",
"name": {"en": {"singular": "Inspection", "plural": "Inspections"}},
"attributes": [{"slug": "notes", "type": "text", "name": {"en": "Notes"}}]
}

Only system Simple and Visit have is_extendable: true. Question bases and tenant definitions cannot be extended. execution_type is immutable. Responses use the canonical definition representation, including resource_type: "task", icon/color, map_marker_fields, managed_by (tenant, system, or plugin), optional managed_by_plugin, schema_policy, and one effective attributes list containing native and authored fields. Native fields have is_system_managed: true; is_readonly independently describes value writability. Structured native fields use the response-only type json. Use the Task request schemas for their value requirements. See shared definition metadata. Native fields, the numeric allocator and display templates cannot be redefined by a custom schema. Relationships may target Objects or the Vehicle family; Task targets and reverse fields are unsupported.

PUT requires slug, execution_type, name and attributes. Omitted attributes fail validation; [] deliberately removes authored fields subject to usage protection. Retain field/choice IDs to preserve identity. PATCH omission preserves values; root name: null and slug: null are rejected. A null language removes its translation, but at least one localized name must remain. Both writes accept an optional lock_version; a stale value returns 409 resource-conflict.

natural_id_key is optional on every concrete system/custom definition. A supplied prefix contains 1–16 uppercase letters/digits, starts with a letter and is unique across Object, Vehicle and Task definitions in the workspace. Blank strings are invalid. PATCH omission preserves the prefix; {"natural_id_key": null} clears it. PUT omission or null also clears it. GET omits the key when unconfigured. Prefix and presentation PATCH are allowed on system definitions and definitions already in use.

A definition is in use when a Task (including completed Tasks) or stored configuration references it. While used, labels, descriptions, presentation order and the optional prefix may change. Optional additions are allowed only without new indexing or uniqueness obligations; defaults apply to new Tasks without backfilling existing ones. Structural changes, required additions and deletion return 409 tasks/definition-in-use. Its data.definition_id identifies the blocked definition and data.usage_examples includes bounded examples of blocking templates and Workflow versions the caller may read. Retained publications remain blocking after Workflow deletion; retirement/purge is separate from deleting a Workflow. An empty examples list does not mean the definition is unused. System definitions return 409 definitions/schema-locked on schema/name writes; their optional prefix is the sole editable metadata field.

Deleting an Object or Vehicle selected by a required Task relationship returns 409 tasks/required-target-in-use, even after Task completion or when other targets remain selected. Saved Tour-template and retained Workflow inputs also protect required Tag, Skill and tracked-location references, even before any Task has been created. Optional references deleted later are removed from editable copies and execution inputs; immutable Workflow publications keep their original values. Optional references are cleared atomically and produce one owning Task or template revision/update event, including when the same record also has an ordinary Task link.

Definition changes emit task_definition.created, task_definition.updated and task_definition.deleted. Created and updated events carry the frozen definition representation; updates also include previous_attributes for changed fields. Deleted events carry the definition ID. No-op edits emit no event.

Definition Settings is available to authorized generic workspaces and is hidden by BW/ÖAMTC. The operational Task editor, Tour-template item editor and typed Workflow authoring support custom definitions. Question Tasks remain Workflow-only.

Custom Task values​

Value-validation errors use JSON pointers such as #/data/customer or #/data/rating, matching the submitted custom attribute slug. Map these errors to the corresponding custom field.

Every Task response includes its immutable definition_id, canonical type (built-in name or custom slug), and execution_type. Creation selects the definition through type alone; this field is required. UUID input is normalized to the canonical name in responses. The definition and execution behavior cannot change after creation. Workflow questions always use their protected system definition and do not accept custom values. Read and author definitions through the Task definition endpoints. Definition creation keeps slug, name, and execution_type; it does not accept an instance type selector. Built-in execution names are reserved as custom definition slugs.

Filter instances with GET /api/v2/tasks?type=vehicle_inspections (slug, UUID or built-in name). Use execution_type=visit to select all Visit tasks across definitions. The existing definition_id filter remains available; if combined with type, both must identify the same definition.

Simple and Visit responses include data, keyed by custom attribute slug. To-many relationships use nested {items, page} collections with at most 50 compact record views and full totals; later pages are available at GET /api/v2/tasks/{task_id}/related/{attribute_ref}. System Tasks return empty data objects. Custom attributes cannot override native fields such as title or visit.

{
"type": "vehicle_inspections",
"title": "Inspect delivery van",
"visit": {"location": {"lat": 48.2, "lon": 16.3}},
"data": {"serial": "INSPECT-1", "passed": false}
}

Creation applies defaults to omitted custom fields and validates required values. PATCH accepts a partial data object: omitted attributes stay unchanged, an attribute's explicit null clears it when allowed, and {} preserves every value. data: null, unknown attributes and writes to read-only attributes return 422. Completion without a custom value patch does not introduce a second required-field validation gate.

Native fields and custom values commit atomically. A real change advances lock_version once and emits one update event, including for a custom-field-only edit. An unchanged patch emits no event. The same optional version check and finished-Tour restrictions apply.

Relationship previews require target read permission. To load the complete linked collection, use GET /api/v2/tasks/{task_id}/related/{attribute_ref}?page=0&size=20, where attribute_ref is the attribute UUID or slug. It returns canonical target records in {items, page}, ordered by UUID, and requires both Task and target read permission before returning records or totals. Page size is 1–100. The corresponding MCP tool is tasks_related_list.

Human interactions​

A workflow approval creates a Task with a single_choice interaction. The interaction has its own UUID, distinct from the Task ID, and freezes the question and its options when created. Task detail contains the information needed to render and answer it; no workflow graph request or workflow authoring permission is needed. Ordinary Task creation and updates cannot inject an interaction.

{
"id": "54b31ce1-7b2d-4423-97e1-72eaf344e251",
"natural_id": "123",
"title": "Approve roadside assistance",
"status": "open",
"lock_version": 0,
"interaction": {
"id": "fbab0b62-fbbb-4731-86cf-dba29b4ab985",
"type": "single_choice",
"status": "pending",
"prompt": "Approve roadside assistance",
"options": [
{"id": "approved", "label": "Approve"},
{"id": "rejected", "label": "Reject"}
],
"created_at": "2026-09-09T10:00:00Z",
"expires_at": "2026-09-16T10:00:00Z"
}
}

Answer with POST /api/v2/tasks/{task_id}/interaction/answer:

{
"type": "single_choice",
"interaction_id": "fbab0b62-fbbb-4731-86cf-dba29b4ab985",
"option_id": "approved",
"comment": "The customer confirmed the details.",
"lock_version": 0
}

The required type is single_choice or free_text and must match the interaction. The required interaction_id must identify this Task's interaction. A single-choice answer selects one published option_id; an optional comment must be nonblank and at most 2000 characters. A type: free_text answer instead requires nonblank text within its declared bound. Do not combine text with an option or choice comment. Invalid field values and incompatible payloads return 422.

The response is 200 with the updated Task: status done, interaction status answered, and the accepted response, respondent and time. The answer, Task completion and durable continuation intent commit atomically. A workflow resumes asynchronously from the committed response.

A repeated identical answer by the same currently authorized human returns the accepted result, even with the original lock_version. A different answer or respondent, the wrong interaction ID, a stale supplied version on a pending interaction, expiry, or cancellation returns 409. Expired and cancelled interactions remain distinguishable from answered interactions; a late response cannot reopen them.

Answering requires an active human with tasks:write. API-only users and service accounts cannot answer. Task grants remain tenant-wide: assignment identifies responsibility and does not restrict answering to that assignee. Reading requires tasks:read.

An authenticated caller who does not qualify as an active human receives 403 with type https://problems.tourfold.com/tasks/interaction-human-required and data.reason: not_member. This denial does not include data.required_grants; adding grants cannot make an API-only user or service account a human respondent. A caller missing tasks:write receives the usual 403 access-denied with data.reason: missing_grant and data.required_grants: ["tasks:write"]. Requests without usable credentials receive the shared 401 authentication-required response and WWW-Authenticate challenge.

Ordinary PATCH {"status":"done"} cannot supply a required answer, and PATCH {"status":"open"} cannot reopen it. Both return 409 resource-conflict, including when the requested status already matches. Deletion also returns 409 after the interaction closes, so the accepted response remains traceable.

The Task's title and record context cannot be changed through Task CRUD. Reassignment and clearing assignee_user_id remain available with the usual optional lock_version check. An unchanged title or record-link array may be retained in the same patch. Automatic record/object deletion still removes obsolete Task links; the interaction retains its frozen question.

See Workflow approvals for publication, timeout and branch behavior.

Reading tasks requires tasks:read; creating, editing or deleting them requires tasks:write. These grants apply across the tenant, independently of linked-record permissions. Admin and Owner roles receive both grants by default; other roles can receive them through normal role management.

The same operations are available as tasks_list, tasks_get, tasks_create, tasks_update and tasks_delete MCP tools. tasks_interaction_answer mirrors the answer action and preserves its active-human requirement. All are subject to the same Task grants and the workspace's MCP controls.

Each link contains object_id, record_id and an optional role such as customer or equipment. Roles are lowercase snake_case slugs, at most 64 characters. Multiple records may share a role; one record may have different roles. Duplicate object/record/role combinations are rejected. Roles describe the task's links and do not define custom-object relationship attributes.

New links require an existing, readable record. Custom-object links require objects:records:read and the object type's access policy; vehicle links require vehicle-read permission and must name the vehicle's concrete definition in object_id. Other read-only built-in system record types remain unsupported.

Restricted links remain in task responses, retaining IDs and role with is_accessible: false. They omit display_name; clients should display “You don't have access to this record”. Accessible links include is_accessible: true and the current display name. A task editor can retain or remove an existing restricted link and edit its role without gaining access to the record's contents.

Deleting a record removes its links from tasks while preserving the tasks and their other links. Deleting an object or vehicle definition performs the same cleanup for all its records. This cleanup commits atomically with deletion and increments each affected task's version once. Object renames preserve stable links.

Filtering the backlog​

Filters combine with AND:

  • search: case-insensitive literal title substring or an exact number such as 123 or Task-123; blank is rejected.
  • natural_id: exact positive task number.
  • status: open or done; omitted includes both.
  • definition_id: exact concrete Task definition UUID.
  • type: one concrete definition, selected by built-in name, custom slug, or definition UUID.
  • execution_type: execution behavior, including every custom definition with that behavior.
  • has_visit: true for Visit Tasks and false for other types.
  • assignee_user_id: exact tenant user UUID; omitted includes assigned and unassigned tasks.
  • object_id and record_id: supply together using the Object or concrete Vehicle definition UUID and a readable record UUID. Matches ad hoc links (regardless of role) and named custom relationships, including relationships targeting the Vehicle family. The target resource's own read policy applies. A Task matching both kinds of link appears only once in the page and total.

“My tasks” uses the current user's UUID as assignee_user_id. Pagination uses page (default 0) and size (default 20, maximum 100). sort accepts one field:asc or field:desc pair for natural_id, created_at, updated_at, title, status or id; a bare field means ascending order. The default is created_at:desc. An ID tie-breaker keeps pages stable, and multiple matching links never duplicate tasks or inflate totals.

Lifecycle events​

Subscribe to task.created, task.updated and task.deleted through the existing webhook API. Updates include old values of changed fields in data.previous_attributes. Automatic record-link cleanup produces a task update too. Webhook references contain only IDs and roles; caller-specific record names and access flags are not persisted in webhook payloads. Created and updated payloads include definition_id; Simple and Visit payloads also include frozen custom data. Custom reference fields contain complete sorted ID arrays, independent of the writer's read permissions. Named locations retain their stored fixed value or tracking reference. When custom values change, previous_attributes.data contains the previous custom-value snapshot. Created and updated Task payloads include interaction metadata when present. Accepting an answer closes the Task and emits the normal task.updated lifecycle event in the same transaction. Answer metadata includes the selected option, respondent and answer time. Free-text answers and comments are available through Task detail and are excluded from webhook payloads, including previous_attributes.

Native workflows can read Tasks, create visits and copy complete locations to or from custom-object records. See Workflow location copying.