Share this page

# Manage the task board externally

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

In this topic:

## Entity relationship diagram

The following entities are relevant to this example. The diagram illustrates the relationships between these entities.

The following table shows the relations in the example.

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

## Example: Manage work item tasks

In this example, the goal is to get all tasks for work items assigned to a specific release, sprint, and team, using the REST API.

To manage work item tasks:

1. Use the GET operation to list all work items.

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

2. If there are many work items, you can sort the stories by ID number (order_by=id) and display only certain fields, such as id, name, team, release, sprint, subtype, and child_tasks.

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

   child_tasks shows 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
       }

3. Use the query clause to specify the IDs of the release, sprint, and team for which you want to see tasks. In this case, the relevant entities are as follows.

   Entity | Name | ID
   --- | --- | ---
   Release | Release2 | 1002
   Sprint | Sprint 2 | 1009
   Team | Realtors | 1002

   You need to see the tasks of user stories, defects, and quality stories, so you query also by these subtypes using the Or operator. Other work items, such as epics or features, are not needed.

   `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'))"`

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

   Response

       {
           "total_count": 1,
           "data": [
               {
                   "type": "work_item",
                   "owner": null,
                   "workspace_id": 1002,
                   "logical_name": "lv9w63zv5gkw4h3738g38j40m",
                   "tasks_number": 3,
                   "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
       }

4. Use the GET operation to list the existing tasks for this story.

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

   This story has three tasks.

       {
           "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 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": "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 credentials and track record",
                       "id": "1017"
                   }
               }
           ],
           "exceeds_total_count": false
       }

5. Using the POST operation, 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.

   Response

   Code 201 Created is returned.

       {
           "total_count": 1,
           "data": [
               {
                   "type": "task",
                   "id": "1013"
               }
           ],
           "exceeds_total_count": false
       }

6. Update some of the fields for this newly-created story, 1013. 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.

   Response

   Code 200 is returned.

       {

           "type": "task",

           "id": "1013"

       }

## See also

- REST API calls
- Common flows and ER diagrams

https://admhelp.microfocus.com Software Delivery Management 8942
Tips to improve your search results... OpenText™ Software Delivery Management Help Center OpenText™ Software Delivery Management Help 26.3 All View Local Help Center View Online Help Center Version: