> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Link Roles

> The `linkRole` property in the Nextedy POWERSHEET data model maps a relationship between entity types to a specific Siemens Polarion ALM link role.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

See also: [Relationships](/powersheet/reference/data-model/relationships) | [Navigation Directions](/powersheet/reference/data-model/navigation-directions) | [Cardinality](/powersheet/reference/data-model/cardinality)

## Link Role Property Reference

| Name       | Type     | Default         | Description                                                                                                                                                                         |
| ---------- | -------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `linkRole` | `string` | None (required) | Polarion link role ID that implements the relationship. Must exactly match a link role defined in the Polarion project configuration. Required when `storage` is `linkedWorkItems`. |

<Warning title="Must match Polarion configuration">
  The `linkRole` value must exactly match a link role ID defined in your Polarion project under **Administration > Work Item Link Roles**. A mismatch causes the relationship to fail silently -- no linked items will appear in the sheet, and no error is displayed to the user.
</Warning>

## How Link Roles Bridge the Data Model and Polarion

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/-WiVljKlDztH36bB/powersheet/diagrams/reference/data-model/link-roles/diagram-1.svg?fit=max&auto=format&n=-WiVljKlDztH36bB&q=85&s=2342cd10c32a55cec95cf970246721b0" alt="diagram" style={{ width: "600px", maxWidth: "100%" }} width="600" height="220" data-path="powersheet/diagrams/reference/data-model/link-roles/diagram-1.svg" />
</Frame>

The link role is the bridge between the data model's abstract relationship definition and Polarion's concrete work item linking infrastructure. At runtime:

* **Read operations:** Powersheet queries Polarion for work items connected via the specified link role, then populates the sheet with the results.
* **Write operations:** When users create or remove links in the sheet, Powersheet uses the same link role to persist changes to Polarion.

## Where `linkRole` Appears in Configuration

The `linkRole` property is specified on each entry in the `relationships` array of the data model YAML. It sits alongside the structural properties (`from`, `to`, `cardinality`, `storage`) and the navigation direction definitions (`direct`, `back`).

```yaml theme={null}
relationships:
  - from: UserNeed
    to: Chapter
    cardinality: many-to-one
    storage: linkedWorkItems
    linkRole: parent
    direct:
      name: chapter
    back:
      name: userNeeds
```

### Context Within the Relationship

| Property      | Type     | Default                       | Description                                                                                                                  |
| ------------- | -------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `from`        | `string` | Required                      | Source entity type name. Must match a key in `domainModelTypes`.                                                             |
| `to`          | `string` | Required                      | Target entity type name. Must match a key in `domainModelTypes`.                                                             |
| `cardinality` | `string` | Required                      | Relationship multiplicity. See [Cardinality](/powersheet/reference/data-model/cardinality).                                  |
| `storage`     | `string` | Required                      | Must be `linkedWorkItems` when using `linkRole`.                                                                             |
| `linkRole`    | `string` | Required                      | Polarion link role ID.                                                                                                       |
| `direct`      | `object` | Required                      | Forward navigation property definition. See [Navigation Directions](/powersheet/reference/data-model/navigation-directions). |
| `direct.name` | `string` | Required                      | Name of the navigation property on the `from` entity.                                                                        |
| `back`        | `object` | Optional                      | Reverse navigation property definition.                                                                                      |
| `back.name`   | `string` | Required (if `back` provided) | Name of the navigation property on the `to` entity.                                                                          |

## Link Role and Relationship Direction

A Polarion link role is inherently directional: it has a "from" side and a "to" side. The data model's `from`/`to` entity types and `direct`/`back` navigation properties align with this directionality.

| Aspect                        | `direct` Direction | `back` Direction      |
| ----------------------------- | ------------------ | --------------------- |
| Navigation property placed on | `from` entity type | `to` entity type      |
| Traversal direction           | Source to target   | Target back to source |
| Polarion link side            | Forward link       | Reverse (backlink)    |

The `isBacklink` flag is managed internally by the system. When Powersheet processes a `back` direction, it internally flags the reverse traversal so that Polarion queries use the correct link direction.

<Note title="Same link role, two directions">
  A single `linkRole` value serves both the `direct` and `back` navigation properties. You do not need to define separate link roles for forward and reverse traversal. Powersheet handles the directionality automatically based on the `direct`/`back` configuration.
</Note>

## Link Role and Cardinality Interaction

The `linkRole` itself does not encode cardinality -- it is a simple identifier pointing to a Polarion link role. Cardinality is controlled separately by the `cardinality` property. However, the combination of `linkRole` and `cardinality` determines the runtime behavior:

