Tasks API

Task Groups

GET /api/v1/tasks/groups/(project id)
Synposis:get a list of task groups in a project. You can use the Projects request with a query parameter of links=true to get a list of available task groups URLs

Example response:

https://sg.smap.com.au/api/v1/tasks/groups/1554

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

[
  {
        "tg_id": 199,
        "name": "xxxx",
        "address_params": "[]",
        "p_id": 1,
        "rule": {
          "task_group_name": "xxxx",
          "dl_dist": 0,
          "show_dist": 100,
          "source_survey_id": 17821,
          "target_survey_id": 20282,
          "project_name": "A project",
          "source_survey_name": "3. School Personnel",
          "survey_name": "accuracy",
          "user_id": -2,
          "role_id": 0,
          "fixed_role_id": 0,
          "assign_data": "${q1.1}",
          "task_group_id": 0,
          "blank": true,
          "prepopulate": true,
          "update_results": false,
          "add_future": true,
          "add_current": false,
          "address_columns": [],
          "filter": {
                "qId": 0,
                "oId": 0,
                "qInteger": 0,
                "qStartDate": 0,
                "qEndDate": 0,
                "advanced": "${q1.2} > 1000"
          },
          "taskStart": -1,
          "taskAfter": 3,
          "taskUnits": "days",
          "taskDuration": 2,
          "durationUnits": "hours",
          "emailDetails": {
                "subject": "",
                "content": ""
          },
          "complete_all": true,
          "assign_auto": false
        },
        "source_s_id": 17821,
        "target_s_id": 20282,
        "totalTasks": 1,
        "completeTasks": 1,
        "emaildetails": {
          "subject": "",
          "content": ""
        }
  }

]

In the task group details shown above:

  • A task is created if the answer to question q1.2 in the submitted data was greater than 1000
  • The task is assigned to the user identified in the answer to question q1.2
  • Tasks are triggered by survey 17821 and require the completion of survey 20282
Request Headers:
 
Status Codes:

Task List

GET /api/v1/tasks
Synposis:get a list of tasks.

Example response:

https://sg.smap.com.au/api/v1/tasks

The format of the response is GeoJSON.

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "type": "FeatureCollection",
  "features": [
        {
          "type": "Feature",
          "geometry": {
                "type": "Point",
                "coordinates": [
                  0,
                  0
                ]
          },
          "properties": {
                "tg_id": 234,
                "name": "cccc",
                "form_id": 17831,
                "survey_ident": "s1_17829",
                "assignee_ident": "neil",
                "generate_user": false,
                "from": "2019-11-09 01:44:34",
                "to": "2019-11-09 02:44:34",
                "location_trigger": "",
                "repeat": false,
                "repeat_count": 1,
                "guidance": "",
                "lon": 0,
                "lat": 0,
                "complete_all": true,
                "assign_auto": true,
                "show_dist": 0,
                "id": 2507,
                "tg_name": "Locate",
                "p_id": 0,
                "a_id": 2215,
                "survey_name": "2. Entèvyou paran oubyen gadyen (Parent Guardian) (1)",
                "blocked": false,
                "assignee": 3988,
                "assignee_name": "Neil Penman",
                "comment": "",
                "status": "late"
          },
          "links": {
                "detail": "https://sg.smap.com.au/api/v1/tasks/2507",
                "webform": "https://sg.smap.com.au/webForm/s1_17829?assignment_id=2215"
          }
        },
        {
          "type": "Feature",
          "geometry": {
                "type": "Point",
                "coordinates": [
                  153.01260069944,
                  -27.446150149836
                ]
          },
          "properties": {
                "tg_id": 235,
                "name": "Light 2",
                "form_id": 20361,
                "survey_ident": "s1554_20361",
                "assignee_ident": "neil",
                "generate_user": false,
                "from": "2019-11-09 04:21:16",
                "to": "2019-11-09 05:21:16",
                "location_trigger": "",
                "repeat": false,
                "repeat_count": 1,
                "guidance": "",
                "lon": 153.01260069943964,
                "lat": -27.446150149835972,
                "complete_all": true,
                "assign_auto": true,
                "show_dist": 0,
                "id": 2508,
                "tg_name": "Maintenance",
                "p_id": 0,
                "a_id": 2216,
                "survey_name": "street light",
                "blocked": false,
                "assignee": 3988,
                "assignee_name": "Neil Penman",
                "comment": "",
                "status": "late"
          },
          "links": {
                "detail": "https://sg.smap.com.au/api/v1/tasks/2508",
                "webform": "https://sg.smap.com.au/webForm/s1554_20361?assignment_id=2216"
          }
        }
  ]
}
Query Parameters:
 
  • user – The ident of the user who has been assigned the task. Use _unassigned to return unassigned tasks.
  • tg_id – The task group id.
  • period – One of all, week or month. The default is week which will return only the recent tasks created in the past week. Hence this is an option you will probably want to change to all in order to get all of the tasks.
  • start – The id of the first task to get.
  • limit – The number of tasks to return.
  • sort – The property to sort on. This can be one of id (the default) or scheduled the scheduled start of the task.
  • dirn – The direction of sort. One of asc or desc
  • tzTimezone
  • status – A comma separated list of status values. These can include new, accepted, late, unsent, unsubscribed, submitted, rejected, cancelled, deleted, pending, error, blocked. Refer to Task Lifecycle for details on how a task gets a status value.
Request Headers:
 
Status Codes:

Details of a Single Task

GET /api/v1/tasks/(task id)
Synposis:Get the details for a single task.

Example response:

https://sg.smap.com.au/api/v1/tasks

HTTP/1.1 200 OK
    Vary: Accept
    Content-Type: application/json

    {
      "tg_id": 234,
      "name": "cccc",
      "form_id": 17831,
      "survey_ident": "s1_17829",
      "assignee_ident": "neil",
      "generate_user": false,
      "from": "2019-11-09 01:44:34",
      "to": "2019-11-09 02:44:34",
      "location_trigger": "",
      "repeat": false,
      "repeat_count": 1,
      "guidance": "",
      "lon": 0,
      "lat": 0,
      "complete_all": true,
      "assign_auto": true,
      "show_dist": 0,
      "id": 2507,
      "tg_name": "Locate",
      "p_id": 0,
      "a_id": 2215,
      "survey_name": "2. Entèvyou paran oubyen gadyen (Parent Guardian) (1)",
      "blocked": false,
      "assignee": 3988,
      "assignee_name": "Neil Penman",
      "comment": "",
      "status": "late"
    }

:reqheader Authorization: basic
:statuscode 200: no error

Create a Task

POST /api/v1/tasks
Synposis:Create a task. The payload is a JSON object and can use the same attributes as returned by Details of a Single Task

Example request:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
   "tg_id": 226,
   "name": "Assign to neil",
   "form_ident": "s38_722",
   "assignee_ident": "neil",
   "initial_data_source": "none",
   "from": "2019-04-15 01:48:17",
   "to": "2019-04-15 02:48:17"
}