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

# Process Constraints

> Siemens Polarion ALM provides a flexible work item system that intentionally leaves structural rules unenforced.

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

This page explains why constraints exist, how the three constraint stages interact through cascading, what properties you can constrain, and how dynamic context expressions enable adaptive filtering at runtime.

## Why Constraints Exist

Consider a regulated engineering environment: user needs must live in a stakeholder requirements document, system requirements belong in a system specification, and design outputs go into a design document. Polarion itself does not enforce these structural rules -- it stores the data, but it does not prevent a user from placing a system requirement in the wrong document or linking a hazard to an unrelated test case.

Process constraints in Nextedy POWERSHEET act as **guardrails**: they do not alter what Polarion can store, but they control what Powersheet will display in the sheet, offer in picker dialogs, and permit as a target location when creating new items.

Think of constraints as a building's access control system. The building itself (Polarion) has rooms and hallways connecting them, but the access system (constraints) determines which doors open for which people and which rooms are available for new meetings. The physical structure is unchanged, but the behavior is governed.

<Tip title="Guardrails, not walls">
  Constraints operate at the Powersheet application layer. Users with direct Polarion access can still create or link items outside these rules. Constraints guide correct behavior within the sheet experience; they complement (but do not replace) Polarion workflow rules or link role restrictions.
</Tip>

## The Three Constraint Stages

The data model supports three categories of constraints, each operating at a different point in the data lifecycle:

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

### Load Constraints

**`constraints.load`** filters which entities are retrieved when the sheet initially queries Polarion. This operates at the query level, reducing the result set before data ever reaches the client application.

A load constraint typically uses document properties to scope entity retrieval:

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

With this constraint, only system requirements residing in documents of type `systemSpecification` are loaded into the sheet. Items in other document types are invisible to Powersheet, as though they do not exist.

### Pick Constraints

**`constraints.pick`** restricts which existing items appear in picker dialogs when users create or modify relationships. This is critical for preventing incorrect traceability links -- without pick constraints, a user could link a system requirement to an item from an unrelated document or project space.

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

When a user opens the picker to select a `UserNeed`, only items from the `Requirements` folder in documents of type `needsDocument` appear as candidates.

### Create Constraints

**`constraints.create`** controls where new work items are placed when users create them through the sheet. By specifying a `document` constraint with `moduleFolder`, `moduleName`, or `type`, you route new items to the correct location automatically.

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

When a user creates a new `DesignRequirement` through the sheet, Powersheet automatically places it in a document matching the `Design` folder and `designSpecification` type. The user does not need to manually choose a target location.

## Stage Cascading and Fallback

One of the most important aspects of the constraint system is **stage cascading**. The three stages form an inheritance chain:

1. **`load`** is the base stage -- it stands alone with no inheritance
2. **`pick`** inherits all `load` constraints (combined with AND logic)
3. **`create`** inherits both `load` and `pick` constraints

This cascading behavior means that a single `load` constraint automatically scopes all three user interactions. If you constrain `load` to filter by `document.type: systemSpecification`, then the picker and create dialogs also respect that filter without requiring explicit `pick` or `create` blocks.

<Warning title="Fallback behavior">
  If no `create` constraints are explicitly defined for an entity type, the system falls back to using `pick` constraints for the create stage. This means defining only `load` and `pick` is often sufficient -- the `create` behavior inherits from both. However, if you need create to target a *different* location than what pick allows, you must define `create` constraints explicitly.
</Warning>

**Practical implication:** Start with the most restrictive stage you need. If a load constraint covers your needs, you may not need pick or create blocks at all. Add them only when the three stages require different scoping rules.

| Scenario                                | Minimum constraints needed                        |
| --------------------------------------- | ------------------------------------------------- |
| Same filter for all interactions        | `load` only                                       |
| Different picker scope than loaded data | `load` + `pick`                                   |
| Create targets a specific document      | `load` + `create` (or `load` + `pick` + `create`) |
| Each stage has unique rules             | All three explicitly defined                      |

## Document-Based Constraint Properties

All three constraint stages share a common set of document-level filter properties:

| Property                | Description                                                     | Example value                        |
| ----------------------- | --------------------------------------------------------------- | ------------------------------------ |
| `document.moduleFolder` | Restricts to a specific Polarion module folder (space)          | `Requirements`                       |
| `document.moduleName`   | Restricts to a specific document by exact name                  | `System Specification`               |
| `document.type`         | Restricts to documents of a specific Polarion document type     | `systemSpecification`                |
| `document.id`           | Restricts by full document ID in `folder/name` format           | `Requirements/Stakeholder Needs`     |
| `document.title`        | Restricts by document display title                             | `Stakeholder Requirements`           |
| `document.component`    | Restricts by document component; supports `$context` references | `$context.source.document.component` |

## Comparison Operators

Constraint values are not limited to exact matching. Powersheet provides five comparison operators that give you flexible filtering patterns:

