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 |
Parameters
| 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"