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

# Document Rules

> In Nextedy POWERSHEET, **document rules** are constraints within the data model that bind entity types to specific Polarion documents, document types, or module folders.

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

Think of document rules as a filing system for a regulated office: each type of document has its designated drawer, and the rules ensure that nobody accidentally files a safety hazard report in the requirements drawer. Polarion itself does not enforce this discipline -- Powersheet adds it through the data model's constraint mechanism.

## Why Document Rules Matter

Siemens Polarion ALM organizes work items inside LiveDoc documents, but it does not natively restrict which work item types belong in which documents. A `systemRequirement` work item can be created in any document, and a `userNeed` can end up in a design specification. In regulated industries following standards like ISO 26262 or Automotive SPICE, this structural freedom introduces risk: auditors expect clear separation between requirement types, and traceability gaps emerge when items scatter across uncontrolled locations.

Document rules in the data model act as **process guardrails**. They do not alter Polarion's underlying data storage -- they control what Powersheet queries, displays, and permits through the sheet interface. This distinction is important: a `SystemRequirement` work item that exists in an unexpected document is not deleted or moved by a document rule. Instead, the rule simply prevents it from appearing in the sheet, being selected in a picker, or being the default location for new items of that type.

<Note title="Data model scope">
  Document rules are defined per entity type in the data model YAML (`domainModelTypes`), not in the sheet configuration. This means they apply consistently across every sheet configuration that uses the same data model, regardless of column layout or view settings.
</Note>

## The Three Constraint Stages

Document rules operate through three **constraint stages**, each controlling a different aspect of how entities interact with documents. These stages are defined within the `constraints` block on an entity type.

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/3Zik2OH750CE3kB4/powersheet/diagrams/concepts/document-rules/diagram-1.svg?fit=max&auto=format&n=3Zik2OH750CE3kB4&q=85&s=75beea40e96ce69a71936b3587e93719" alt="diagram" style={{ width: "580px", maxWidth: "100%" }} width="580" height="280" data-path="powersheet/diagrams/concepts/document-rules/diagram-1.svg" />
</Frame>

### Stage Cascading

A critical concept is that constraint stages **cascade upward**:

* **`pick`** inherits from `load`. If you define `load` constraints but no `pick` constraints, the pick stage uses the load constraints automatically.
* **`create`** inherits from both `load` and `pick`. If no explicit `create` constraints exist, the system falls back to `pick` constraints (which themselves may have fallen back to `load`).

This cascading means you often only need to define the `load` stage. The pick and create stages will inherit its document rules unless you need different behavior at those stages.

<Warning title="Cascading fallback order">
  The fallback chain is: `create` -> `pick` -> `load`. If you define only `load` document rules, all three stages use them. If you define `load` and `pick`, the create stage inherits from `pick` (not `load`). Define explicit `create` constraints only when new items should go to a different location than where picker results come from.
</Warning>

### Load Stage

A `load` constraint with document rules filters the initial data query so that only work items residing in matching documents appear in the sheet:

```yaml theme={null}
domainModelTypes:
  SystemRequirement:
    polarionType: systemRequirement
    constraints:
      load:
        document:
          type: systemSpecification
```

This ensures the sheet query only returns `SystemRequirement` items from documents whose type is `systemSpecification`. Items of the same Polarion work item type in other documents are excluded from the display.

### Pick Stage

Pick constraints scope the item picker dialog. When a user links a relationship to a `UserNeed`, the picker shows only items matching the pick constraints:

```yaml theme={null}
domainModelTypes:
  UserNeed:
    polarionType: userNeed
    constraints:
      pick:
        document:
          moduleFolder: Requirements
          type: needsDocument
```

When another entity type references `UserNeed` through a relationship, the picker dialog will only show user needs from `needsDocument`-type documents in the `Requirements` folder. This prevents users from accidentally linking to items in unrelated documents.

### Create Stage

Create constraints determine the default document location when a user creates a new entity through the sheet:

```yaml theme={null}
domainModelTypes:
  DesignRequirement:
    polarionType: designOutput
    constraints:
      create:
        document:
          moduleFolder: Design
          moduleName: Design Specification
```

When a user creates a new `DesignRequirement` item, Powersheet automatically places it in the `Design Specification` document within the `Design` folder. Without this constraint, new items might be created in the currently active document, which may not be the intended location.

## Document Filter Properties

All three constraint stages support the same set of document filter properties within the `document` block:

| Property                | What It Filters                                                                         | Example Value                        |
| ----------------------- | --------------------------------------------------------------------------------------- | ------------------------------------ |
| `document.moduleFolder` | Restricts to work items within a specific Polarion module folder (space)                | `Requirements`                       |
| `document.moduleName`   | Restricts to work items within a specific document by exact name match                  | `System Specification`               |
| `document.type`         | Restricts to work items in documents of a specific Polarion document type               | `systemSpecification`                |
| `document.component`    | Restricts by the document's component property; supports dynamic `$context` expressions | `$context.source.document.component` |

These properties can be combined within a single `document` block. When multiple properties are specified, they act as an AND condition -- all criteria must match for a document to qualify.

```yaml theme={null}
constraints:
  load:
    document:
      moduleFolder: Requirements
      type: systemSpecification
      component: Braking
```

This loads only `systemSpecification`-type documents from the `Requirements` folder that belong to the `Braking` component.

