The following flow demonstrates how to check if a user story's tasks are completed, and if so, mark the user story as done.

In this topic:

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, quality stories, and user 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
Tasks	Work items	Tasks must be associated with one user story, quality story, or defect. User stories, quality stories, and defects are work items. 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.	stories defects
	Phases	Tasks must be associated with a phase.	phase
	Users	Tasks must have one owner.	owner
	Attachments	Tasks can have attachments.	attachments
Epics	Work items	Epics are subtypes of work_items. There is no field that relates back to the aggregate resource collection, work_items.
	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.
	Tasks	User stories can be associated with tasks.	story
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.
	Tasks	Quality stories can be associated with tasks.	story
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
	User stories and quality stories	Defects can be associated with user stories and quality stories.
	Tasks	Defects can be associated with tasks.	defect
Phases	Features, user stories, quality stories, and defects	Features, stories, and defects must be associated with a phase.	phase
Users	All work items	Epics, features, use stories, quality stories, and defects can be associated with an owner.	owner

Back to top

Flow

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

1. We want to see all stories that are still in-progress.

   To do this, we enter a query clause that lists only those work items whose subtype is story and whose phase is still in progress. Phase is a reference field, and we find the phase by id.

   We use the fields clause to control which fields are returned by the API call. Not all fields are returned automatically, so here we are going to be specific.  We want to see if any of the in-progress stories are associated with tasks, so we make sure to add tasks_number to our list of fields.

   GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/work_items?fields=phase,release,name,id,tasks_number,subtype&query="(subtype EQ ^story^;phase EQ {id EQ ^phase.story.inprogress^})"

2. For each story, we will check if the corresponding tasks are done.

   Here, we are checking the task corresponding to story 1019, because the previous API call showed that this story has one task, 1002, associated with it.

   This example also demonstrates the use of reference fields. We use the story reference field using the id to specify the story.

   GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/tasks?query="(story EQ {id EQ ^1019^ } )"

   Response 

   {
       "total_count": 1,
       "data": [
           {
               "type": "task",
               "workspace_id": 1002,
               "phase": {
                   "type": "phase",
                   "logical_name": "phase.task.completed",
                   "name": "Completed",
                   "index": 0,
                   "id": "1034"
               },
               "name": "This is my task.",
               "id": "1002"
           }
       ],
       "exceeds_total_count": false
   }

3. After looking at the response, we see that task 1002 did complete. We can now update the phase of the corresponding story, 1019, to done.

   PUT .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/work_items//1019/

   Payload 

   {

      "phase":{ 

           "type":"phase",

           "id":"phase.story.done"

          },

      "id":"1019"

   }

Back to top

See also:

• How to work with the REST API
• Common flows and ER diagrams