Manage the task board externally

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

Areas: Work items, Tasks

Entity relationship diagram

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

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
	Tasks	Work items can be associated with tasks.	child_task
	Releases	Work itemss 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
	Phases	Tasks must be associated with a phase.	phase
	Users	Tasks must have one owner.	owner
	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.
Epics	Features	Epics can be associated with features.
Features	Work items	Features are subtypes of work_items. There is no field that relates back to the aggregate resource collection, work_items.
	Epics	Features can be associated with epics.	parent
	Stories, and defects	Features can be associated with user stories, quality stories, and defects.
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.
	Features	User stories can be associated with features.	parent
	Defects	User stories can be associated with defects.
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.
	Features	Quality stories can be associated with features.	parent
	Defects	Quality stories can be associated with defects.
Defects	Work items	Defects are subtypes of work_items. There is no field that relates back to the aggregate resource collection, work_items.
	Features	Defects can be associated with features.	parent
	Stories	Defects can be associated with stories.
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

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.

As a first step, we list all work items.

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

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

Response

{
    "total_count": 14,
    "data": [
        {
            "type": "work_item",
            "workspace_id": 1002,
            "logical_name": "5ge4jg0m29olmukp11l05qn7m",
            "subtype": "story",
            "release": {
                "type": "release",
                "activity_level": 0,
                "name": "Release2",
                "id": "1002"
            },
            "sprint": {
                "type": "sprint",
                "end_date": "2018-07-14T12:00:00Z",
                "name": "Sprint 1",
                "id": "1008",
                "start_date": "2018-07-01T12:00:00Z"
            },
            "name": "Access credit history",
            "id": "1013",
            "team": {
                "type": "team",
                "name": "Processers",
                "id": "1001"
            }
        },
        {
            "type": "work_item",
            "workspace_id": 1002,
            "logical_name": "k3wxj59g07oz9tnx77lpg62vg",
            "subtype": "story",
            "release": {
                "type": "release",
                "activity_level": 0,
                "name": "Release1",
                "id": "1001"
            },
            "sprint": {
                "type": "sprint",
                "end_date": "2018-04-11T12:00:00Z",
                "name": "Sprint 1",
                "id": "1001",
                "start_date": "2018-03-29T12:00:00Z"
            },
            "name": "Access public prison records",
            "id": "1012",
            "team": {
                "type": "team",
                "name": "Processers",
                "id": "1001"
            }
        },
        {
            "type": "work_item",
            "workspace_id": 1002,
            "logical_name": "0nrzq94z3ml10ax1zgx7nj48g",
            "subtype": "defect",
            "release": {
                "type": "release",
                "activity_level": 0,
                "name": "Release2",
                "id": "1002"
            },
            "sprint": {
                "type": "sprint",
                "end_date": "2018-07-14T12:00:00Z",
                "name": "Sprint 1",
                "id": "1008",
                "start_date": "2018-07-01T12:00:00Z"
            },
            "name": "Approval letters went out to rejected customers if customer was under 50 and had an account at our bank",
            "id": "1016",
            "team": {
                "type": "team",
                "name": "Processers",
                "id": "1001"
            }
        },
        {
            "type": "work_item",
            "workspace_id": 1002,
            "logical_name": "owlkqogl702xohdw5eoxrjy81",
            "subtype": "feature",
            "release": null,
            "sprint": null,
            "name": "Approval process",
            "team": null,
            "id": "1009"
        },
        {
            "type": "work_item",
            "workspace_id": 1002,
            "logical_name": "work_item.root",
            "subtype": "work_item_root",
            "release": null,
            "sprint": null,
            "name": "Backlog",
            "team": null,
            "id": "1001"
        },
        {
            "type": "work_item",
            "workspace_id": 1002,
            "logical_name": "d79yjmn2v78kfne3y0mw6wpo4",
            "subtype": "story",
            "release": {
                "type": "release",
                "activity_level": 0,
                "name": "Release3",
                "id": "1003"
            },
            "sprint": null,
            "name": "Check if customer ever filed bankruptcy",
            "id": "1014",
            "team": {
                "type": "team",
                "name": "Processers",
                "id": "1001"
            }
        },
        {
            "type": "work_item",
            "workspace_id": 1002,
            "logical_name": "5ge4jg08wk3mns9lng1n8qn7m",
            "subtype": "defect",
            "release": {
                "type": "release",
                "activity_level": 0,
                "name": "Release2",
                "id": "1002"
            },
            "sprint": {
                "type": "sprint",
                "end_date": "2018-07-28T12:00:00Z",
                "name": "Sprint 2",
                "id": "1009",
                "start_date": "2018-07-15T12:00:00Z"
            },
            "name": "Could not log into prison service app",
            "id": "1015",
            "team": {
                "type": "team",
                "name": "Processers",
                "id": "1001"
            }
        },
        {
            "type": "work_item",
            "workspace_id": 1002,
            "logical_name": "r482j2xlkvvo9alpelvxk6oex",
            "subtype": "feature",
            "release": null,
            "sprint": null,
            "name": "Credit and background checks",
            "team": null,
            "id": "1011"
        },
        {
            "type": "work_item",
            "workspace_id": 1002,
            "logical_name": "5x8ljxv018r95uk83ovrm67r9",
            "subtype": "epic",
            "release": null,
            "sprint": null,
            "name": "Foreclosures",
            "team": null,
            "id": "1008"
        },
        {
            "type": "work_item",
            "workspace_id": 1002,
            "logical_name": "eo4wqw8dgnld1hywkxwggqgvz",
            "subtype": "feature",
            "release": null,
            "sprint": null,
            "name": "Policy terms and rates",
            "team": null,
            "id": "1010"
        },
        {
            "type": "work_item",
            "workspace_id": 1002,
            "logical_name": "3zxeql5r78w8gaxyg11rg6vm4",
            "subtype": "epic",
            "release": null,
            "sprint": null,
            "name": "Processing",
            "team": null,
            "id": "1007"
        },
        {
            "type": "work_item",
            "workspace_id": 1002,
            "logical_name": "xeyrqzmlexm4gi4w9zxmw6z1g",
            "subtype": "epic",
            "release": null,
            "sprint": null,
            "name": "Realtors",
            "team": null,
            "id": "1006"
        },
        {
            "type": "work_item",
            "workspace_id": 1002,
            "logical_name": "4v9xj0xpvzm5nbo40dkwkj71z",
            "subtype": "epic",
            "release": null,
            "sprint": null,
            "name": "Sales",
            "team": null,
            "id": "1005"
        },
        {
            "type": "work_item",
            "workspace_id": 1002,
            "logical_name": "lv9w63zv5gkw4h3738g38j40m",
            "subtype": "story",
            "release": {
                "type": "release",
                "activity_level": 0,
                "name": "Release2",
                "id": "1002"
            },
            "sprint": {
                "type": "sprint",
                "end_date": "2018-07-28T12:00:00Z",
                "name": "Sprint 2",
                "id": "1009",
                "start_date": "2018-07-15T12:00:00Z"
            },
            "name": "Verify realtor's credentials and track record",
            "id": "1017",
            "team": {
                "type": "team",
                "name": "Realtors",
                "id": "1002"
            }
        }
    ],
    "exceeds_total_count": false
}

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.

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.

