Manage the task board externally

The following flow demonstrates how to manage tasks on the task board using the REST API.

Entity relationship diagram

We need to access the following entities for this flow, and understand the relationships between these entities.

Entity relationship diagram for managing tasks on the task board externally.

The following shows the relations in the flow.

Entity Relationships in this flow Description of relationship Reference / relationship fields
Work items Epics, features, defects, user stories, and quality stories This aggregate resource collection represents types of work items, including epics, features, defects, user stories, and quality stories. subtype
Work items Tasks Work items can be associated with tasks. child_task
Work items Releases Work items can be associated with releases. release
Tasks Work items

Tasks must be associated with one quality story, user story, or defect.

Tasks cannot be associated with other work items, such as epics and features.

User stories, quality stories, and defects can be associated with multiple tasks.

story

defect

Tasks Phases Tasks must be associated with a phase. phase
Tasks Users Tasks must have one owner. owner
Tasks List nodes The type of each task can be referenced by querying the list_node resource collection. item_type
Epics Work items

Epics are subtypes of work_items.

There is no field that relates back to the aggregate resource collection, work_items.

None
Epics Features

Epics can be associated with features.

None
Features Work items

Features are subtypes of work_items.

There is no field that relates back to the aggregate resource collection, work_items.

None
Features

Epics

Features can be associated with epics.

parent
Features

Stories, and defects

Features can be associated with user stories, quality stories, and defects.

None
User stories Work items

User stories are subtypes of work_items.

There is no field that relates back to the aggregate resource collection, work_items.

None
User stories Features

User stories can be associated with features.

parent
User stories Defects

User stories can be associated with defects.

None
Quality stories Work items

Quality stories are subtypes of work_items.

There is no field that relates back to the aggregate resource collection, work_items.

None
Quality stories Features

Quality stories can be associated with features.

parent
Quality stories Defects

Quality stories can be associated with defects.

None
Defects Work items

Defects are subtypes of work_items.

There is no field that relates back to the aggregate resource collection, work_items.

None
Defects Features

Defects can be associated with features.

parent
Defects Stories

Defects can be associated with stories.

None
Phases Features, quality stories, user stories, and defects Features, quality stories, user stories, and defects must be associated with a phase. phase
Users All work items Epics, features, quality stories, user stories, and defects can be associated with an owner. owner
Releases All work items Epics, features, quality stories, user stories, and defects can be associated with an owner. release
Releases Sprints Sprints are associated with releases. release

Back to top

Flow:  Retrieve, create, and update work item tasks for a release, sprint, and team

The goal of this flow is to get all tasks for work items assigned to a specific release, sprint, and team.

Let's create the REST API call step-by-step.

  1. As a first step, we list all work items.

    GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/work_items

  2. If we have many work items, it might be helpful to sort the stories by ID number (order_by=id) and to display only certain fields, such as id, name, team, release, sprint, subtype, and child_tasks.

    subtype shows us if the work item is an entity such as defect or user story.

    child_tasks shows us if the work item is associated with tasks.

    GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/work_items?order_by=id&fields=id,name,team,release,sprint,subtype,child_tasks

  3. Now we use the query clause to specify the IDs of the release, sprint, and team for which we want to see tasks. In our case, we want to see:

    • Release2, whose ID is 1002

    • Sprint 2, whose ID is 1009

    • Realtors, whose ID is 1002

    Note that we want to see the tasks of user stories, defects, and quality stories, so we query also by these subtypes using the Or operator. We do not want to see other work items, such as epics or features.

    GET .../api/shared_spaces/<space_id>/work_items?fields=name,tasks_number,owner,id, release,sprint,team&query="(release={id=1002};sprint={id=1009};team={id=1002};(subtype='story'||subtype='defect'||subtype='quality_story'))"

    We only have one work item for this combination of release, sprint, and team, which is user story 1017.

  4. Let's see the existing tasks for this story.

    GET .../api/shared_spaces/<space_id>/tasks?query="story={id EQ ^1017^}"

    This story has three tasks.

  5. Let's add a new task to this story.

                                
                                    POST .../api/shared_spaces/<space_id>/tasks
                                
                            
    {"data":
       [   
          {   "item_type":
                    {"type":"list_node",
                     "id":"list_node.task_item_type.test"},
              "phase":
                    {"type":"phase",
                    "id":"phase.task.new"},
              "story":
                    {"type":"work_item",
                    "id":"1017"},
              "owner":
                    {"type":"workspace_user",
                    "id":"1003"},
              "name":"Test that it all works."
          }
       ]
    }

    A task with ID 1013 is created.

  6. Let's update some of the fields for this newly-created story, 1013. We will change the name, change the owner, update the phase, and define how many hours were already invested on the task.

    PUT.../api/shared_spaces/<space_id>/tasks/1013
    {
        "name":"Check that the background check matches a manual check.",
        "owner":{"type":"workspace_user","id":"1005"},
        "invested_hours":10,
        "phase":{"type":"phase","id":"phase.task.inprogress"},
        "id":"1013"
    }
    

    A task with ID 1013 is created.

Back to top

See also: