Create subtasks in a task of a task plan

post

https://app.fracttal.com/api/tasks_subtasks/

Allows creating one or more subtasks within an existing task of a task plan (maintenance form), without depending on the Fracttal UI.

POST https://app.fracttal.com/api/tasks_subtasks

Input parameters — Required

Sent in the request body.

Parameter	Type	Required	Description
`id_task`	integer	Yes	Id of the existing task within the task plan where the subtasks will be created. Obtained from the plan's task list/detail.
`is_cyclical`	boolean	Yes	Indicates whether the task handles iterations. Must match the task's actual state — if it doesn't, the request is rejected with `409`.
`num_iterations`	integer	Yes, only if `is_cyclical = true`	Number of iterations of the task. Integer greater than 0.
`subtasks`	array of objects	Yes	Array with at least one element; each element is the configuration of a subtask. The array order determines the assigned `order_number`. See `subtasks` parameters below for each element's fields.

Input parameters — Optional

None at the top level — all optional fields of this endpoint are part of each subtasks element (see below).

`subtasks` parameters

Each element of the subtasks array represents a subtask to create, with the following fields:

Required

Parameter	Type	Required	Description
`id_task_form_item_type`	integer	Yes	Type of subtask to create. Determines which other fields apply — see the `Subtask types` table below. Valid values: `1` to `8`.
`description`	string	Yes	Text shown as the label/question of the subtask when executing the task (e.g. "Describe el procedimiento realizado"). Cannot be empty.

Subtask types (`id_task_form_item_type`)

Id	Type	Relevant additional fields
`1`	Text	None.
`2`	Yes/No	None.
`3`	Number	None.
`4`	Checkbox	None.
`5`	Meter reading	Requires `id_unit` or `unit_description` (see Optional). If the task has linked assets, the response may include `message: "ERROR_CONFIG_METERS_ASSETS"`.
`6`	GPS location	None.
`7`	List	Requires `dropdown_options` with at least 2 elements (see Optional).
`8`	Date and time	None.

Optional

Parameter	Type	Required	Description
`is_required`	boolean	Optional	Default: `false`.
`attachments_required`	boolean	Optional	Default: `false`.
`task_form_item_group_description`	string	Optional	Group/section name. If provided, a similar group is looked up (fuzzy match); if none exists, it's created automatically.
`id_unit`	integer	Optional (required if `id_task_form_item_type = 5` and `unit_description` is not sent)	Unit of measure id in `companies.units`. If it doesn't exist, returns `422`.
`unit_description`	string	Optional (required if `id_task_form_item_type = 5` and `id_unit` is not sent)	Unit description; if there's no match by similarity, it's created automatically.
`dropdown_options`	array	Optional (required if `id_task_form_item_type = 7`, minimum 2 elements)	Each element: `{ "description": string }`.
`iterations`	object	Optional	Only applies if `is_cyclical = true` (at the request level). Format: `{ "iteration_1": true, "iteration_3": true, ... }`. If any `iteration_n` has `n > num_iterations`, returns `400`. If omitted or sent empty, the subtask does not participate in any iteration.

Output parameters

Parameter	Type	Description
`id`	integer	Id generated for the created subtask.
`id_task`	integer	Id of the task it belongs to.
`id_task_form_item_type`	integer	Subtask type.
`description`	string	Subtask description.
`order_number`	integer	Order automatically assigned by the server.
`is_required`	boolean	Whether the subtask is mandatory.
`attachments_required`	boolean	Whether it requires attachments.
`id_task_form_item_group`	integer	Id of the associated group/section (created or reused).
`iterations`	object	Iterations in which the subtask participates.
`dropdown_options`	array	List options (type `7` only).
`message`	string	`ERROR_CONFIG_METERS_ASSETS` when the task has linked assets and a type `5` (meter) subtask is added; requires additional per-asset configuration.
`total`	integer	Number of affected assets — present only together with `ERROR_CONFIG_METERS_ASSETS`.

Errors

Code	Cause
`400`	`id_task` not provided; `is_cyclical` not provided; `is_cyclical=true` without `num_iterations`; `num_iterations` ≤ 0; `subtasks` empty or missing; `id_task_form_item_type` outside 1–8; empty `description`; type `5` without `id_unit` nor `unit_description`; type `7` with fewer than 2 `dropdown_options` or an option without `description`; some `iteration_n` with `n > num_iterations`.
`401`	No authentication.
`403`	No `edit` permission on `TASKS > PLAN_TASKS`.
`404`	`id_task` does not exist.
`409`	`is_cyclical` or `num_iterations` in the body doesn't match the task's actual state.
`415`	`Content-Type` other than `application/json`.
`422`	`id_unit` does not exist in `companies.units`.

Example

Request body (cyclical task, 4 iterations)