| Operator     | Meaning                                          | Example                                |
| ------------ | ------------------------------------------------ | -------------------------------------- |
| `equals`     | Exact match (default when no operator specified) | `type: systemSpecification`            |
| `contains`   | Value contains the substring                     | `moduleName: {contains: "Spec"}`       |
| `in`         | Value matches any item in a list                 | `type: {in: [systemSpec, designSpec]}` |
| `startsWith` | Value starts with the prefix                     | `moduleFolder: {startsWith: "Req"}`    |
| `endsWith`   | Value ends with the suffix                       | `moduleName: {endsWith: "Document"}`   |

When you write a plain string value (like `type: systemSpecification`), it is interpreted as an `equals` comparison. Use the object syntax with an explicit operator key when you need other matching behavior.

## Logical Operators: AND and OR

By default, multiple properties within a `document` block are combined with **AND** logic -- all conditions must be true for an item to match.

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

This means the item must be in the `Requirements` folder AND in a document of type `needsDocument`.

Powersheet also supports **OR** logic inside the document block, allowing you to match items that satisfy any one of several conditions. This is useful when valid items can come from multiple document types or folders.

<Note title="Constraint composition">
  When combining multiple constraints with OR logic, be careful about conflicting conditions. Two constraints that individually match different sets of items may produce an empty result if their intersection is empty. Test complex constraint compositions in a development environment before deploying to production.
</Note>

## Dynamic Context References

Constraints support runtime context expressions using the `$context` prefix. These expressions are resolved dynamically when the constraint is evaluated, allowing the filter to adapt based on the current document or entity.

The most common pattern is **component-scoped filtering**:

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

This ensures that when a user opens a picker to select a related entity, only items from documents sharing the same component value as the source entity's document are offered. This is particularly useful in large projects where multiple components (subsystems, variants, or product lines) coexist and traceability must remain within component boundaries.

Other available context references include:

| Expression                           | Resolves to                                      |
| ------------------------------------ | ------------------------------------------------ |
| `$context.source.document.component` | Component of the source entity's parent document |
| `$context.document.id`               | Full ID of the current document                  |

<Info title="Verify in application">
  The exact set of `$context` expressions available may vary by Powersheet version. Test context-based constraints in your environment to confirm behavior before relying on them in production configurations.
</Info>

## Constraint Composition: A Complete Example

The following data model excerpt shows constraints applied to a standard RTM hierarchy. Each entity type is scoped to its correct document location, with pick constraints ensuring traceability links stay within the proper boundaries:

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

  SystemRequirement:
    polarionType: systemRequirement
    constraints:
      load:
        document:
          type: systemSpecification
      create:
        document:
          moduleFolder: Design
          type: systemSpecification

  DesignRequirement:
    polarionType: designOutput
    constraints:
      load:
        document:
          type: designSpecification
      create:
        document:
          moduleFolder: Design
          type: designSpecification

  Hazard:
    polarionType: hazard
    constraints:
      pick:
        document:
          moduleFolder: Risks
          component: $context.source.document.component
```

In this configuration:

* **`UserNeed`** items are loaded only from stakeholder requirements documents, and pickers further restrict to the `Requirements` folder
* **`SystemRequirement`** items load from system specifications, and new items are created in the `Design` folder within system specification documents
* **`DesignRequirement`** follows a similar pattern, scoped to design specifications
* **`Hazard`** pick constraints ensure risk-related linking stays within the same component, enforcing component-level traceability

## How Constraints Relate to Other Concepts

Constraints work in concert with several other data model concepts to enforce your engineering process:

* **[Link Cardinality](/powersheet/concepts/link-cardinality)** controls *how many* links are allowed between entity types, while constraints control *which items* are visible, selectable, and creatable
* **[Document Rules](/powersheet/concepts/document-rules)** define broader document-level governance that applies regardless of entity type
* **[Entity Types and Relationships](/powersheet/concepts/entity-types-and-relationships)** define the structural connections that constraints then filter and scope
* **[Navigation Properties](/powersheet/concepts/navigation-properties)** use the `direct` and `back` directions that constraints influence when loading related entities

Together, these mechanisms form a layered governance model: the data model defines what entities exist and how they relate, cardinality limits the number of connections, and constraints ensure those connections stay within the correct structural boundaries.

## Common Misconceptions

**"Constraints block Polarion from storing data."** They do not. Constraints operate at the Powersheet application layer. A user with direct Polarion access or another tool can still create items outside the constraint boundaries. Constraints govern the Powersheet experience, not the underlying Polarion data store.

**"I need all three stages defined for every entity type."** In most cases, you only need `load` constraints. Thanks to cascading, `pick` inherits from `load` and `create` inherits from both. Define additional stages only when their scoping rules differ from the inherited behavior.

**"OR logic means I can match anything."** While OR broadens the filter, all constraints within a stage are still composed together. Two OR branches with contradictory conditions can still produce an empty result set. Always verify composed constraints against real data.

For practical guidance on implementing constraints in your data model, see [Creating Your First Data Model](/powersheet/getting-started/first-data-model) and the [Data Model Guides](/powersheet/guides/data-model/index).

***

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