Creating projects and hierarchy

How to create a project with the CLI, and how to check and change its hierarchy rules — which issue types can sit at the top and which types can go under which. Hierarchy rules differ per project, even between projects created from the same template, so look them up every time.

Replace ACME in the examples with your own project key.

Create a project

A project is a boundary of work. If it has its own owners, schedule, and definition of done, create a new project. If it is a branch of the same effort, express it in that project’s hierarchy. Creating a project per topic scatters issue keys so search fragments, and computes progress separately so nobody can see where the whole effort stands.

dillie --agent project projects create --data '{"name":"New Service","key":"ACME","template":"agile-scrum"}'

• template — agile-scrum creates an agile project that uses sprints; agile-kanban creates an agile project with sprints turned off. If you omit it, the project gets a plain list with no issue type field, no hierarchy, and no status transition rules.
• includeInitiative — meaningful only with an agile template, and true by default. When true, the initiative type and the initiative → epic rule are added, and initiatives can also sit at the top level. Either way, types such as epic, story, task, and bug can sit at the top level.
• key — 2 to 10 uppercase letters and digits, starting with a letter (^[A-Z][A-Z0-9]{1,9}$). It becomes the prefix of every issue key (ACME-123).

Set the key yourself. If you omit it, a key is derived from the name; if no key can be built from Latin letters in the name (for example, a Korean name), the project is created without issue keys. A key must be unique within the workspace; a duplicate is rejected with 409.

You can change the key later, but doing so rewrites every issue key in the project with the new prefix. Old issue keys written in commit messages or documents no longer point to their items, so pick a short key you will not change.

Create in another workspace

A project is created in the currently selected workspace. To create it in another workspace for one run only, specify it with --workspace or DILLIE_WORKSPACE (CLI 0.21.0 or later).

dillie --agent --workspace <tenantId> project projects create --data '{"name":"New Service","key":"ACME","template":"agile-scrum"}'

Keys are unique only within a workspace, so creation succeeds even if another workspace has the same key. If you work across several workspaces, check the key in all of them before creating (CLI 0.21.0 or later).

dillie --agent project projects list --all-workspaces

Both features require a session signed in with the default dillie login method (browser or --device). The full rules for choosing a workspace are in Working with the dillie CLI — Choose a workspace.

Check a project’s hierarchy

Which types can be top level, and which types may be children of which, is that project’s configuration. Do not guess from general agile practice or from another project.

dillie --agent describe ACME --fields fieldMap

When the response has a hierarchy block, it holds three things.

• agileMode — whether agile is on. The server enforces the rules below only when it is true.
• topLevelAllowed — types that can be created without a parent
• allowedChildren — the permitted child types for each parent type

describe is a summary. It omits the hierarchy block when the project has no workflow settings or its hierarchy table is empty, so a missing block alone does not tell you whether rules exist. If the block is missing, or you need to confirm agileMode, look up the rules directly as in the next section.

Look up the hierarchy rules directly

The source of truth for hierarchy and status transition rules is workProfile in the list details.

dillie --agent project lists get ACME

workProfile is one of three things.

When agileMode is true, read these keys from config.

• hierarchy — parent type → list of permitted child types
• top_level_allowed — types that can be created without a parent
• initial and transitions — starting statuses and status transition rules. See Recording progress and moving status — Look up status values.

Turning agile off does not clear the values in config. Do not read a value’s presence as a rule — check agileMode alongside it.

Fill in issue types

If the fields in the describe response include a field whose role is ISSUE_TYPE, give every item an issue type. The usable values are the option ids in that field’s options. Sending issueType to a project without that field is rejected.

Hierarchy rules apply only to items that have an issue type. An item created without a type passes unchecked, leaving an item with a parent-child link but no type. The response makes it look as if the hierarchy was built, so read the item back after creating it and confirm the type is set.

dillie --agent project tasks get ACME ACME-1

The keys in the response values are field ids. Match them against fields[].id from describe to find the issue type field’s value.

The check runs not only on creation but also on updates, bulk updates, and reordering. Changing a parent’s type re-checks its existing children too. So if you create an item without a type and add one later, it can be rejected at that point.

Under an item whose type is not a parent in the hierarchy table (hierarchy), you cannot add a child that has a type.

Create a hierarchy in one request

Instead of creating a parent, getting its id, and then creating the child, reference an earlier item as the parent within one request.

dillie --agent project tasks bulk-create ACME --data '[
  {"clientId":"e1","values":{"title":"Payments overhaul","issueType":"epic","_description":"## Background\n…"}},
  {"parentClientId":"e1","values":{"title":"Retry card payments","issueType":"story","_description":"## Background\n…"}}
]'

• clientId is a temporary name used only within this request. parentClientId must be the clientId of an item that appears earlier in the same batch, and cannot be combined with parentItemId.
• Set the issue type per item with values.issueType. The --issue-type option overwrites every item with the same type, so do not use it when mixing levels.
• The response’s createdRefs returns { id, issueKey, clientId } for each item. Use it to match which item became which issue key.

A bulk create is applied entirely or not at all. Before sending, --dry-run shows the item count and the first few items. See Finding items and bulk cleanup — Create in bulk.

Change the hierarchy

Change the hierarchy rules of an agile project with lists update-hierarchy. First read the current rules as in Look up the hierarchy rules directly.

dillie --agent project lists update-hierarchy ACME \
  --data '{"merge":true,"hierarchy":{"story":["subtask","e2e","task"]}}'

Only what you send of hierarchy and topLevelAllowed changes; what you leave out stays as it is. merge decides how the values you send are applied.

merge: true does not append to a child list. If you send a parent type that already exists, that parent’s child list becomes what you sent. To add one child, as in the example above, list the existing children as well. Conversely, a child you leave out of a parent you send is dropped. What merge: true cannot remove are the parent types you do not send and the allowed top-level types — to remove those, send the complete set you want with merge: false.

• Values are option ids of the issue type field, not labels. An id that is not in that field is rejected.
• Rules that make a type its own child or create a cycle are rejected.
• The response is the result after the change (agileMode and config). Use it to confirm the table is what you intended.

Troubleshooting

How to read status codes in general is covered in Working with the dillie CLI — Troubleshooting.

The project cannot be found

The error message tells you which workspace was searched. If the project is in another workspace, find it with projects list --all-workspaces and run again with --workspace pointing to that workspace.

A project with that key already exists (409)

A project with the same key exists in that workspace. Choose a different key.

Blocked by a hierarchy rule

The rejection is a 400, and the message names the parent type and child type that were blocked. If creating without a parent was blocked, (top-level) appears in the parent position. The same combination will not pass if sent again. Read the permitted combinations as in Look up the hierarchy rules directly and fix the parent or the type.

Changing the hierarchy is rejected

• Agile is off, or the project has no workflow settings. The message does not give a specific reason in this case, so check workProfile with lists get.
• You sent an option id that is not in the issue type field — for example, initiative to a project created without initiatives.
• You sent rules that create a self-loop or a cycle.