Polarion Type Mapping - Nextedy Documentation

See also: Data Model Types | Properties | Relationships

Mapping Architecture

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.

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.

`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:

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:

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

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.

For complete guidance on multi-type entity configuration, see Create an Entity Type.

Omitted `polarionType` (Default Mapping)

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

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

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.

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.

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.

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:

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

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.

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

The from entity type’s polarionType identifies the source work item type
The to entity type’s polarionType identifies the target work item type
The linkRole maps to the Polarion link role connecting them
direct and back properties create navigation properties for traversal in each direction

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

These are the most frequent type mapping errors encountered during initial setup:

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:

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:

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

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

​Mapping Architecture

​Core Mapping Properties

​polarionType Property

​Single Type Mapping (Scalar)

​Multi-Type Mapping (Array)

​Omitted polarionType (Default Mapping)

​polarionProto Property

​Schema Validation

​Built-in Entity Types

​Reserved Properties

​Type Mapping in Relationships

​Relationship Navigation and Type Resolution

​Query Behavior with Type Mappings

​Security and Permissions

​Document-Scoped Queries

​Mapping Validation Rules

​RTM Mapping Example

​Cardinality Impact on Column Binding

​Many-to-One Example

​Many-to-Many Example

​Complete YAML Example

Mapping Architecture

Core Mapping Properties

`polarionType` Property

Single Type Mapping (Scalar)

Multi-Type Mapping (Array)

Omitted `polarionType` (Default Mapping)

`polarionProto` Property

Schema Validation

Built-in Entity Types

Reserved Properties

Type Mapping in Relationships

Relationship Navigation and Type Resolution

Query Behavior with Type Mappings

Security and Permissions

Document-Scoped Queries

Mapping Validation Rules

RTM Mapping Example

Cardinality Impact on Column Binding

Many-to-One Example

Many-to-Many Example

Complete YAML Example