# User Problem

## User

* Project manager

* Project member

* Administrator


## Problem

In some scenarios, users are required to manage complex information that naturally fits into a hierarchical structure. e.g.

* **Real Estate:** Property -> Buildings -> Floors -> Rooms

* **Geographical Data:** Continent -> Country -> Federal State -> County

* **Organizational Structures:** Organization -> Department -> Team -> User

* **Product Components:** Parts list of a machine


Currently, only flat lists are available. Flat lists can be challenging in managing and navigating through this information. Without a hierarchical view, it becomes difficult to maintain, locate, and work with these datasets effectively.

## Pain

* Users, particularly project managers and project members, need a way to save and organize information in work packages using hierarchical structures.

* A hierarchical representation would allow them to focus on relevant subsets of information, making navigation more intuitive and information retrieval easier.


# Business Case

## Solution

The solution involves implementing a custom field of type "hierarchy" to allow users to manage and navigate information in a structured, multi-level format

### Summary

* The admin needs to be able to

* Create a custom field of type "hierarchy" (on admin level)

* Set Begin of the insertionitemsEnd of the insertion Begin of the deletion valuesEnd of the deletion (on admin level)

* Items in that hierarchical structure should be able to have optionally an abbreviation e.g.

* Headquarters (HQ) -> 1 Floor (1F) -> Room 2 (2) **in short:** "HQ -> 1F -> 2"

* Europe (EU) -> Germany (DE) -> Bavaria (BY) -> Weißenburg (WUG) **in short:** "EU -> DE -> BY -> WUG" Begin of the insertion

* item label and item short name must be unique within the same level of the hierarchy

End of the insertion Begin of the deletion

End of the deletion * Project admins need to be able to

* enable / disable this custom field on project level.

* Other custom fields should to be able to access the value of the selected item from the custom field of type hierarchy.

* It should be also possible to access partial information e.g. the parent node, short and long form of a value


###

### Admin Interface

* Create nodes

* Set parent (and be able to change parent afterwards)

* Navigate to a specific node

* Validations / Services / Contracts

* Data structures

* Path / Breadcrumb

* Long form

* short form


### API

* Add to work package representer

* Query

* on work packages (start with this one)

* on users

* on groups

* on projects

* Filter on

* Operators

* all assigned to a certain node

* all assigned to a certain node and its descendents

* Allowed values

* Group by

* WP/project/users/groups form

* link to typeahead backend

* Values endpoint

* Typeahead for value searching

* drill down

* get all children for node

* get all as tree (needed for quick solution with ng-select)

* Documentation


### Angular Frontend

* Render values

* In WP full view

* In WP table column

* Select values

* ng-select based (browsing the hierarchy)

* single select

* multi select

* search on path (typeahead) (searching the hierarchy, )


### **Acceptance criteria**

* When ever we work with the hierarchy, it is not necessary to load the full hierarchy as hierarchies can easily bigger than 1k elements.

* Administration

* create such an attribute

* set to single- or multi-select

* create nodes one by one

* modify parent

* delete node

* rename node

* provide acronym per node

* Interface for non admin, e.g. in a work package form

* A selected value can have multiple value representation

* Node ID

* Full path long: Europe -> Germany -> Bavaria

* Full path short: EU-DE-BY

* Selected long: Bavaria

* Selected short: BY

* Selection

* Select a leaf (e.g. Bavaria)

* Select a node (e.g. Germany)

* Allow multi-selection

* Filters

* By node or leaf (e.g. Bavaria only, Germany only)

* By node with descendants (e.g. Germany, including all federal states)


## Out of Scope for iteration 1

* Drill down selector. A component like a location/file picker. The user can click on nodes to go one level deeper on the hierarchy.

* Manual sort order. For the time being elements are sorted alphabetically per node.

* Multiple changes to the hierarchy get saved in one transaction instead of multiple ones.

* Allow the same custom field to be active on work packages AND projects, or any other entity type we allow custom fields for.


##

## Next iteration

* The next iteration would be extending the hierarchical custom field with a drill down selector. This is needed for selecting an item within a large amounts of hierarchical items. This needs clarification what drill down pattern would be the most accepted by users Folder-Style vs. a small + button on a tree structure


# Launch and Growth

## Measures

* tbd


## Messaging

<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><tbody><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Headline</p></th><td class="op-uc-table--cell"><p class="op-uc-p">Custom fields of type Hierarchy makes project managers and members life easier.</p></td></tr><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">First Paragraph</p></th><td class="op-uc-table--cell"><p class="op-uc-p">This feature allows admins to create and configure hierarchical custom fields. It helps users to organize and navigate complex data in structured, multi-level formats within work packages, making information retrieval more intuitive and manageable.</p></td></tr><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Customer Quote</p></th><td class="op-uc-table--cell"><p class="op-uc-p">It's needed for our ...</p></td></tr></tbody></table></figure>

## Go to market

**Figma and visuals**

https://www.figma.com/design/oTMDTvcwrx35qExTkkSKBn/Custom-fields?node-id=386-8676