> ## 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.

# Polarion Type Mapping

> Polarion type mapping connects each entity type in the Nextedy POWERSHEET data model to one or more Siemens Polarion ALM work item types.

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: [Data Model Types](/powersheet/reference/data-model/domainmodeltypes) | [Properties](/powersheet/reference/data-model/properties) | [Relationships](/powersheet/reference/data-model/relationships)

## Mapping Architecture

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

## Core Mapping Properties

| Name            | Type                   | Default              | Description                                                                                                                                                                                                  |
| --------------- | ---------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `polarionType`  | `string` or `string[]` | Entity type name     | Maps the data model entity type to one or more Polarion work item type IDs. When omitted, the entity type name is used as the Polarion type ID. Accepts both scalar and array formats.                       |
| `polarionProto` | `string`               | `IWorkItem.PROTO`    | Specifies the Polarion prototype (object type) this entity maps to. Determines which class of Polarion objects this entity can represent. Valid values are enumerated from the Polarion platform at runtime. |
| `name`          | `string`               | Derived from map key | Unique identifier for the entity type. Set automatically from the YAML map key. Referenced by `relationships[].from` and `relationships[].to` fields.                                                        |

<Tip title="Implicit type mapping">
  When `polarionType` is omitted, the entity type name (the YAML map key) is used as the Polarion work item type ID. For example, an entity named `Task` with no explicit `polarionType` maps to Polarion work item type `Task`.
</Tip>

## `polarionType` Property

### Single Type Mapping (Scalar)

The most common pattern maps one entity type to one Polarion work item type using a scalar string value:

```yaml theme={null}
domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      title:
      description:
      severity:
```

In this configuration, the `UserNeed` entity type maps to the Polarion work item type ID `user_need`. All queries for `UserNeed` entities resolve to work items of type `user_need`.

### Multi-Type Mapping (Array)

A single entity type can map to multiple Polarion work item types by providing an array. This enables a unified view over work items of different types:

```yaml theme={null}
domainModelTypes:
  Requirement:
    polarionType:
      - sys_req
      - des_req
    properties:
      title:
      description:
      severity:
```

When `polarionType` is an array:

* Queries for the `Requirement` entity type return work items matching **any** of the listed types
* The first type in the array is used as the default when creating new work items
* All listed type IDs must exist in the Polarion project configuration

<Warning title="Multi-type query behavior">
  When an entity maps to multiple Polarion types, queries produce a combined result set. Filter predicates and constraints apply uniformly across all mapped types. Properties referenced in column bindings must exist on all mapped types, or the value will be empty for types that lack the field.
</Warning>

For complete guidance on multi-type entity configuration, see [Create an Entity Type](/powersheet/guides/data-model/create-entity-type).

### Omitted `polarionType` (Default Mapping)

When `polarionType` is not specified, the entity type name becomes the Polarion type ID:

```yaml theme={null}
domainModelTypes:
  Hazard:
    properties:
      title:
      severity:
```

The `Hazard` entity maps to Polarion work item type `Hazard`. This convention works when the entity type name exactly matches the Polarion work item type ID defined in the project.

## `polarionProto` Property

The `polarionProto` property specifies which Polarion prototype (object class) the entity represents. Most entity types use the default `IWorkItem.PROTO`, but special object types require an explicit prototype.

| `polarionProto` Value       | Polarion Object       | Use Case                                              |
| --------------------------- | --------------------- | ----------------------------------------------------- |
| `IWorkItem.PROTO` (default) | Work item             | Standard entity types (requirements, risks, controls) |
| Other prototype values      | Non-work-item objects | Special Polarion object classes                       |

<Info title="Verify in application">
  Available prototype values are enumerated from the Polarion platform at runtime. The JSON schema generator reads all valid prototype names to populate the `polarionProto` enum constraint for IDE validation.
</Info>

```yaml theme={null}
domainModelTypes:
  Document:
    polarionProto: IModule.PROTO
    properties:
      title:
      type:
```

### Schema Validation

