Organise Work Items into a Hierarchy

Work items can be nested using the parent_work_item_id field to create a tree structure. This guide explains the hierarchy rules, how to set parent–child relationships, and what protections are in place.

Type hierarchy rules

Not every work item type can be a child of every other type. The allowed parent → child relationships are:

Parent type	Allowed child types
EPIC	EPIC, ISSUE, TASK, BUG
ISSUE	TASK, SUB_TASK, BUG
TASK	SUB_TASK
BUG	SUB_TASK
SUB_TASK	(none — cannot have children)

If you attempt to create a relationship that violates these rules, the request will be rejected.

Set a parent when creating a work item

Include parent_work_item_id in the create request:

POST /rest/v1/t_ppm_work_items

{
  "project_id": "a1b2c3d4-...",
  "work_item_type": "TASK",
  "work_item_name": "Implement API endpoint",
  "parent_work_item_id": "e5f6a7b8-..."
}

note

When a parent is specified, the child inherits the parent's project_id automatically. You can omit project_id from the request if the parent already belongs to the correct project.

Move a work item to a different parent

Update the parent_work_item_id:

PATCH /rest/v1/t_ppm_work_items?id=eq.<work-item-id>

{
  "parent_work_item_id": "<new-parent-id>"
}

To make a work item a root-level item (no parent), set the field to null:

PATCH /rest/v1/t_ppm_work_items?id=eq.<work-item-id>

{
  "parent_work_item_id": null
}

Cycle prevention

The system prevents circular parent chains. For example, if A → B → C exists, you cannot set C's parent to A. The request will be rejected with an error.

The cycle check walks up the ancestor chain from the proposed parent. If it encounters the work item being updated, the operation is blocked.

Project consistency

All work items in a parent–child chain must belong to the same project. When you assign a parent:

• If you omit project_id, the child inherits the parent's project.
• If you supply a project_id that differs from the parent's project, the request is rejected.

Example: building a hierarchy

1. Create an epic (root level):

   POST /rest/v1/t_ppm_work_items

   {
     "project_id": "a1b2c3d4-...",
     "work_item_type": "EPIC",
     "work_item_name": "Onboarding Redesign"
   }

2. Add an issue under the epic:

   POST /rest/v1/t_ppm_work_items

   {
     "project_id": "a1b2c3d4-...",
     "work_item_type": "ISSUE",
     "work_item_name": "Build welcome screen",
     "parent_work_item_id": "<epic-id>"
   }

3. Add tasks under the issue:

   POST /rest/v1/t_ppm_work_items

   {
     "project_id": "a1b2c3d4-...",
     "work_item_type": "TASK",
     "work_item_name": "Design mockups",
     "parent_work_item_id": "<issue-id>"
   }

4. Add a sub-task under the task:

   POST /rest/v1/t_ppm_work_items

   {
     "project_id": "a1b2c3d4-...",
     "work_item_type": "SUB_TASK",
     "work_item_name": "Create Figma wireframe",
     "parent_work_item_id": "<task-id>"
   }

The resulting hierarchy:

EPIC: Onboarding Redesign
  └─ ISSUE: Build welcome screen
       └─ TASK: Design mockups
            └─ SUB_TASK: Create Figma wireframe

Query children of a work item

To list all direct children of a work item:

GET /rest/v1/t_ppm_work_items?parent_work_item_id=eq.<parent-id>&order=display_order.asc