{
  "id_task": 1001,
  "is_cyclical": true,
  "num_iterations": 4,
  "subtasks": [
    {
      "id_task_form_item_type": 1,
      "description": "Describe el procedimiento realizado",
      "iterations": { "iteration_4": true },
      "is_required": false,
      "attachments_required": false
    },
    {
      "id_task_form_item_type": 5,
      "description": "Lectura de presión hidráulica",
      "task_form_item_group_description": "Sistema Hidráulico",
      "id_unit": 42,
      "iterations": { "iteration_1": true, "iteration_2": true, "iteration_3": true, "iteration_4": true },
      "is_required": true,
      "attachments_required": false
    },
    {
      "id_task_form_item_type": 7,
      "description": "Estado general del equipo",
      "task_form_item_group_description": "Inspección General",
      "dropdown_options": [
        { "description": "Bueno" },
        { "description": "Regular" },
        { "description": "Malo" }
      ],
      "iterations": { "iteration_2": true, "iteration_4": true },
      "is_required": true,
      "attachments_required": true
    }
  ]
}

Response `200`

{
  "success": true,
  "message": "200",
  "data": [
    {
      "id": 501,
      "id_task": 1001,
      "id_task_form_item_type": 1,
      "description": "Describe el procedimiento realizado",
      "order_number": 1,
      "is_required": false,
      "attachments_required": false,
      "id_task_form_item_group": null,
      "iterations": { "iteration_4": true },
      "dropdown_options": null
    },
    {
      "id": 502,
      "id_task": 1001,
      "id_task_form_item_type": 5,
      "description": "Lectura de presión hidráulica",
      "order_number": 2,
      "is_required": true,
      "attachments_required": false,
      "id_task_form_item_group": 12,
      "iterations": { "iteration_1": true, "iteration_2": true, "iteration_3": true, "iteration_4": true },
      "dropdown_options": null
    },
    {
      "id": 503,
      "id_task": 1001,
      "id_task_form_item_type": 7,
      "description": "Estado general del equipo",
      "order_number": 3,
      "is_required": true,
      "attachments_required": true,
      "id_task_form_item_group": 13,
      "iterations": { "iteration_2": true, "iteration_4": true },
      "dropdown_options": [
        { "id": 1, "description": "Bueno" },
        { "id": 2, "description": "Regular" },
        { "id": 3, "description": "Malo" }
      ]
    }
  ],
  "total": 3
}

Response — meter-type subtask on a task with linked assets

{
  "success": true,
  "message": "ERROR_CONFIG_METERS_ASSETS",
  "data": [
    {
      "id": 504,
      "id_task": 1001,
      "id_task_form_item_type": 5,
      "description": "Lectura de nivel de aceite",
      "order_number": 4,
      "is_required": true,
      "attachments_required": false,
      "id_task_form_item_group": null,
      "iterations": {},
      "dropdown_options": null
    }
  ],
  "total": 3
}

OpenAPI definition

{
  "openapi": "3.1.0",
  "info": {
    "title": "tasks",
    "version": "2-En"
  },
  "servers": [
    {
      "url": "https://app.fracttal.com/api/tasks_subtasks"
    }
  ],
  "security": [
    {}
  ],
  "paths": {
    "/": {
      "post": {
        "summary": "Create subtasks in a task of a task plan",
        "description": "",
        "operationId": "create-subtasks-in-a-task-of-a-task-plan",
        "deprecated": false,
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["id_task", "is_cyclical", "subtasks"],
                "properties": {
                  "id_task": { "type": "integer" },
                  "is_cyclical": { "type": "boolean" },
                  "num_iterations": { "type": "integer" },
                  "subtasks": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "object",
                      "required": ["id_task_form_item_type", "description"],
                      "properties": {
                        "id_task_form_item_type": { "type": "integer", "minimum": 1, "maximum": 8 },
                        "description": { "type": "string" },
                        "is_required": { "type": "boolean", "default": false },
                        "attachments_required": { "type": "boolean", "default": false },
                        "task_form_item_group_description": { "type": "string" },
                        "id_unit": { "type": "integer" },
                        "unit_description": { "type": "string" },
                        "dropdown_options": {
                          "type": "array",
                          "items": { "type": "object", "properties": { "description": { "type": "string" } } }
                        },
                        "iterations": { "type": "object", "additionalProperties": { "type": "boolean" } }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Subtasks created successfully" },
          "400": { "description": "Bad Request" },
          "401": { "description": "Unauthorized" },
          "403": { "description": "Forbidden" },
          "404": { "description": "Not Found" },
          "409": { "description": "Conflict" },
          "415": { "description": "Unsupported Media Type" },
          "422": { "description": "Unprocessable Entity" }
        }
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": false,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}

Response

200

Language

Loading…