## Dynamic Document Scoping with Context

For projects where document assignments vary by component, subsystem, or other runtime context, document rules support **`$context` expressions**. These expressions resolve dynamically based on the current document, source entity, or query parameters rather than being hardcoded in the data model.

The most common pattern scopes constraints to the same component as the source entity's document:

```yaml theme={null}
constraints:
  pick:
    document:
      component: $context.source.document.component
```

This ensures that when picking related items, only entities from documents with the **same component value** as the source entity's document are shown. In multi-component projects -- where each component has its own requirement, design, and test documents -- this prevents cross-component linking mistakes.

<Tip title="When to use dynamic scoping">
  Use `$context.source.document.component` when your project structure mirrors a component hierarchy. For example, if the Braking subsystem has its own `System Specification` and `Design Specification` documents, dynamic scoping ensures that requirements in the Braking specification only link to design items in the Braking design document -- without needing separate entity types or data models per component.
</Tip>

The query manager resolves `$context` expressions at runtime by injecting the current document's properties (such as `document.id`, `document.moduleFolder`, and `document.component`) into the query parameters. This resolution happens transparently before the query is sent to the server.

## Combining Document Rules Across Entity Types

In a full RTM data model, each entity type typically has its own document rules. Consider a standard requirements traceability hierarchy:

```yaml theme={null}
domainModelTypes:
  UserNeed:
    polarionType: userNeed
    constraints:
      load:
        document:
          type: needsDocument
  SystemRequirement:
    polarionType: systemRequirement
    constraints:
      load:
        document:
          type: systemSpecification
  DesignRequirement:
    polarionType: designOutput
    constraints:
      load:
        document:
          type: designSpecification
      create:
        document:
          moduleFolder: Design
          moduleName: Design Specification
  Hazard:
    polarionType: hazard
    constraints:
      pick:
        document:
          component: $context.source.document.component
```

Each entity type is scoped to its appropriate document type. The `DesignRequirement` type adds an explicit `create` stage to control where new items land. The `Hazard` type uses dynamic component scoping for its picker.

## Comparison Operators in Constraints

Beyond simple equality matching, constraints support several **comparison operators** that provide more flexible filtering:

| Operator     | Behavior                                         | Example                                |
| ------------ | ------------------------------------------------ | -------------------------------------- |
| `equals`     | Exact match (default when no operator specified) | `type: systemSpecification`            |
| `contains`   | Substring match                                  | `moduleName: { contains: "Spec" }`     |
| `in`         | Matches any value in a list                      | `type: { in: [sysSpec, designSpec] }`  |
| `startsWith` | Prefix match                                     | `moduleFolder: { startsWith: "Req" }`  |
| `endsWith`   | Suffix match                                     | `moduleName: { endsWith: "Document" }` |

These operators are useful when document naming follows a pattern rather than exact conventions, or when a single constraint needs to match multiple document types.

## Logical Operators

Within the `document` block, constraints support **OR logic** for combining alternative conditions. Multiple criteria at the same level are joined with AND logic by default. To express OR conditions, the constraint system allows alternative document blocks:

```yaml theme={null}
constraints:
  pick:
    document:
      moduleFolder: Requirements
      type: needsDocument
```

All properties within the same `document` block are evaluated as AND. If no `create` constraints are defined, the system falls back to `pick` constraints for the create stage, ensuring consistent behavior without redundant configuration.

<Warning title="Conflicting constraints">
  When composing multiple constraints, be careful that the combined conditions do not produce an empty result set. For example, constraining to `moduleFolder: Design` AND `type: needsDocument` might match no documents if your needs documents reside in the `Requirements` folder. Test constraint combinations by checking what the picker shows before committing the configuration.
</Warning>

## Common Misconceptions

**"Document rules move work items between documents."**
They do not. Document rules only affect what Powersheet loads, displays in pickers, and uses as the target for new items. A work item's actual document location in Polarion is unchanged by document rules.

**"I need to define all three stages."**
Due to cascading inheritance, defining only the `load` stage is often sufficient. The `pick` and `create` stages inherit from it automatically. Define separate stages only when you need different behavior -- for example, loading broadly but creating in a specific document.

**"Document rules replace Polarion permissions."**
Document rules are a data model concern, not a security mechanism. They guide the sheet interface but do not override Polarion's native permission model. A user with Polarion permissions to edit a document outside the constraint scope could still modify items through Polarion's standard interface, just not through Powersheet.

## Relationship to Other Concepts

Document rules are one layer of the broader constraint system in Powersheet. They work alongside other concepts to create a complete enforcement model:

* **[Process Constraints](/powersheet/concepts/process-constraints)** define validation rules beyond document scoping, such as field-level restrictions and workflow enforcement.
* **[Link Cardinality](/powersheet/concepts/link-cardinality)** controls how many relationships of a given type are permitted -- while document rules control *where* the related entities can come from.
* **[Entity Types and Relationships](/powersheet/concepts/entity-types-and-relationships)** define the structural foundation that document rules operate upon.
* **[Navigation Properties](/powersheet/concepts/navigation-properties)** determine how relationships are traversed; document rules determine which items are reachable during that traversal.

For practical setup instructions, see the [Data Model Guides](/powersheet/guides/data-model/index). For the full constraint property reference, see the [Data Model Reference](/powersheet/reference/data-model/index).

***

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