Modifies an existing subtask of a task in a task plan. The update is partial: only what you send in the body is changed, and the rest of the subtask keeps its current value. One subtask is edited per request. To create subtasks use Create subtasks in a task of a task plan.
Add-onGeneral use — no specific add-on. The token must belong to a profile with edit permission on Tasks > Task plans.
PUT https://app.fracttal.com/api/tasks_subtasks/{id_subtask}Input parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id_subtask | integer | Yes (in the path) | Identifier of the subtask. It is returned in the id field of the response of Create subtasks in a task of a task plan. The task it belongs to is deduced from the subtask. |
Body parameters
Sent in JSON format. All of them are optional, but you must send at least one of the editable fields (id_task_form_item_type, description, task_form_item_group_description, id_unit, unit_description, dropdown_options, iterations, is_required or attachments_required).
| Parameter | Type | Required | Description |
|---|---|---|---|
id_task_form_item_type | integer | No | Subtask type, from 1 to 8: 1 Text, 2 Yes/No, 3 Number, 4 Check, 5 Meter reading, 6 GPS location, 7 List, 8 Date and time. |
description | text | No | Label or question of the subtask. It cannot be empty or contain only spaces. |
task_form_item_group_description | text | No | Name of the group the subtask belongs to (between 1 and 150 characters). It is matched by similarity against existing groups; if there is no match, the group is created. |
id_unit | integer | Conditional | Identifier of the unit of measure. Only applies to type 5 subtasks. It must exist among the company's units. |
unit_description | text | Conditional | Name of the unit of measure (maximum 50 characters). Only applies to type 5 subtasks. It is matched by similarity against existing units; if there is no match, the unit is created. |
dropdown_options | array of objects | Conditional | Options of the list. Only applies to type 7 subtasks. Minimum 2 elements. See the structure in the next table. |
iterations | object | No | Iterations in which the subtask takes part, in the format { "iteration_1": true, "iteration_2": false }. It is only taken into account in cyclical tasks. |
is_required | boolean | No | Indicates whether the subtask is mandatory. |
attachments_required | boolean | No | Indicates whether the subtask requires attachments. |
is_cyclical | boolean | No | Indicates whether the task is cyclical. If sent, it must match the task configuration; this service does not modify it. |
num_iterations | integer | No | Number of iterations of the task. If sent, it must be greater than 0 and match the task configuration; this service does not modify it. |
Structure of each element in dropdown_options:
| Parameter | Type | Required | Description |
|---|---|---|---|
description | text | Yes | Text of the option. It cannot be empty. |
Editing rules
- Type rules are applied on the subtask's effective type: the one you send in
id_task_form_item_typeor, if you do not send it, the one it already has.- When changing to type
7(List) you must senddropdown_optionswith at least 2 options.- When changing to type
5(Meter reading) you must sendid_unitorunit_description, unless the subtask already has a unit assigned.- If the task has linked assets and the subtask changes to type
5, the subtask is updated butmessageis returned asERROR_CONFIG_METERS_ASSETS: the meter of each asset still has to be configured from Fracttal.- When leaving type
7, the options of the subtask's list are removed.- When leaving type
5, the subtask's unit and the meters associated with it are removed.dropdown_optionsis only accepted on type7subtasks;id_unitandunit_descriptiononly on type5subtasks.iterationsis merged with the subtask's current iterations: only the iterations you send are changed. Eachiteration_nmust be between 1 and the number of iterations of the task. In a task that is not cyclical,iterationsis ignored.- A subtask from another company is treated the same as a non-existent one (
404).
Output parameters
| Parameter | Type | Description |
|---|---|---|
success | boolean | true if the subtask was updated. |
message | text | 200 when the operation succeeds, or ERROR_CONFIG_METERS_ASSETS if the subtask was updated but the meters of the linked assets still need to be configured. On error, it contains the error code. |
total | integer | 1 when the operation succeeds. |
data | object | Updated subtask. |
data.id | integer | Identifier of the subtask. |
data.id_task | integer | Identifier of the task it belongs to. |
data.id_task_form_item_type | integer | Subtask type (1 to 8). |
data.id_unit | integer | Identifier of the unit of measure. null if the subtask is not type 5. |
data.description | text | Label or question of the subtask. |
data.order_number | integer | Position of the subtask within the task. |
data.is_required | boolean | Indicates whether it is mandatory. |
data.attachments_required | boolean | Indicates whether it requires attachments. |
data.id_task_form_item_group | integer | Identifier of the subtask's group. null if it has no group. |
data.iterations | object | Iterations in which the subtask takes part. |
data.dropdown_options | array of objects | Options of the list. null if the subtask is not type 7. |
Errors
| Code | Cause |
|---|---|
400 | body is required: the request body is missing. |
400 | at least one editable field must be sent: no editable field was sent. |
400 | id_task_form_item_type must be between 1 and 8: invalid subtask type. |
400 | description cannot be empty: the description is empty or contains only spaces. |
400 | is_required must be a boolean, attachments_required must be a boolean or is_cyclical must be a boolean: the value sent is not a boolean. |
400 | task_form_item_group_description must have between 1 and 150 characters: empty or too long group name. |
400 | num_iterations must be greater than 0: num_iterations is not greater than 0. |
400 | dropdown_options only applies to list subtasks: options were sent for a subtask that is not type 7. |
400 | dropdown_options requires at least 2 elements for list subtasks: list with fewer than 2 options. |
400 | every dropdown option must have a non-empty description: an option without description. |
400 | id_unit must be an integer and unit_description at most 50 characters: id_unit is not an integer or unit_description exceeds 50 characters. |
400 | id_unit and unit_description only apply to meter reading subtasks: a unit was sent for a subtask that is not type 5. |
400 | id_unit or unit_description is required for meter reading subtasks: meter reading without a unit. |
400 | iterations must be an object or iterations must use the format {"iteration_n": true|false}: invalid iterations format. |
400 | iteration_n does not exist in task (num_iterations=n): iteration outside the task's range. |
401 | INVALID_TOKEN: the authentication token is not valid. |
403 | User does not have edit permission over TASKS > PLAN_TASKS: the token's profile cannot edit task plans. |
404 | subtask not found: the subtask does not exist or belongs to another company. |
409 | is_cyclical does not match the task configuration: is_cyclical does not match the task. |
409 | num_iterations does not match the task configuration: num_iterations does not match the task. |
422 | id_unit n does not exist: id_unit does not exist among the company's units. |
500 | Internal system error. |
Note on error codesWhen the operation fails, the error code arrives in the
messagefield (for example"404"or"409") and the detail indata[0].ERROR. The HTTP response of validation errors is400, regardless of the value ofmessage; usemessageto tell the causes apart. An invalid token responds with HTTP401.
Example
Request body
PUT /api/tasks_subtasks/6102
{
"description": "Bearing condition after the inspection",
"is_required": true,
"attachments_required": true,
"id_task_form_item_type": 7,
"dropdown_options": [
{ "description": "Good" },
{ "description": "Worn" },
{ "description": "Replace" }
]
}Response 200
200{
"success": true,
"message": "200",
"data": {
"id": 6102,
"id_task": 5001,
"id_task_form_item_type": 7,
"id_unit": null,
"description": "Bearing condition after the inspection",
"order_number": 3,
"is_required": true,
"attachments_required": true,
"id_task_form_item_group": null,
"iterations": {},
"dropdown_options": [
{ "description": "Good" },
{ "description": "Worn" },
{ "description": "Replace" }
]
},
"total": 1
}Response — Change to meter reading in a task with linked assets (200)
200)Request body:
{
"id_task_form_item_type": 5,
"unit_description": "Degrees Celsius"
}Response:
{
"success": true,
"message": "ERROR_CONFIG_METERS_ASSETS",
"data": {
"id": 6103,
"id_task": 5002,
"id_task_form_item_type": 5,
"id_unit": 215,
"description": "Motor temperature",
"order_number": 1,
"is_required": false,
"attachments_required": false,
"id_task_form_item_group": null,
"iterations": {},
"dropdown_options": null
},
"total": 1
}Response — List with fewer than 2 options (400)
400){
"success": false,
"message": "400",
"data": [
{
"ERROR": "dropdown_options requires at least 2 elements for list subtasks"
}
],
"total": "0"
}Response — Non-existent subtask (404)
404){
"success": false,
"message": "404",
"data": [
{
"ERROR": "subtask not found"
}
],
"total": "0"
}Response — is_cyclical does not match the task (409)
is_cyclical does not match the task (409){
"success": false,
"message": "409",
"data": [
{
"ERROR": "is_cyclical does not match the task configuration"
}
],
"total": "0"
}Response — Non-existent unit (422)
422){
"success": false,
"message": "422",
"data": [
{
"ERROR": "id_unit 999999 does not exist"
}
],
"total": "0"
}OpenAPI definition
{
"openapi": "3.1.0",
"info": {
"title": "tasks_subtasks",
"version": "2-En"
},
"servers": [
{ "url": "https://app.fracttal.com/api/tasks_subtasks" }
],
"security": [{}],
"paths": {
"/{id_subtask}": {
"put": {
"summary": "Update a subtask of a task in a task plan",
"description": "",
"operationId": "update-a-subtask-of-a-task-in-a-task-plan",
"deprecated": false,
"security": []
}
}
},
"x-readme": {
"headers": [],
"explorer-enabled": false,
"proxy-enabled": true
},
"x-readme-fauxas": true
} 200