Working with task forms¶

Forms can be attached to tasks to be filled by field employees using Mobile Tracker App (Android / iOS). This document describes API actions specific to working with task forms (except task/form/list which can return all kinds of forms).

For <form_field> and <form_value> object description, see form fields and values.

For <form> object description, see forms.

API actions¶

API path: /task/form.

Contains API calls related to forms associated with tasks.

create¶

Attaches new form to the existing task or checkpoint. Form always created on the basis of form template.

required sub-user rights: task_update.

parameters¶

examples¶

curl -X POST 'https://api.navixy.com/v2/fsm/task/form/create' \
    -H 'Content-Type: application/json' \ 
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "task_id": 11231, "template_id": 12548}'

https://api.navixy.com/v2/fsm/task/form/create?hash=a6aa75587e5c59c32d347da438505fc3&task_id=11231&template_id=12548

response¶

{
    "success": true
}

errors¶

• 201 – Not found in the database (if there is no task or template with such an id, or task has the "route" type).
• 247 – Entity already exists (if task already has form attached to it).
• 255 – Invalid task state (if current task state is not "unassigned", "assigned" or "arrived").

delete¶

Deletes a form (detach it from the task).
All form data will be lost!

required sub-user rights: task_update.

parameters¶

examples¶

curl -X POST 'https://api.navixy.com/v2/fsm/task/form/delete' \
    -H 'Content-Type: application/json' \ 
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "task_id": 11231}'

https://api.navixy.com/v2/fsm/task/form/delete?hash=a6aa75587e5c59c32d347da438505fc3&task_id=11231

response¶

{
    "success": true
}

errors¶

• 201 – Not found in the database (if there is no task with such an id, or task has the "route" type, or it has no form attached).
• 255 – Invalid task state (if current task state is not "unassigned", "assigned" or "arrived").

download¶

Retrieves attached form as file.

parameters¶

examples¶

curl -X POST 'https://api.navixy.com/v2/fsm/task/form/download' \
    -H 'Content-Type: application/json' \ 
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "task_id": 11231, "format": "pdf"}'

https://api.navixy.com/v2/fsm/task/form/download?hash=a6aa75587e5c59c32d347da438505fc3&task_id=11231&format=pdf

response¶

A form rendered to file (standard file download).

errors¶

• 201 – Not found in the database (if task does not exist or does not have attached form).

list¶

Returns descriptions of forms, created on the basis of specified form template. In addition to the data on the forms, the list contains data on the objects related to each form – tracker / vehicle / employee, task.

parameters¶

• form_template_id (integer, optional). The returned list will contain forms, related to that template.
  warning: at least one of form_template_id and task_ids parameters must be not null.
• task_ids (list of integers, optional). Maximum size of list is 500 elements. List of task ids. The returned list will contain forms, related to tasks, which ids specified in this parameter.
  warning: at least one of form_template_id and task_ids parameters must be not null.
• order_by (optional, default = submitted). Data field for list sorting. Available values:
  • task_id
  • created
  • submitted
  • task_address
  • submit_address
  • employee_full_name
  • vehicle_label
  • tracker_label
  • task_label
  • task_creation_date
  • task_from
  • task_to
  • task_arrival_date
  • task_completion_date
  • form_label
  • form_description
• ascending (boolean, required). Sorting direction (ascending / descending).
• include_unsubmitted (boolean, required). If true, unsubmitted forms shall be included in the list.
• filters (object, optional). Specifies the criteria for filtering the list based on the values of the data fields. Conditions are combined by logical AND.\ Filters object contains following optional elements:

{
    "employee_full_name": , // a sequence of characters for partial matching (against the name of the associated employee)
    "form_description": ,
    "form_label": ,
    "submit_address": ,
    "task_id": // strict match
    "task_address": ,
    "task_label": ,
    "tracker_label": ,
    "vehicle_label": ,
}

• submit_period (period_object, optional).
• task_creation_period (period_object, optional).
• task_from_period (period_object, optional).
• task_to_period (period_object, optional).
• task_arrival_period (period_object, optional).
• task_completion_period (period_object, optional).

where period_object is:

    {
        "from": "2020-02-03 03:00:00", // string <date/time>
        "to": "2020-02-03 08:00:00" // string <date/time>
    }

• offset, limit (integers, optional). Specify which subset of elements from all matching results will be included in the returned list.

examples¶

