Working with tasks¶

You can assign task to any tracked device. If specified tracker visits task checkpoint at the specified time and meets other conditions such as filling form or staying in the task zone for the specified time, the task completed. Otherwise, the task either failed completely or completed with warnings.

If task assigned to a Mobile Tracker App (Android / iOS), it's available for viewing by app user. User will also receive notifications of newly assigned tasks, task changes, etc.

Task object¶

{
    "id": 111,
    "user_id": 3,
    "tracker_id": 22,
    "location": {
        "lat": 56.5,
        "lng": 60.5,
        "address": "Fichtenstrasse 11",
        "radius": 150
    },
    "label": "Deliver parcels",
    "description": "Quickly",
    "creation_date": "2014-01-02 03:04:05",
    "from": "2014-02-03 04:05:06",
    "to": "2014-03-04 05:06:07",
    "external_id": null,
    "status": "assigned",
    "status_change_date": "2014-01-02 03:04:05",
    "max_delay" : 5,
    "min_stay_duration": 0,
    "arrival_date": "2014-01-02 03:04:05",
    "stay_duration": 0,
    "origin": "imported",
    "tags": [1, 2],
    "type": "task",
    "form": <form_object>,
    "fields": {
        "131312" : {
             "type": "text",
             "value":  "I love text!"
        }
   },
}

• id - int. Primary key. Used in task/update, IGNORED in task/create.
• user_id - int. User id. IGNORED in create/update.
• tracker_id - int. An id of the tracker to which task assigned. Can be null. IGNORED in task/update.
• location - location associated with this task. Cannot be null.
  • address - string. Address of the location.
  • radius- int. Radius of location zone in meters.
