Create Bidirectional Links - Nextedy Documentation

Prerequisites

Both entity types must already exist in your domainModelTypes section (see Create an Entity Type)
A Polarion link role must be configured in your project for the relationship
Basic familiarity with the data model relationships array (see Configure a Relationship)

Define Both Navigation Directions

Every relationship in the data model supports two navigation directions through the direct and back properties. The direct direction navigates from the from entity to the to entity. The back direction navigates in reverse — from to back to from.Add a relationship entry with both direct and back names defined:

relationships:
  - from: UserNeed
    to: SystemRequirement
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: systemRequirements
    back:
      name: userNeeds

This single relationship definition creates two navigation properties:

Direction	Property Name	Added To	Navigates To
`direct`	`systemRequirements`	`UserNeed`	`SystemRequirement` entities
`back`	`userNeeds`	`SystemRequirement`	`UserNeed` entities

Choose the Right Cardinality

The cardinality determines how navigation properties behave in sources and columns. Pick the pattern that matches your traceability structure:

Cardinality	When to Use	Direct Property	Back Property
`many-to-one`	Each child belongs to exactly one parent	Singular (scalar)	Plural (collection)
`one-to-many`	One parent has many children	Plural (collection)	Singular (scalar)
`many-to-many`	Items linked freely in both directions	Plural (collection)	Plural (collection)

Many-to-One Example

Each UserNeed belongs to exactly one Chapter:

relationships:
  - from: UserNeed
    to: Chapter
    cardinality: many-to-one
    storage: linkedWorkItems
    linkRole: parent
    direct:
      name: chapter
    back:
      name: userNeeds

The direct property chapter is singular — it returns one Chapter entity
The back property userNeeds is plural — it returns a collection of UserNeed entities

Many-to-Many Example

UserNeed links to multiple SystemRequirement items and vice versa:

relationships:
  - from: UserNeed
    to: SystemRequirement
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: systemRequirements
    back:
      name: userNeeds

Both navigation properties return collections in this cardinality.

Navigation property names must be unique within an entity typeEach entity type can only have one navigation property with a given name. If SystemRequirement already has a userNeeds property from another relationship, you will get a conflict error. Use distinct, descriptive names for each navigation property.

Use Bidirectional Links in Sheet Sources

Once the data model defines both directions, configure your sheet sources to expand the navigation properties. The direction you expand determines which entities appear as child rows.Expanding the direct direction (from UserNeed to SystemRequirement):

sources:
  - id: user_needs
    model: rtm
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement

Expanding the back direction (from SystemRequirement to UserNeed):

sources:
  - id: sys_reqs
    model: rtm
    query:
      from: SystemRequirement
    expand:
      - name: userNeeds
        expand:
          - name: userNeed

The same relationship serves both views — no need to define a separate relationship for each direction.

Many-to-many relationships use an association entityFor many-to-many cardinality, the source expand is two levels deep: first the collection (e.g., systemRequirements), then the target entity (e.g., systemRequirement). This intermediate association entity is what enables the many-to-many link.

Bind Columns to Both Directions

Reference the navigation properties in your column configuration to display data from both sides of the relationship.Columns for a UserNeed-centric sheet (expanding toward SystemRequirement):

columns:
  title:
    title: User Need
    hasFocus: true
  systemRequirements.systemRequirement:
    title: System Requirement
    list:
      search:
        - objectId
        - title
      createNew: true
  systemRequirements.systemRequirement.title:
    title: SysReq Title
    isReadOnly: true

Columns for a SystemRequirement-centric sheet (expanding back toward UserNeed):

columns:
  title:
    title: System Requirement
    hasFocus: true
  userNeeds.userNeed:
    title: User Need
    list:
      search:
        - objectId
        - title
  userNeeds.userNeed.description:
    title: UN Description
    isReadOnly: true

The binding path follows the pattern: navigationProperty.targetEntity.field. For many-to-one relationships, the binding is simpler since the property is scalar:

columns:
  chapter:
    title: Chapter
    display: title
    list:
      search:
        - title
  chapter.title:
    title: Chapter Title
    isReadOnly: true

Build a Multi-Level Hierarchy

Chain multiple bidirectional relationships to create a full requirements traceability matrix:

domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      description:
      severity:

  SystemRequirement:
    polarionType: sys_req
    properties:
      description:
      severity:

  DesignRequirement:
    polarionType: des_req
    properties:
      description:

relationships:
  - from: UserNeed
    to: SystemRequirement
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: systemRequirements
    back:
      name: userNeeds

  - from: SystemRequirement
    to: DesignRequirement
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: designRequirements
    back:
      name: systemRequirements

With this model, you can build a sheet that navigates the full chain: UserNeed → SystemRequirement → DesignRequirement — or traverse it in reverse from any level using the back navigation properties.

Avoid duplicate navigation property names in chained relationshipsIn the example above, SystemRequirement has a back property named systemRequirements from the second relationship. Make sure this does not conflict with any other navigation property on the same entity type. If the name is already taken, use a more specific name such as parentSystemRequirements or relatedUserNeeds.

Verify Your Bidirectional Links

Open the Model Helper widget in your Polarion project
Set the depth parameter to at least 2 to see multi-level relationships
Confirm that each entity type shows both its direct and back navigation properties
Open a sheet that uses the data model and expand a row — you should see child items loaded through the navigation property
Switch to a sheet using the reverse direction and verify the back property loads the expected parent items

You should now see navigation working in both directions: expanding a UserNeed shows its linked SystemRequirement items, and expanding a SystemRequirement shows the UserNeed items that reference it.

Use the Model Helper to debug missing linksIf one direction works but the reverse does not, open the Model Helper and verify that both direct.name and back.name appear on their respective entity types. A missing back property usually means the relationship was defined without the back section.

Common Pitfalls

Second linked entity column requires multiItem: trueWhen a sheet has two work item types linked to the same parent entity (for example, both design outputs and design verifications linked to system requirements), the second linked column must be declared with multiItem: true in the sheet configuration. This is a non-obvious requirement that frequently blocks first-time setups.

The sources.model property must match your data model name

Ensure the sources.model property in your sheet configuration matches the custom model name defined in your YAML file, not the default rtm. A mismatch causes model connection errors.

​Prerequisites

​Many-to-One Example

​Many-to-Many Example

​Common Pitfalls

​See Also

Prerequisites

Many-to-One Example

Many-to-Many Example

Common Pitfalls

See Also