| Cardinality    | Direct Property              | Back Property                | Source Expand Pattern                                                     | Column Binding                         |
| -------------- | ---------------------------- | ---------------------------- | ------------------------------------------------------------------------- | -------------------------------------- |
| `many-to-one`  | Scalar (single entity)       | Collection                   | `- name: chapter`                                                         | `chapter`, `chapter.title`             |
| `one-to-many`  | Collection                   | Scalar                       | `- name: userNeeds`                                                       | `userNeeds` (child rows)               |
| `many-to-many` | Collection (via association) | Collection (via association) | Two levels: `- name: systemRequirements` then `- name: systemRequirement` | `systemRequirements.systemRequirement` |

See [Cardinality](/powersheet/reference/data-model/cardinality) for the full reference on each value and its effects across model, source, and column layers.

## Reusing the Same Link Role

A single Polarion link role can appear in multiple relationships. This is common when the same semantic relationship type applies to different entity type pairs.

```yaml theme={null}
relationships:
  # decomposes links UserNeed to SystemRequirement
  - from: SystemRequirement
    to: UserNeed
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: userNeeds
    back:
      name: systemRequirements

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

In this example, the `decomposes` link role is reused across two relationship definitions. Each relationship has its own `from`/`to` pairing and its own navigation property names, but they share the same underlying Polarion link role.

<Tip title="Navigation property names must be unique per entity type">
  When reusing a link role across multiple relationships, ensure the navigation property names (`direct.name` and `back.name`) do not collide on the same entity type. Each entity type must have uniquely named navigation properties.
</Tip>

## Permission Control on Relationships

Relationships support permission flags that control whether the link role's operations are available through the sheet:

| Property     | Type      | Default         | Description                                                                     |
| ------------ | --------- | --------------- | ------------------------------------------------------------------------------- |
| `createable` | `boolean` | See application | Controls whether new links using this role can be created through the sheet.    |
| `readable`   | `boolean` | See application | Controls whether links using this role are visible in queries and the sheet UI. |

Individual navigation properties (`direct` and `back`) can also have independent permission settings, allowing fine-grained control over which direction of a link role is editable or visible.

```yaml theme={null}
relationships:
  - from: UserNeed
    to: SystemRequirement
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: systemRequirements
    back:
      name: userNeeds
```

For detailed property-level permission configuration, see [Permissions](/powersheet/reference/data-model/permissions).

## Validation Rules

Powersheet enforces specific rules when processing `linkRole` values:

| Rule                               | Detail                                                                                                                                   |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Required**                       | Every relationship with `storage: linkedWorkItems` must have a `linkRole` value.                                                         |
| **String match**                   | The value must exactly match a link role ID in the Polarion project configuration. The match is case-sensitive.                          |
| **Entity type references**         | The `from` and `to` fields must reference entity type names defined in `domainModelTypes`, not Polarion work item type IDs.              |
| **Navigation property uniqueness** | Within a single entity type, no two navigation properties can share the same name. This applies even when different link roles are used. |

<Warning title="Case sensitivity">
  Link role IDs in Polarion are case-sensitive. A `linkRole: Refines` value will not match a Polarion link role with ID `refines`. Always verify the exact casing in **Administration > Work Item Link Roles**.
</Warning>

## Complete YAML Example

A minimal data model demonstrating `linkRole` across different relationship types:

```yaml theme={null}
domainModelTypes:
  Chapter:
    polarionType: heading

  UserNeed:
    polarionType: user_need
    properties:
      description:
      severity:

  SystemRequirement:
    polarionType: sys_req
    properties:
      description:
      severity:

  DesignRequirement:
    polarionType: des_req
    properties:
      description:

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

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

This model demonstrates two different link roles:

* `parent` for the hierarchical `UserNeed` to `Chapter` relationship (many-to-one)
* `decomposes` for the traceability `SystemRequirement` to `UserNeed` relationship (many-to-many)

Each relationship uses `storage: linkedWorkItems` and defines both `direct` and `back` navigation properties for bidirectional traversal.

## Related Pages

* [Relationships](/powersheet/reference/data-model/relationships) -- complete relationship definition reference
* [Cardinality](/powersheet/reference/data-model/cardinality) -- relationship multiplicity options and their effects
* [Navigation Directions](/powersheet/reference/data-model/navigation-directions) -- `direct` and `back` navigation property definitions
* [Constraints](/powersheet/reference/data-model/constraints) -- filtering constraints on navigation directions
* [Permissions](/powersheet/reference/data-model/permissions) -- CRUD permission controls on relationships and properties
* [Polarion Type Mapping](/powersheet/reference/data-model/polarion-mapping) -- entity type to work item type mapping
* [Binding Syntax](/powersheet/reference/sheet-config/binding-syntax) -- using navigation properties in column bindings
* [Sources](/powersheet/reference/sheet-config/sources) -- configuring expand paths that reference navigation properties

<LastReviewed date="2026-07-02" />