• creation_date - string date/time. When task created. IGNORED in create/update.
• from - string date/time. Date AFTER which task zone must be visited.
• to - string date/time. Date BEFORE which task zone must be visited.
• external_id - string. Used if task imported from external system. Arbitrary text string. Can be null.
• status - string enum. Task status. IGNORED in create/update. Can have "unassigned" value (unassigned to any executor), "assigned", "done", "failed", "delayed", "arrived" (arrived to geofence but haven't done the task), "faulty" (with problems).
• status_change_date - string date/time. When task status changed. IGNORED in create/update.
• max_delay - int. Maximum allowed task completion delay in minutes.
• min_stay_duration - int. Minimum duration of stay in task zone for task completion, minutes.
• arrival_date - string date/time. When tracker has arrived to the task zone. IGNORED in create/update.
• stay_duration - int. Duration of stay in the task zone, seconds.
• origin - string. Task origin. IGNORED in create/update.
• tags - array of int. List of tag ids.
• form - form object. If present.
• fields - optional object. A map, each key of which is a custom field id as a string. See entity/fields

API actions¶

API base path: /task.

assign¶

(Re)assigns task to new tracker (or make it unassigned).

required sub-user rights: task_update.

parameters¶

examples¶

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

https://api.navixy.com/v2/fsm/task/assign?hash=a6aa75587e5c59c32d347da438505fc3&task_id=23144&tracker_id=132421

response¶

{ "success": true }

errors¶

• 201 – Not found in the database (if there is no task with such an id).
• 204 – Entity not found (if there is no tracker with such id belonging to authorized user).
• 208 – Device blocked (if tracker exists but was blocked due to tariff restrictions or some other reason).
• 255 – Invalid task state (if current task state is not "unassigned" or "assigned").
• 236 – Feature unavailable due to tariff restrictions (if device's tariff does not allow usage of tasks).

batch_convert¶

Converts batch of tab-delimited tasks and return list of checked tasks with errors.

required sub-user rights: task_update.

parameters¶

In case of location_check_mode==entity_location – vehicle_ids will be ignored.

response¶

{
    "success": true,
    "list": [{
         "id": 111,
         "user_id": 3,
         "tracker_id": 22,
         "location": {
             "lat": 56.5,
             "lng": 60.5,
             "address": "Fichtenstrasse 11",
             "radius": 150
         },
         "label": "Deliver parcels",
         "description": "Quickly",
         "creation_date": "2014-01-02 03:04:05",
         "from": "2014-02-03 04:05:06",
         "to": "2014-03-04 05:06:07",
         "external_id": null,
         "status": "assigned",
         "status_change_date": "2014-01-02 03:04:05",
         "max_delay" : 5,
         "min_stay_duration": 0,
         "arrival_date": "2014-01-02 03:04:05",
         "stay_duration": 0,
         "origin": "imported",
         "tags": [1, 2]
         "type": "task",
         "form": <form_object>,
         "errors": [<error_object>]
    }],
    "limit_exceeded": false
}

• list - list of checked task objects that contain all fields from task and field errors.
  • errors - array of objects. Optional. List of errors.
• limit_exceeded - boolean. true if given batch constrained by a limit.

errors¶

General types only.

count¶

Returns total number of tasks belonging to current user.

examples¶

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

https://api.navixy.com/v2/fsm/task/count?hash=a6aa75587e5c59c32d347da438505fc3

response¶

{
    "success": true,
    "count": 111
}

• count - int. Number of tasks.

create¶

Creates a new task.

required sub-user rights: task_update.

parameters¶

Minimal JSON object to create a new task must contain:

{
    "tracker_id": 22,
    "location": {
    "lat": 56.83717295,
    "lng": 60.59761920,
    "radius": 150
    },
    "label": "Name",
    "description": "Description example",
    "from": "2020-02-03 04:05:06",
    "to": "2020-03-04 05:06:07"
}

• tracker_id - int. Optional. if the field specified then the task will be assigned to the employee associated with the tracker, otherwise it won't be assigned to anybody.
• location - area (circle geofence), entering and leaving of geofence will be controlled.
  • lat - float. Latitude.
  • lng - float. Longitude.
  • radius - int. Radius in meters.
• label - string. Task name, length 1-200 characters.
• description - string. Task description, length 0-1024 characters.
• from - string date/time. Start date of the interval - when the specified location has to be visited (in the user's time zone).
• to - string date/time. End date of the interval - when the specified location has to be visited (in the user's time zone).

example¶

curl -X POST 'https://api.navixy.com/v2/fsm/task/create' \
    -H 'Content-Type: application/json' \ 
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b" "task": {"tracker_id": 22, "location": {"lat": 56.83717295, "lng": 60.59761920, "radius": 150}, "label": "Name", "description": "Description example", "from": "2020-02-03 04:05:06", "to": "2020-03-04 05:06:07"}, "create_form": false}'

task/create call returns the identifier of the created task. A returned object also can include "external_id_counts" field see task/route/create method description.

response¶

{
    "success": true,
    "id": 111,
    "external_id_counts": [{
        "external_id": "456", 
        "count": 2
    }]
}

• id - int. An id of the created task.

Note: The "id" parameter is unique, it is automatically generated by the server when you create a task. Therefore, if you call task/create two times with the same parameters, every time the new task will be created. These two tasks will differ only by an id. Respectively, if the created task has to be connected to a certain record in external system, you have to remember the id of this record to use it in future when you want to change/delete the associated task in our system.

errors¶

• 201 – Not found in the database (if task.tracker_id is not null and belongs to nonexistent tracker).
• 236 – Feature unavailable due to tariff restrictions (if device's tariff does not allow usage of tasks).

delete¶

Deletes the task with the specified id.

required sub-user rights: task_update.

parameters¶

examples¶

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

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

response¶

{ "success": true }

errors¶

• 201 – Not found in the database (if there is no task with such an id).

list¶

Gets all task belonging to user with optional filtering.

parameters¶

condition fields¶

If external_id, trackers, filters, from, to or tag_ids is not passed or null then appropriate condition not used to filter results.

If offset or limit is null then restrictions for pagination will not be applied.

sort: string[]?¶

set of sort options. Each option is a pair of column name and sorting direction, e.g. ["label=acs", "address=desc", "employee=desc"].

sort fields¶

If external_id, trackers, filters, from, to or tag_ids is not passed or null then appropriate condition not used to filter results.

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

https://api.navixy.com/v2/fsm/task/list?hash=a6aa75587e5c59c32d347da438505fc3

response¶

{
    "success": true,
    "list": [{
        "id": 111,
        "user_id": 3,
        "tracker_id": 22, 
        "location": {
            "lat": 56.5,
            "lng": 60.5,
            "address": "Schulhof 2, Wien, Austria",
            "radius": 150
         },
         "label": "Name",
         "description": "Description example",
         "creation_date": "2014-01-02 03:04:05",
         "from": "2020-02-03 04:05:06",
         "to": "2020-03-04 05:06:07",
         "external_id": "01234567",
         "status": "assigned",
         "status_change_date": "2020-01-02 03:04:05",
         "max_delay": 5,
         "min_stay_duration": 0,
         "arrival_date": "2020-01-02 03:04:05",
         "stay_duration": 10,
         "origin": "manual",
         "type": "task"
    }],
    "count": 1
}

• list - array of task objects.
  • id - int. Task id.
  • user_id - int. User id (office). An unchangeable parameter.
  • tracker_id - int. Tracker ID. Indicator ID by which the implementation of this task will be controlled.
  • location - area (circle geofence), entering and leaving of geofence will be controlled.
  • label - string. Task name, length 1-200 characters.
  • description - string. Task description, length 0-1024 characters.
  • creation_date - string date/time. Date of creation of a task, unchangeable field.
  • from - string date/time. Start date of the interval - when the specified location has to be visited (in the user's time zone).
  • to - string date/time. End date of the interval - when the specified location has to be visited (in the user's time zone).
  • external_id - string. Text field for tracking of communication of the task with certain external systems (for example, number of the order). Is for reference only.
  • status - string enum. Current status of a task, can have "unassigned" value (unassigned to any executor), "assigned", "done", "failed", "delayed", "arrived" (arrived to geofence but haven't done the task), "faulty" (with problems).
  • status_change_date - string date/time. Date of the last change of the status of a task.
  • max_delay - int. The maximum time delay of the execution of the task, in minutes.
  • min_stay_duration - int. The minimum stay time in the area of the task in which the task has to be done, in minutes.
  • arrival_date - string date/time. Date and time of arrival in the area of the task. Can be null. If the executor has not visited it yet.
  • stay_duration - int. Number of seconds spent inside task zone.
  • origin - string enum. The way of creation of a task. Can be "manual", "scheduled" or "imported" (from excel).
  • type - string. Reserved.
• count - int. count of the all found tasks.

errors¶

General types only.

read¶

Gets task, checkpoint, or route with checkpoints by specified id.

parameters¶

examples¶

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

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

response¶

{
    "success": true,
    "value":  <task, checkpoint or route>,
    "checkpoints": [
        <checkpoint1>,
        <checkpoint2>
    ]

}

• value - JSON object. task described here.
• checkpoints - only returned if entity with specified id is a route. Contains all checkpoints of this route. checkpoint object described here.

errors¶

• 201 – Not found in the database (if there is no task with such an id).

transmute¶

Converts task into a route checkpoint.

required sub-user rights: task_update.

parameters¶

examples¶

curl -X POST 'https://api.navixy.com/v2/fsm/task/transmute' \
    -H 'Content-Type: application/json' \ 
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "task_id": 23144, "route_id": 12334, "order": 0}'

https://api.navixy.com/v2/fsm/task/transmute?hash=a6aa75587e5c59c32d347da438505fc3&task_id=23144&route_id=12334&order=0

response¶

{ "success": true }

errors¶

• 201 – Not found in the database (if there is no task or route with such an id, or tracker to which checkpoint assigned is unavailable to current sub-user).
• 255 – Invalid task state (if task or any of the checkpoints are not in unassigned or assigned state).

update¶

Updates existing task. Note that you cannot change task owner using this method.

required sub-user rights: task_update.

parameters¶

example¶

curl -X POST 'https://api.navixy.com/v2/fsm/task/update' \
    -H 'Content-Type: application/json' \ 
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b" "task": {"id": 22379, "location": {"lat": 56.83717295, "lng": 60.59761920, "radius": 150}, "label": "Name", "description": "Description example", "from": "2020-02-03 04:05:06", "to": "2020-03-04 05:06:07"}, "create_form": false}'

A returned object also can include "external_id_counts" field see task/route/create method description.

response¶

{
    "success": true,
    "external_id_counts": [{
        "external_id": "456", 
        "count": 2
    }]
}

errors¶

• 201 – Not found in the database (if there is no task with such an id).
• 255 – Invalid task state (if current task state is not "unassigned" or "assigned").