Task Groups

Tasks are created inside "groups". As well as being a container for tasks these may contain a rule for creating more tasks when a results submission is received. Task Group are stored inside projects and a project ID has to be provided to the API.

Service Format Description Version Example
/api/v1/tasks/groups/{project id} Json Get a list of task groups for a project. 19.04+ https://sg.smap.com.au/api/v1/tasks/groups/193

Task List

Service Format Description Version Example
/api/v1/tasks GeoJSON Get a list of tasks 19.03+ https://sg.smap.com.au/api/v1/tasks


Filter Description Version Example
user The user ident. If the ident is not specified then tasks for all users are returned. You can set the ident to "_unassigned" to only get tasks that have not been assigned to a user. 19.03+ https://sg.smap.com.au/api/v1/tasks?user=_unassigned
tg_id The task group id. If the id is not specified then tasks for all task groups are returned. 19.03+ https://sg.smap.com.au/api/v1/tasks?tg_id=112
period Restrict tasks to those scheduled within a recent period. If the period is not set then "all" is assumed and all tasks and no period restriction is set. Other period values are "week" (default) and "month" which will return tasks scheduled more recently than a week / month ago. This includes tasks scheduled for the future. 19.03+ https://sg.smap.com.au/api/v1/tasks?period=month
start The first task to get. You should probably be using the default ordering by increasing task id when using this option. 19.03+ https://sg.smap.com.au/api/v1/tasks?user=tom&start=121
limit The number of records to return 19.03+ https://sg.smap.com.au/api/v1/tasks?start=12&limit=10
sort The property to sort on. This can be "id" the task id(default) or "scheduled", the scheduled time of the task 19.03+ https://sg.smap.com.au/api/v1/tasks?sort=scheduled
dirn The direction of sort. This can be "asc" (default) or "desc" 19.03+ https://sg.smap.com.au/api/v1/tasks?sort=scheduled&dirn=asc
tz Timezone 19.03+ https://sg.smap.com.au/api/v1/tasks?tz=Australia/Brisbane
status A comma separated list of status values that you want returned. Status values you can include are: new, accepted, unsent, unsubscribed, submitted, rejected, cancelled, deleted, pending, error, blocked. From version 19.08 you can also specify a status of "late". This will return tasks that are accepted but who's target completion time has passed. 19.04+ https://sg.smap.com.au/api/v1/tasks?status=accepted

Task Details

Returns details on a single task

Service Format Description Version Example
/api/v1/tasks/{task id} GeoJSON Get details on a single task 19.04+ https://sg.smap.com.au/api/v1/tasks/1000

Create a task

Service Format Description Version Example
/api/v1/tasks POST / GeoJSON Create a new task 19.04+ See below

The POST should include a body content type of application/x-www-form-urlencoded.

The payload should include a parameter called task which has a json value in the following format

  • tg_id: The identifier of the task group where you want to place this task
  • name: The name of the task
  • form_ident: The identifier for the survey that will guide the user through the task
  • assignee_ident: The username of the person being assigned the task
  • initial_data_source: Can be "none", "survey" or "task"
  • emails: A comma separated list of emails to whom the task can be assigned
  • lon: Longitude for the task
  • lat: Latitude for the task
  • show_dist: The distance in meters that the user has to be from the task before it shown to them
  • from: When the task should start
  • to: When the task should end
  • update_id: The instance id of a record to be updated (when initial_data_source is survey)
  • initial_data: A json object containing initial data. (when initial_data_source is task)

Example 1 - Assign a task to a user with username "tom"