Task Resource

In Surpass, users are able to create, manage and complete Tasks. A Task is a way to manage a workload of users by assigning a specific task(s) to them. At current, there are two types of task that can be created in Surpass: General Task and a Review task. The Tasks module is currently Beta functionality, with new features and functionality being added in future releases.

General Task

General Tasks are intended to be used for administrative purposes and they act like a to do list for users to create, assign and manage tasks. An example of a General Task could be 'Call the people listed' as the Task title and then a list of people detailed in the task description. This could then be assigned to a user to complete independently of the Surpass system. 

Review Task

Review tasks require users to review items that have been added to an Item List. Users can 'Approve', 'Revise' or 'Reject' each item. This data is then collected and can be downloaded onto a spreadsheet at any time during the review timeline.

When creating a review task, you can assign multiple users to the task by searching for them and selecting them from the drop-down menu using the checkbox next to the user's name. After you then select a List to Review.

Tasks Resource

Using the Surpass API, you can retrieve, create and update all properties on a particular task. You can also retrieve particular information on the result of the Item Review task. Below we have listed the operations, the HTTP verbs and an example URL for the task resource within the Surpass API.
Operation HTTP Verb Example URL
Filter and Search GET https://...surpass.com:443/api/v2/Task?$top=10&$skip=10
Read (Individual by ID) GET/[Task Type]/{id} https://...surpass.com/api/v2/GeneralTask?reference={reference}&includeDetails=true
Create POST https://...surpass.com/api/v2/GeneralTask https://...surpass.com/api/v2/ItemReviewTask
Update PUT https://...surpass.com/api/v2/GeneralTask/{id} https://...surpass.com/api/v2/ItemReviewTask/{reference} https://...surpass.com/api/v2/ItemReviewTask/ItemReviewResult/{id}

Properties for the Task Resource
Listed below are the properties that can be returned using the Task Resource. As there are differing attributes to a General Task and an Item Review task, some of the properties listed below will only apply to the particular Task type, some will be common between the two and the properties returned will depend on the type of request that is sent. 
Property Name Type Description Order (GET) Filter (GET) Mandatory for Create (POST) Updatable (PUT)*
id int The unique Task ID, this is not the reference given to the Task.
reference string The reference given to the particular Task when it was created. X X X
href string The link to call the particular resource to return information about the particular task.
name string The name given to the Task when it was created. X X X
description string The description that was given to the task when it was initially created. X X
type string The type of task that has been created, this could read 'General' or 'ItemReview'. X
startDate date/time The date that the task is available to users. X
expiryDate date/time The last date that the task can be completed or accessed by users with the relevant task permission. X X
createDate date/time The date and time that the task was created.
creator collection Returns the user information for the particular Surpass user who created the Task. Returns most of the information contained in the User Resource.
executor collection Returns the user information for the particular Surpass user(s) who have been assigned to that particular Task. Returns most of the information contained in the User Resource. X X
status enum Returns information on the status of the task. This will be 'NotStarted', 'InProgress' or 'Complete'. If a Review task, the status will be shown per executor. X
itemList collection Returns information on the Item List that has been used for an Item Review task. X X
itemReviewResult collection When calling the Item Review Result API, this will show the id and href for the particular result of that item.
itemReviewResult / id num The ID for the Item Review Result.
itemReviewResult / href string The URL to call a specific Item Review Result
itemReviewResult / externalItemId num The Surpass Item ID
itemReviewResult / externalItemVersion num The version number of the item.
itemReviewResult / reviewResult enum The result given to an item as it has passed through a review. This will display 'Reject', 'Revise' or 'Approve'. X
itemReviewResult / comment string The comment left against an item by an executor after selecting the 'Revise' option. X
itemReviewResult / lastModifiedDate date/time The time and date that this item review result was last submitted by the executor. X
itemReviewResult / isFinalDecision boolean This indicates whether the task manager has made a final decision on the item under review. X

* Please see the section 'PUT Requests' below for more information about the variable conditions for updating properties.

GET Request and Return
The GET Task resource can be called directly by browsing to the URL, any required parameters such as $filter, $orderBy, $skip and $top would need to form part of the URL that is sent. You can provide specific IDs for both the Below we have provided examples of JSON and XML responses that would be returned from the Surpass API when requesting the GET method for the Task resource, this is for both General Tasks and Item Review Tasks.

GET ItemReviewResult
Calling the get ItemReviewResult API will allow you to retrieve information on an Item Review and the result that each item was given along with comments left by the reviewer when voting. When calling this resource you will receive a link to an individual Item Review Result, which will contain information relating to the result. An example is provided below:

  "count": null,
  "top": null,
  "skip": null,
  "pageCount": null,
  "nextPageLink": null,
  "prevPageLink": null,
  "response": [
      "id": 7534,
      "href": "https://...surpass.com/api/v2/ItemReviewTask/ItemReviewResult/7534",
      "externalItemId": 7484,
      "externalItemVersion": "4",
      "externalSubjectId": 213,
      "reviewResult": 0,
      "comment": "sample string 1",
      "lastModifiedDate": "2018-08-29T12:12:18.937",
      "executor": {
        "id": 184,
        "reference": "taskman",
        "href": "https://...surpass.com/api/v2/User/184"
      "isFinalDecision": true,
      "isFlagged": false
  "errors": null,
  "serverTimeZone": "GMT Standard Time"

POST Request and Return
The POST Task method requires the attributes listed above to be submitted as part of the body of the HTTPS request. This can be submitted in either JSON or XML format. The content-type used will need to be submitted as part of the header of the request. An example of the header and body of the request (for both formats) can be found below. Both examples include the POST requests for General and Item Review Tasks.

PUT Requests
You can send PUT requests to the GeneralTask and ItemReviewTask resources to update various options of tasks at the 'Not started' and 'In progress' states.

For 'Not started' tasks, you can update:

  • Name (name, string)
  • Reference (reference, string)
  • Description (description, string)
  • List to Review (itemList, collection) [ItemReviewTask only]
  • Assignee(s) (executor, collection)
  • Start Date (startDate, date/time)
  • End Date (endDate, date/time)

For 'In progress' tasks, you can update:

  • Name (name, string)
  • Reference (reference, string)
  • Description (description, string)
  • Assignee(s) (executor, collection)
  • End Date (endDate, date/time)

You can also update certain information by sending a PUT request to ItemReviewResult. Updatable properties include:

  • Review Result (reviewResult, int)
  • Comment (comment, string)
  • Flag (isFlagged, boolean)
  • Final decision (isFinalDecision, boolean) [Task managers only]

Feedback and Knowledge Base