Skip to main content

​
Structure

Relationships are defined as an array at the top level of the domain model YAML, alongside domainModelTypes: 
relationships:
  - from: UserNeed
    to: SystemRequirement
    cardinality: one-to-many
    storage: linkedWorkItems
    linkRole: refines
    fromNavPropName: systemRequirements
    toNavPropName: userNeed

​
Relationship Properties

PropertyTypeDefaultDescription
fromstringRequiredSource entity type name. Must match a key in domainModelTypes.
tostringRequiredTarget entity type name. Must match a key in domainModelTypes.
cardinalitystringRequiredRelationship multiplicity. See Cardinality.
storagestringRequiredPersistence mechanism. See Storage.
linkRolestringRequired (when storage is linkedWorkItems)Polarion link role ID. See Link Roles.
fromNavPropNamestringSee applicationNavigation property name added to the source (from) entity for forward traversal.
toNavPropNamestringSee applicationNavigation property name added to the target (to) entity for reverse traversal.
The from and to fields must reference names defined in domainModelTypes — not Polarion work item type IDs. For example, use UserNeed (the entity type name), not userNeed (the Polarion type ID).

​
Alternative Navigation Property Syntax

Instead of fromNavPropName and toNavPropName, relationships can use the direct and back object syntax:
PropertyTypeDefaultDescription
directobjectNoneForward navigation property configuration.
direct.namestringRequiredNavigation property name for forward traversal (from source to target).
backobjectNoneReverse navigation property configuration.
back.namestringRequiredNavigation property name for reverse traversal (from target back to source).
relationships:
  - from: UserNeed
    to: SystemRequirement
    cardinality: one-to-many
    storage: linkedWorkItems
    linkRole: refines
    direct:
      name: systemRequirements
    back:
      name: userNeed
Both syntaxes are equivalent. The direct/back format supports additional properties for permission control on the navigation direction.

​
Cardinality Options

ValueFrom SideTo Side
one-to-oneSingle referenceSingle reference
many-to-oneSingle referenceCollection
one-to-manyCollectionSingle reference
many-to-manyCollectionCollection
See Cardinality for detailed documentation.

​
Storage Mechanisms

ValueDescription
linkedWorkItemsUses Polarion’s native work item link mechanism. Requires linkRole.
customFieldStores references in custom fields.
See Storage for detailed documentation. Navigation property names created by relationships are used in sheet configuration binding paths. For example, with the relationship above, a column can display the linked system requirement’s title: 
columns:
  systemRequirements.systemRequirement.title:
    title: System Requirement
    width: 200
The binding path follows: systemRequirements (navigation property on UserNeed) -> systemRequirement (the expanded entity) -> title (the property).

​
Permission Control on Relationships

Relationships support permission flags that control whether links can be created or read:
PropertyTypeDefaultDescription
createablebooleanSee applicationWhether new relationship instances can be created through the sheet
readablebooleanSee applicationWhether relationship instances are visible in queries
The exact behavior of permission flags on relationships may vary. Test in your environment to confirm.

​
Complete YAML Example

domainModelTypes:
  UserNeed:
    polarionType: userNeed
    properties:
      description: null
      severity: null

  SystemRequirement:
    polarionType: systemRequirement
    properties:
      description: null
      component: null

  DesignRequirement:
    polarionType: designOutput
    properties:
      description: null

  Hazard:
    polarionType: hazard
    properties:
      description: null

  RiskControl:
    polarionType: riskControl
    properties:
      description: null

  ExternalReference:
    properties:
      systemId: null
      link: null

relationships:
  - from: UserNeed
    to: SystemRequirement
    cardinality: one-to-many
    storage: linkedWorkItems
    linkRole: refines
    direct:
      name: systemRequirements
    back:
      name: userNeed

  - from: SystemRequirement
    to: DesignRequirement
    cardinality: one-to-many
    storage: linkedWorkItems
    linkRole: refines
    direct:
      name: designRequirements
    back:
      name: systemRequirement

  - from: Hazard
    to: RiskControl
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: mitigates
    direct:
      name: riskControls
    back:
      name: hazards

  - from: ExternalReference
    to: DesignRequirement
    cardinality: many-to-one
    storage: linkedWorkItems
    linkRole: relatesTo
    direct:
      name: designRequirement
    back:
      name: externalReferences
diagram
KB ArticlesSource Code
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/fixtures/models/constraints_create_only.yaml
  • model.yaml
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/fixtures/models/constraints-base.yaml
  • DomainModelV2.java
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/fixtures/configurations/constraints_currentDocument_downstream.template.yaml