The JSON schema generated by Powersheet validates `polarionProto` values against the set of prototypes available on the Polarion server. When editing data model YAML files with schema support enabled, the IDE provides:

* Autocomplete for valid `polarionProto` values
* Validation errors for unrecognized prototypes
* Type checking for `polarionType` (accepts both string and array)

## Built-in Entity Types

Powersheet recognizes several built-in entity types that map to Polarion objects. These types have specialized handling in the query processor and metadata system.

| Entity Type | Polarion Object           | `polarionType` Support | Notes                                                                                         |
| ----------- | ------------------------- | ---------------------- | --------------------------------------------------------------------------------------------- |
| `Document`  | Polarion module (LiveDoc) | Yes                    | When `polarionType` is set, it references a concrete document type. Container for work items. |
| `Project`   | Polarion project          | N/A                    | Project-level metadata and properties.                                                        |

<Note title="Document type mapping">
  The `Document` entity type supports `polarionType`. When set, it filters documents to those matching a specific document type ID. This is useful for constraining picker dialogs and queries to a particular class of documents.
</Note>

### Reserved Properties

Built-in entity types have reserved properties that are always set to `false` in the data model schema:

| Reserved Property | Applies To       | Description                                                 |
| ----------------- | ---------------- | ----------------------------------------------------------- |
| `project`         | All entity types | Always `false`. Project context is resolved automatically.  |
| `document`        | All entity types | Always `false`. Document context is resolved automatically. |

## Type Mapping in Relationships

Relationship definitions reference entity types by their data model name (the YAML map key), **not** by their Polarion work item type ID:

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

<Warning title="Entity names, not Polarion type IDs">
  The `from` and `to` fields in relationships must use data model entity type names (`UserNeed`, `SystemRequirement`), not Polarion work item type IDs (`user_need`, `sys_req`). Powersheet resolves the Polarion type mapping internally when executing queries.
</Warning>

### Relationship Navigation and Type Resolution

When a relationship links two entity types, Powersheet resolves the `polarionType` of each entity to construct the appropriate Polarion query:

1. The `from` entity type's `polarionType` identifies the source work item type
2. The `to` entity type's `polarionType` identifies the target work item type
3. The `linkRole` maps to the Polarion link role connecting them
4. `direct` and `back` properties create navigation properties for traversal in each direction

