Skip to content

Issue Hierarchy

Kiket epics and metadata definitions are now built into the core platform. This guide explains how to model parent/child relationships and define typed custom fields per project.

Hierarchy Essentials

  • Every issue can have a parent_id. Root issues automatically set root_id, hierarchy_depth, and hierarchy_path.
  • Parents must belong to the same organization and project as the child; cycles and self-references are blocked.
  • Moving an issue under a new parent recalculates all descendants.
  • UI highlights:
  • Autocomplete parent picker on the issue form.
  • Details sidebar shows parent links, child lists, and completion totals.
  • Kanban cards display child completion progress bars.
  • Lists across the app (issue index, board table, calendar popovers, search results, milestones) show ancestor breadcrumbs and child counts.
  • Issue index presents a collapsible tree view with inline metadata, keeping subtasks grouped under their parents.

Practical Patterns

  • Use epics (parent issues) to aggregate stories/tasks. Only issue types with Allow children enabled in Settings → Issue Types can act as parents; flip the toggle per type to control hierarchy depth.
  • API responses now include parent_id, root_id, and hierarchy_depth so external tools can mirror the structure.
  • Extensions can create or re-parent issues by sending those attributes in POST /api/v1/ext/issues.

Cross-View Controls

  • Apply the Hierarchy filter on issue lists or project boards to focus on top-level work or subtasks.
  • Collapse subtasks in the board table view with the "Hide subtasks" toggle while keeping parent summaries visible.
  • Bulk actions (web UI and API) include a permissioned "Change parent" operation that enforces organization + project boundaries.

Custom Field Definitions

Project admins define metadata once and reuse it across issues without touching the base schema.

  • Definitions live in issue_field_definitions and are scoped by project, organization, and optional issue_type.
  • Supported data types: string, text, number, boolean, enum.
  • Values persist in issue_field_values with typed columns. Access via issue.custom_fields in Ruby or JSON responses.
  • Default values populate new issues; required flags enforce completion before save.

Configuration Workflow

  1. Fork the definitions/<template>/.kiket repository that matches your process (e.g., definitions/kanban/.kiket) and add entries to custom_fields.yaml describing field key, label, type, required flag, enum options, helper text, and display order.
  2. Run your usual configuration sync task (e.g., the admin UI bulk importer or kiket sync) to persist definitions into issue_field_definitions.
  3. Issue forms render fields dynamically; templates can still inject overrides or defaults.
definitions/kanban/.kiket/custom_fields.yaml
custom_fields:
  - project: platform-v2
    issue_type: UserStory
    field_key: customer_impact
    label: Customer Impact
    data_type: enum
    required: true
    options: [low, medium, high, critical]
    default: medium
  - project: mvp-launch
    field_key: go_live_blocker
    data_type: boolean
    required: true
    helper_text: Must be true for any launch-stopping work.

API Notes

  • custom_fields values appear in both list and detail endpoints.
  • When creating/updating via API, pass a custom_fields hash alongside standard attributes. Invalid enum options or missing required fields return validation errors.

Seeds & Demo Data

Issue Type Definitions

  • Each organization owns a configurable catalog of types in issue_type_definitions. Admins can rename display labels, pick Bootstrap badge colors/icons, and decide which types allow children.
  • Defaults (Epic, Story, Task, Bug) are created automatically. You can add domain-specific types (e.g., Risk, Experiment) directly from the settings UI.
  • Deleting a type requires that no issues still reference its key. Deactivate unused types to hide them from selectors while keeping historic issues valid.
  • Kanban boards, calendars, and hierarchy tables read type metadata from data attributes, so badges always match the configured label/color without additional frontend work.

Workflow Status Metadata

  • Workflow states should declare metadata.label and metadata.color (Bootstrap variant) if you want polished status badges. Those values flow through everywhere—issue detail pages, cards, tables—without extra code.
  • If you omit metadata the UI falls back to a neutral badge and the titleized state key. No server-side list of statuses is hard-coded; scopes such as “active”/“final” discover states from the workflow definitions, so keep state categories accurate in your YAML.

The default seed script now creates: - Sample definitions (customer_impact, tech_component, release_train, go_live_blocker). - Multi-level parent/child networks for platform epics and MVP launch tasks (epic → task → subtask) so breadcrumbs and indentation appear right after seeding. - Example values so the dashboard and boards immediately surface roll-ups.

For deeper architectural notes or migration guidance, contact your customer success manager for the internal brief.