Advanced task creation

Default answers

Tasks can be created with an initial set of answers that will be visible to the first agent working on the task. These answers could be coming from a prior step in the overall workflow of your task, from existing annotations that you might already have for that task, or even from the output of a machine learning model that is providing annotations that will be revised by a human.

To create tasks with default answers, first coordinate with your Sama Project Manager to determine the workflow, correct format, and output name(s) to use. Then, when creating a task, include an output_<name> attribute with the default answer as the value.

Body:
This example will create a task with two attributes, img and caption with the appropriate values. It will also create a default answer of “blue” for the color output.

JSON

{
  "task": {
    "data": {
      "img": "http://static.samasource.org/samasource/images/logo.png",
      "caption": "SamaLogo",
      "output_color": "blue"
    }
  }
}

This example will create a task with two attributes, img and caption with the appropriate values. It will also create a default answer for the tagging image tagging output.

JSON

{
  "task": {
    "data": {
      "img": "http://static.samasource.org/samasource/images/logo.png",
      "caption": "SamaLogo",
      "output_tagging": [
        {
          "type": "point",
          "index": 1,
          "points": [[451, 150]],
          "tags": {
            "color": "blue"
          }
        },
        {
          "type": "rect",
          "index": 2,
          "points": [
            [545, 312],
            [996, 312],
            [545, 569],
            [996, 569]
          ],
          "tags": {
            "color": "green"
          }
        }
      ]
    }
  }
}

Task grouping

Tasks can be created in a Task Group so that all tasks in a group are served to the same agent. The Hub currently supports groups with up 300 tasks created via the task creation API. Before creating tasks in groups, please consult with your project manager to first configure grouping in Hub and discuss workflow and quality implications. Task grouping is often used to ensure consistency across a time series of images or a set of tasks that are somehow related.

In the Hub, tasks are grouped using a unique group identifier called Task Group ID. The Task Group ID is a normal task input that is marked as a Task Group ID input in the project settings UI by the project manager.

🚧

Before Creating Tasks via API

This input must be set up before you create tasks in groups via the API, otherwise tasks will not be served in groups.

To group multiple tasks together, all tasks in the group must have the same Task Group ID when created. This value cannot be updated after task creation. The Task Group ID must be stored under the input marked as the Task Group ID in the Hub. For example, an input named folder name could be marked as the Task Group ID. Each task created may have a string as a value under the folder name, input such as 0001 or blue. All tasks with the same value of blue will be served to the same agent.

When creating tasks one at a time, it is important to remember that if each task is created over a separate API call then the tasks in the same group should ideally be created quickly in a row of calls that are close together in time, in order to avoid splitting them into separate groups. If an agent begins work on a group of tasks but more tasks are added to that group later, there is a risk that the later tasks might get served to a different agent. You can use batch task creation to avoid this issue.

🚧

Uniqueness of Task Group ID

Task Group IDs should be unique for the whole project, but the hub does not validate that you are using a Task Group ID that has previously been used before. If you do that, there is a risk of tasks with the Task Group ID being reused being unintentionally grouped with tasks in the previous group with the same Task Group ID.

Task reservation

Given an agent id, tasks can be reserved to a specific agent during task creation. If a reserved task belongs to a Task Group, all other tasks in the Task Group(already reserved or not) will also be assigned to the specified agent.

Delete tasks

Please see the documentation of the delete tasks endpoint for information on how to delete tasks that have been created.

Create and submit

Some workflows have tasks being submitted when they are created. To do that, pass "submit": true in your request along with the task data. The submission will use the default answers that have been provided:

JSON

{
  "task": {
    "data": {
      "img": "http://static.samasource.org/samasource/images/logo.png",
      "caption": "SamaLogo",
      "output_color": "blue"
    },
    "submit": true,
    "duration": 60
  }
}

Please see create a task and submit a task for more information.