```yaml theme={null}
domainModelTypes:
  UserNeed:
    polarionType: user_need
    properties:
      description:
      severity:

  SystemRequirement:
    polarionType: sys_req
    properties:
      description:
      severity:

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

In this example:

* Navigating `direct` (`systemRequirements`) from a `UserNeed` queries Polarion for `sys_req` work items linked via the `decomposes` link role
* Navigating `back` (`userNeeds`) from a `SystemRequirement` queries Polarion for `user_need` work items linked via the reverse of `decomposes`

## Query Behavior with Type Mappings

The query processor uses `polarionType` mappings when translating data model queries to Polarion Lucene queries:

| Scenario                | Query Behavior                                                        |
| ----------------------- | --------------------------------------------------------------------- |
| Single `polarionType`   | Lucene filter: `type:user_need`                                       |
| Array `polarionType`    | Lucene filter: `type:(sys_req OR des_req)`                            |
| Omitted `polarionType`  | Lucene filter uses entity type name as type ID                        |
| Entity with constraints | Constraints applied as additional Lucene predicates after type filter |

### Security and Permissions

Before any query executes, Powersheet checks that the current user has read permission for the entity type being queried. Entity types can have permission annotations that restrict access. See [Permissions](/powersheet/reference/data-model/permissions) for details.

### Document-Scoped Queries

When a `currentDocConstraint` parameter is provided, the query processor restricts results to work items within a specific document. The constraint can reference either an entity type name or a navigation property path. Combined with `polarionType`, this enables document-scoped views over specific work item types.

## Mapping Validation Rules

<Warning title="Common configuration mistakes">
  These are the most frequent type mapping errors encountered during initial setup:
</Warning>

| Rule                                             | Description                                                                                                                                                                      |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `polarionType` must match Polarion configuration | Type IDs must correspond to work item types defined in the Polarion project. Mismatched IDs produce empty query results.                                                         |
| Entity type names are case-sensitive             | `UserNeed` and `userneed` are different entity types. Use PascalCase consistently.                                                                                               |
| `sources.model` must match model name            | The `model` property in sheet sources must reference the correct data model file name, not the default `rtm`.                                                                    |
| Document constraints use type ID                 | When configuring document constraints, use the document type ID (e.g., `softwareRequirementsSpecification`), not the display name (e.g., "Software Requirements Specification"). |
| Multi-item columns for duplicate link types      | When two different entity types link to the same parent entity via the same link role, the second column must use `multiItem: true` in the sheet configuration.                  |

## RTM Mapping Example

Standard RTM entity types with their Polarion type mappings:

| Entity Type         | `polarionType` | Polarion Work Item Type |
| ------------------- | -------------- | ----------------------- |
| `UserNeed`          | `user_need`    | User Need               |
| `SystemRequirement` | `sys_req`      | System Requirement      |
| `DesignRequirement` | `des_req`      | Design Requirement      |
| `Hazard`            | `hazard`       | Hazard                  |
| `RiskControl`       | `riskControl`  | Risk Control            |

## Cardinality Impact on Column Binding

The `polarionType` mapping interacts with relationship cardinality to determine how columns display data. The cardinality of the relationship between entity types determines the expand pattern and column binding syntax used in sheet configurations.

| Cardinality    | Direct Navigation            | Column Binding                         | UI Behavior                   |
| -------------- | ---------------------------- | -------------------------------------- | ----------------------------- |
| `many-to-one`  | Scalar (single value)        | `chapter`, `chapter.title`             | Single-value reference picker |
| `one-to-many`  | Collection (multiple values) | `userNeeds`                            | Child rows (new sheet level)  |
| `many-to-many` | Collection via association   | `systemRequirements.systemRequirement` | Multi-item reference picker   |

### Many-to-One Example

Each `UserNeed` belongs to one `Chapter`. The `direct` navigation property `chapter` is scalar:

```yaml theme={null}
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: chapter

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

* `chapter` renders as a single-value reference picker
* `chapter.title` displays the referenced entity's title as read-only

### Many-to-Many Example

`UserNeed` links to multiple `SystemRequirement` entities. The `back` navigation property uses a two-level expand:

```yaml theme={null}
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement

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

* Many-to-many relationships use an **association entity** between the two types
* Source expand is two levels: `systemRequirements` (association) then `systemRequirement` (target)
* Column binding uses dot notation: `systemRequirements.systemRequirement`
* The `createNew: true` option enables inline creation of new linked work items

## Complete YAML Example

```yaml theme={null}
domainModelTypes:
  Document:
    polarionProto: IModule.PROTO
    properties:
      title:
      type:

  UserNeed:
    polarionType: user_need
    properties:
      title:
      description:
      severity:
      component:

  SystemRequirement:
    polarionType: sys_req
    properties:
      title:
      description:
      severity:

  DesignRequirement:
    polarionType: des_req
    properties:
      title:
      description:

  Hazard:
    polarionType: hazard
    properties:
      title:
      description:
      severity:

  RiskControl:
    polarionType: riskControl
    properties:
      title:
      description:

  MultiTypeEntity:
    polarionType:
      - defect
      - change_request
    properties:
      title:
      description:
      priority:

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

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

  - from: DesignRequirement
    to: Hazard
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: addresses
    direct:
      name: hazards
    back:
      name: designRequirements

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

***

**Related pages:** [Data Model Types](/powersheet/reference/data-model/domainmodeltypes) | [Properties](/powersheet/reference/data-model/properties) | [Relationships](/powersheet/reference/data-model/relationships) | [Cardinality](/powersheet/reference/data-model/cardinality) | [Link Roles](/powersheet/reference/data-model/link-roles) | [Constraints](/powersheet/reference/data-model/constraints)

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