Update a subtask of a task in a task plan

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

General 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

ParameterTypeRequiredDescription
id_subtaskintegerYes (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).

ParameterTypeRequiredDescription
id_task_form_item_typeintegerNoSubtask 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.
descriptiontextNoLabel or question of the subtask. It cannot be empty or contain only spaces.
task_form_item_group_descriptiontextNoName 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_unitintegerConditionalIdentifier of the unit of measure. Only applies to type 5 subtasks. It must exist among the company's units.
unit_descriptiontextConditionalName 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_optionsarray of objectsConditionalOptions of the list. Only applies to type 7 subtasks. Minimum 2 elements. See the structure in the next table.
iterationsobjectNoIterations 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_requiredbooleanNoIndicates whether the subtask is mandatory.
attachments_requiredbooleanNoIndicates whether the subtask requires attachments.
is_cyclicalbooleanNoIndicates whether the task is cyclical. If sent, it must match the task configuration; this service does not modify it.
num_iterationsintegerNoNumber 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:

ParameterTypeRequiredDescription
descriptiontextYesText 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_type or, if you do not send it, the one it already has.
  • When changing to type 7 (List) you must send dropdown_options with at least 2 options.
  • When changing to type 5 (Meter reading) you must send id_unit or unit_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 but message is returned as ERROR_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_options is only accepted on type 7 subtasks; id_unit and unit_description only on type 5 subtasks.
  • iterations is merged with the subtask's current iterations: only the iterations you send are changed. Each iteration_n must be between 1 and the number of iterations of the task. In a task that is not cyclical, iterations is ignored.
  • A subtask from another company is treated the same as a non-existent one (404).

Output parameters

ParameterTypeDescription
successbooleantrue if the subtask was updated.
messagetext200 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.
totalinteger1 when the operation succeeds.
dataobjectUpdated subtask.
data.idintegerIdentifier of the subtask.
data.id_taskintegerIdentifier of the task it belongs to.
data.id_task_form_item_typeintegerSubtask type (1 to 8).
data.id_unitintegerIdentifier of the unit of measure. null if the subtask is not type 5.
data.descriptiontextLabel or question of the subtask.
data.order_numberintegerPosition of the subtask within the task.
data.is_requiredbooleanIndicates whether it is mandatory.
data.attachments_requiredbooleanIndicates whether it requires attachments.
data.id_task_form_item_groupintegerIdentifier of the subtask's group. null if it has no group.
data.iterationsobjectIterations in which the subtask takes part.
data.dropdown_optionsarray of objectsOptions of the list. null if the subtask is not type 7.

Errors

CodeCause
400body is required: the request body is missing.
400at least one editable field must be sent: no editable field was sent.
400id_task_form_item_type must be between 1 and 8: invalid subtask type.
400description cannot be empty: the description is empty or contains only spaces.
400is_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.
400task_form_item_group_description must have between 1 and 150 characters: empty or too long group name.
400num_iterations must be greater than 0: num_iterations is not greater than 0.
400dropdown_options only applies to list subtasks: options were sent for a subtask that is not type 7.
400dropdown_options requires at least 2 elements for list subtasks: list with fewer than 2 options.
400every dropdown option must have a non-empty description: an option without description.
400id_unit must be an integer and unit_description at most 50 characters: id_unit is not an integer or unit_description exceeds 50 characters.
400id_unit and unit_description only apply to meter reading subtasks: a unit was sent for a subtask that is not type 5.
400id_unit or unit_description is required for meter reading subtasks: meter reading without a unit.
400iterations must be an object or iterations must use the format {"iteration_n": true|false}: invalid iterations format.
400iteration_n does not exist in task (num_iterations=n): iteration outside the task's range.
401INVALID_TOKEN: the authentication token is not valid.
403User does not have edit permission over TASKS > PLAN_TASKS: the token's profile cannot edit task plans.
404subtask not found: the subtask does not exist or belongs to another company.
409is_cyclical does not match the task configuration: is_cyclical does not match the task.
409num_iterations does not match the task configuration: num_iterations does not match the task.
422id_unit n does not exist: id_unit does not exist among the company's units.
500Internal system error.

Note on error codes

When the operation fails, the error code arrives in the message field (for example "404" or "409") and the detail in data[0].ERROR. The HTTP response of validation errors is 400, regardless of the value of message; use message to tell the causes apart. An invalid token responds with HTTP 401.


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

{
  "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)

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)

{
  "success": false,
  "message": "400",
  "data": [
    {
      "ERROR": "dropdown_options requires at least 2 elements for list subtasks"
    }
  ],
  "total": "0"
}

Response — Non-existent subtask (404)

{
  "success": false,
  "message": "404",
  "data": [
    {
      "ERROR": "subtask not found"
    }
  ],
  "total": "0"
}

Response — 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)

{
  "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
}
Path Params
integer
required
Response
200
Language
LoadingLoading…