For many years a requirement existed for PPO to allow easy cross referencing between entities, i.e. have a dropdown from which an entity can be selected.
Although users requested this in the past, we instead used a work around to meet their specific needs. One of those workarounds included having an Integer field in which users entered the key of the referenced entity and optionally creating a URL link field which links to the item. This is however a bit clunky especially from a demo point of view.
The importance of having a dropdown list for linking cross references was more clearly realized when DevOps adopted agile and later when an agile master instance was configured. On the agile implementation we needed to link work items to sprints (both of which are project related entities).
What is an Entity List field?
The entity list field type is similar to the project, programme and employee list field types in that it shows a searchable dropdown list with display values of the referenced entity as items that can be selected.
Similarly to the project, programme and employeelist fields, it can also be filtered at a field level to show a subset of the items.
Entity list fields as criteria
Entity list fields can also be used as criteria on the list pages as shown in the screenshot below.
How are Entity List fields configured?
An additional field type is available for selection on the field edit page. This field type is called “Entity List”. This field type exposes four other settings:
- Referenced Entity – this refers to the entity whose display values will be populated in the dropdown list.
- Filter – allows the entity list to be filtered further
- Allow Global Filter Toggling – specifies if users can disable the global filter for the field in question.
- Filter by Selected Project - limits the items shown to the currently selected project.
Limitations and considerations
The entity list field can only be configured for project related entities. The main reason for this is to avoid confusion with the existing employee list, project list and programme list fields.
If you want to limit the items in the dropdown to the currently selected project, you can do so by checking the "Filter By Selected Project" checkbox in the field configuration. As an example, if you have an Invoice entity, and you implement an Order field on the invoice which links to the Order entity but you only want to show the orders that are the same as the project to which the invoice relates, you should enable this option.
You cannot delete an item if it is referenced anywhere, even if it is only referenced in a history item i.e. once you link a work item to a sprint, you can never delete that sprint.
Global and User Group filters
Both project and the project related entity user group filters are always applied. The following items won’t be included in the dropdown list:
- Items filtered out by the user group filter on the related project
- Items filtered out by the user group filter on the linked entity itself.
In contrast, users may choose to ignore the global filter on the related entity if permitted to do so on a given field (refer field configuration above). This is done by a toggle button to the right of the dropdown list. It should be noted that if the user disables the entity global filter, it also disables the project global filter.
The most obvious usage is on the agile master whereby work items are linked to sprints. Other use cases may be when one wants to link an outage to an incident.