curl -X POST 'https://api.navixy.com/v2/fsm/task/form/list' \
    -H 'Content-Type: application/json' \ 
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "ascending": "true", "include_unsubmitted": "true"}'

https://api.navixy.com/v2/fsm/task/form/list?hash=a6aa75587e5c59c32d347da438505fc3&ascending=true&include_unsubmitted=true

response¶

{
    "success": true,
    "count": 2,
    "list": [{
        "employee": {
            "id": 13,
            "first_name": "John",
            "middle_name": "",
            "last_name": "Dow"
        },
        "task": {
            "id": 7867,
            "label": "My task 3",
            "from": "2017-07-27 15:00:00",
            "to": "2017-07-28 14:59:59",
            "creation_date": "2017-07-27 12:12:23",
            "arrival_date": "2017-07-27 15:14:07",
            "address": "Moltkestrasse 32",
            "status": "done",
            "completion_date": "2017-07-28 14:36:28",
            "fact_duration": "PT22M21S"
        },
        "tracker": {
            "id": 15620,
            "label": "Navixy A6"
        },
        "vehicle": null,
        "form": {
            "id": 1012,
            "label": "A form",
            "description": "",
            "fields": [],
            "created": "2017-07-28 03:48:06",
            "submit_in_zone": false,
            "task_id": 7867,
            "template_id": 449,
            "values": null,
            "submitted": "2017-03-21 18:40:54", 
            "submit_location": {
                "lat": 26.826762,
                "lng": 20.5947311,
                "address": "Partizan st., 4"
            }
        },
        "submit_places": {
            "location": {
                "lat": 26.826762,
                "lng": 20.5947311,
                "address": "Partizan st., 4"
            },
            "places": [{
                "id": 38,
                "label": "Office sweet office"
            }],
            "zones": [{
                "id": 18404,
                "label": "Zone 51"
            }]
        }
    }
]}

• count - int. Total number of forms matching the query.
• form - form object, non-null.
• submit_places - additional info about places/zones related to form submission, can be null.
  • places - list of places associated with zone submission location. Can be empty.
  • zones - list of zones associated with zone submission location. Can be empty.

errors¶

• 204 – Not found (if there is no form template with such id belonging to authorized user).
• General types of errors.

read¶

Gets form associated with the specified task.

parameters¶

examples¶

curl -X POST 'https://api.navixy.com/v2/fsm/task/form/read' \
    -H 'Content-Type: application/json' \ 
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "task_id": "12546"}'

https://api.navixy.com/v2/fsm/task/form/read?hash=a6aa75587e5c59c32d347da438505fc3&task_id=12546

response¶

{
    "success": true,
    "value" : <form>,
    "files" : [
        {
            "id": 16,
            "storage_id": 1,
            "user_id": 12203,
            "type": "image",
            "created": "2020-09-06 11:54:28",
            "uploaded": "2020-09-06 11:55:14",
            "name": "lala.jpg",
            "size": 72594,
            "mime_type": "image/png",
            "metadata": {
                         "orientation":  1
                        },
            "state": "uploaded",
            "download_url": "https://static.navixy.com/file/dl/1/0/1g/01gw2j5q7nm4r92dytolzd6koxy9e38v.png/lala.jpg",
            "bindings": {
                "form_field": {
                    "form_id": 40,
                    "field_id": "2222",
                    "submitted": false
                }
            },
            "previews": [
                {
                    "download_url": "https://localhost:8084/file/preview/1/0/1g/01gw2j5q7nm4r92dytolzd6koxy9e38v.png/lala.jpg"
                }
            ]
        }
   ]
}

• value - form object, or null if no form attached.
• files - list of files, both submitted and unsibmitted, associated with this form's fields.
  • id - int. File id.
  • type - string enum. Can be "image" or "file".
  • created - string date/time. Date when file created.
  • uploaded - string date/time. Date when file uploaded, can be null if file not yet uploaded.
  • name - string. Filename.
  • size - int. Size in bytes. If file not uploaded, show maximum allowed size for the upload.
  • metadata - metadata object.
  • orientation - int. Image exif orientation.
  • state - string enum. Can be "created", "in_progress", "uploaded", "deleted".
  • download_url - string. Actual url at which file is available. Can be null if file not yet uploaded.
  • bindings - all entities to which this file linked.
  • previews - available preview images for the file. Can be null or empty for any file in any state.

errors¶

• 201 – Not found in the database (if there is no task with such an id, or task assigned to tracker unavailable to current sub-user).