Response

{
    "total_count": 3,
    "data": [
        {
            "type": "task",
            "owner": null,
            "creation_time": "2018-03-29T13:09:19Z",
            "phase": {
                "type": "phase",
                "activity_level": null,
                "logical_name": "phase.task.new",
                "name": "New",
                "index": 100,
                "id": "phase.task.new"
            },
            "version_stamp": 1,
            "item_type": null,
            "release": "Release2",
            "author": {
                "type": "workspace_user",
                "activity_level": 0,
                "full_name": "Marta Berman",
                "name": "marta",
                "id": "1002"
            },
            "description": null,
            "remaining_hours": 0,
            "workspace_id": 1002,
            "invested_hours": 0,
            "is_draft": false,
            "name": "Check accreditation and licensing database",
            "estimated_hours": 0,
            "progress": "{\"storyId\":1011,\"tasksInvestedHoursSumTotal\":0,\"tasksEstimatedHoursSumTotal\":0,\"tasksRemainingHoursSumTotal\":0}",
            "id": "1011",
            "last_modified": "2018-03-29T13:09:19Z",
            "story": {
                "type": "story",
                "name": "Verify realtor's credentials and track record",
                "id": "1017"
            }
        },
        {
            "type": "task",
            "owner": null,
            "creation_time": "2018-03-29T13:09:19Z",
            "phase": {
                "type": "phase",
                "activity_level": null,
                "logical_name": "phase.task.new",
                "name": "New",
                "index": 100,
                "id": "phase.task.new"
            },
            "version_stamp": 1,
            "item_type": null,
            "release": "Release2",
            "author": {
                "type": "workspace_user",
                "activity_level": 0,
                "full_name": "Marta Berman",
                "name": "marta",
                "id": "1002"
            },
            "description": null,
            "remaining_hours": 0,
            "workspace_id": 1002,
            "invested_hours": 0,
            "is_draft": false,
            "name": "List references",
            "estimated_hours": 0,
            "progress": "{\"storyId\":1012,\"tasksInvestedHoursSumTotal\":0,\"tasksEstimatedHoursSumTotal\":0,\"tasksRemainingHoursSumTotal\":0}",
            "id": "1012",
            "last_modified": "2018-03-29T13:09:19Z",
            "story": {
                "type": "story",
                "name": "Verify realtor's credentails and track record",
                "id": "1017"
            }
        },
        {
            "type": "task",
            "owner": null,
            "creation_time": "2018-03-29T13:09:19Z",
            "phase": {
                "type": "phase",
                "activity_level": null,
                "logical_name": "phase.task.new",
                "name": "New",
                "index": 100,
                "id": "phase.task.new"
            },
            "version_stamp": 1,
            "item_type": null,
            "release": "Release2",
            "author": {
                "type": "workspace_user",
                "activity_level": 0,
                "full_name": "Marta Berman",
                "name": "marta",
                "id": "1002"
            },
            "description": null,
            "remaining_hours": 0,
            "workspace_id": 1002,
            "invested_hours": 0,
            "is_draft": false,
            "name": "Resume attachment feature",
            "estimated_hours": 0,
            "progress": "{\"storyId\":1010,\"tasksInvestedHoursSumTotal\":0,\"tasksEstimatedHoursSumTotal\":0,\"tasksRemainingHoursSumTotal\":0}",
            "id": "1010",
            "last_modified": "2018-03-29T13:09:19Z",
            "story": {
                "type": "story",
                "name": "Verify realtor's credentails and track record",
                "id": "1017"
            }
        }
    ],
    "exceeds_total_count": false
}

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.

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.

Manage the task board externally

Entity relationship diagram

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

Send Help Center Feedback