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 Tasks API 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
  • tz – The timezone for example Australia/Brisbane. All date time and date answers will be returned in this time zone.
  • 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. The payload is sent as x-www-form-urlencoded content with a key of “task”. Use Details of a Single Task API call to get templates for the data that can be posted.

Example request:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/x-www-form-urlencoded

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

Example request 2:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/x-www-form-urlencoded

{
  "tg_id": 4d": 4,
  "name": "xxxx : A project : geopoint",
  "form_id": 37,
  "survey_ident": "s1_37",
  "assignee_ident": "neil",
  "generate_user": false,
  "initial_data_source": "task",
  "update_id": "uuid:7df6eb5f-c4b0-4837-9063-09653078782a",
  "from": "2020-02-06 01:37:42",
  "repeat": false,
  "repeat_count": 0,
  "lon": 153.013277,
  "lat": -27.445506,
  "complete_all": true,
  "assign_auto": false,
  "initial_data": {
    "values": {
      "q1": "hello 2",
      "instanceid": "uuid:7df6eb5f-c4b0-4837-9063-09653078782a"
    },
    "point_geometry": {
      "coordinates": [
        153.013277,
        -28.445506
      ],
      "altitude": 0,
      "accuracy": 0,
      "type": "Point"
    }
  },
  "show_dist": 0,
  "id": 9,
  "tg_name": "xxxx",
  "p_id": 0,
  "a_id": 9,
  "survey_name": "geopoint",
  "blocked": false,
  "assignee": 2,
  "assignee_name": "neil",
  "status": "accepted"
}

In this second example the task “id” is specified hence the existing task will be updated. Also this example includes initial data for form to use.

Example Response:

Details on the task created as well as a link to a webform that can complete the task are returned

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

{
  "task": {
    "tg_id": 4,
    "name": "xxxx : A project : geopoint",
    "form_id": 37,
    "survey_ident": "s1_37",
    "generate_user": false,
    "initial_data_source": "task",
    "from": "2020-02-06 01:37:42",
    "repeat": false,
    "repeat_count": 0,
    "lon": 153.013277,
    "lat": -27.445506,
    "complete_all": true,
    "assign_auto": false,
    "initial_data": {
        "values": {
            "q1": "hello 2",
            "instanceid": "uuid:7df6eb5f-c4b0-4837-9063-09653078782a"
        },
        "point_geometry": {
            "coordinates": [
                153.013277,
                -28.445506
            ],
            "altitude": 0.0,
            "accuracy": 0.0,
            "type": "Point"
        }
    },
    "show_dist": 0,
    "id": 13,
    "tg_name": "xxxx",
    "p_id": 0,
    "a_id": 0,
    "survey_name": "geopoint",
    "blocked": false,
    "assignee": 0,
    "status": "new"
  },
    "links": {
      "webform": "https://ubuntu1804.smap.com.au/webForm/s1_37?taskkey=13&assignment_id=0"
  }
}