Skip to main content

​
Prerequisites

  • A working domain model with entity types and relationships defined
  • Access to Administration > Nextedy POWERSHEET > Domain Models
  • Knowledge of your Polarion document structure (module folders, document types, components)

​
Step 1: Identify the Target Entity Type

Open your domain model YAML and locate the entity type whose picker you want to filter. Pick constraints are defined on the target entity type — the type that appears in the dropdown when a user selects a related item. For example, to control which SystemRequirement items appear when linking from a UserNeed, you add constraints to SystemRequirement: 
domainModelTypes:
  UserNeed:
    polarionType: requirement
    properties:
      description:

  SystemRequirement:
    polarionType: systemRequirement
    properties:
      description:

​
Step 2: Add Pick Constraints

Add a constraints section with a pick sub-section to the target entity type. The document property within pick controls filtering by document location: 
domainModelTypes:
  SystemRequirement:
    polarionType: systemRequirement
    properties:
      description:
    constraints:
      pick:
        document:
          moduleFolder: "Requirements"
          type: "systemRequirementsSpec"
This restricts the picker to show only system requirements located in documents within the Requirements folder that have the document type systemRequirementsSpec.
The constraints section supports three sub-sections: pick (picker dropdown filtering), load (data loading filters), and create (new item defaults). This guide focuses on pick. For a broader overview of all constraint types, see Configure Constraints.

​
Step 3: Choose Filter Properties

Use the following properties inside constraints.pick.document to narrow picker results:
PropertyDescriptionExample Value
moduleFolderRestricts to work items within a specific module folder (space) in the project hierarchy"Requirements"
moduleNameRestricts to work items within a specific document by exact name"System Requirements"
typeRestricts to documents of a specific document type"systemRequirementsSpec"
componentRestricts by document component property"Braking"
The type property must use the Polarion document type ID (e.g., systemRequirementsSpec), not the human-readable display name (e.g., “System Requirements Specification”). Using the display name silently returns no results. Find type IDs in Administration > Documents & Pages > Document Types.

​
Step 4: Use Dynamic Context References

For component-scoped filtering, use $context.source.document.component to dynamically match the source entity’s component at runtime. This is especially useful in multi-component projects where each component maintains its own set of documents: 
domainModelTypes:
  DesignRequirement:
    polarionType: designRequirement
    properties:
      description:
    constraints:
      pick:
        document:
          moduleFolder: "Design"
          type: "designSpec"
          component: $context.source.document.component
When a user picks a DesignRequirement from within a document whose component is “Braking”, the picker shows only design requirements from “Braking” documents. Switching to an “Engine” document automatically filters to “Engine” design requirements. diagram

​
Step 5: Combine Multiple Filter Properties

You can specify multiple filter properties together. All conditions are applied as a logical AND — every condition must match for an item to appear in the picker: 
domainModelTypes:
  Hazard:
    polarionType: hazard
    properties:
      severity:
      likelihood:
    constraints:
      pick:
        document:
          moduleFolder: "Risks"
          type: "hazardAnalysis"
          component: $context.source.document.component
In this example, the Hazard picker only shows items that satisfy all three conditions:
  1. Located in the Risks module folder
  2. In a document of type hazardAnalysis
  3. Belonging to the same component as the source document
Begin with a single constraint (e.g., moduleFolder) and verify it works before combining additional filters. This makes it easier to identify which constraint causes unexpected filtering.

​
Step 6: Configure Picker Search Fields

When a relationship column uses a picker, you can configure which fields are searchable in the dropdown. Add a list property to the column definition in your sheet configuration: 
columns:
  riskControls.riskControl:
    title: "Risk Control"
    multiItem: true
    display: title
    list:
      searchableFields:
        - title
        - id
The searchableFields array controls which entity properties the user can type to search and filter the picker dropdown. Common choices include title, id, and custom property names.

​
Step 7: Complete RTM Example

Here is a complete domain model excerpt demonstrating pick constraints across a requirements traceability hierarchy: 
domainModelTypes:
  UserNeed:
    polarionType: requirement
    properties:
      description:

  SystemRequirement:
    polarionType: systemRequirement
    properties:
      description:
    constraints:
      pick:
        document:
          moduleFolder: "Requirements"
          type: "systemRequirementsSpec"

  DesignRequirement:
    polarionType: designRequirement
    properties:
      description:
    constraints:
      pick:
        document:
          moduleFolder: "Design"
          type: "designSpec"
          component: $context.source.document.component

  Hazard:
    polarionType: hazard
    properties:
      severity:
    constraints:
      pick:
        document:
          moduleFolder: "Risks"
          type: "hazardAnalysis"

  RiskControl:
    polarionType: riskControl
    properties:
      controlType:
    constraints:
      pick:
        document:
          moduleFolder: "Risks"
          type: "riskControlSpec"
          component: $context.source.document.component
A common mistake is placing constraints.pick on the source entity type (e.g., UserNeed) instead of the target (e.g., SystemRequirement). The constraint must be on the entity type that appears in the picker dropdown, not the one initiating the link.

​
Verify Your Configuration

After saving your domain model changes:
  1. Reload the sheet in Polarion (refresh the page or re-open the document)
  2. Click a cell in a relationship column that references the constrained entity type
  3. The picker dropdown should now show only items matching your filter criteria
  4. If using $context.source.document.component, verify that switching to a document with a different component changes the picker results accordingly
You should now see a filtered picker dropdown showing only work items that match your moduleFolder, type, moduleName, or component constraints.
If the picker shows no results after adding constraints, verify: (1) the moduleFolder value matches the exact Polarion space name, (2) the type uses the document type ID (not the display name), and (3) work items actually exist in the constrained location. Remove constraints one at a time to isolate which filter is too restrictive.

​
See Also

Sources — whole_rtm.template.yaml, PolarionQueryProcessor.java, ModelProvider.tsx