Skip to main content

​
The design principle

In a model-driven system, configuration files describe what should happen, not how it should happen. The domain model declares entity types, their properties, and their relationships. The Powersheet runtime reads this declaration and automatically generates the metadata, queries, pickers, and validation rules needed to render and edit the data. This is the opposite of a code-driven approach where each new entity type or relationship would require custom development. With Powersheet, adding a new entity type is a YAML change, not a code change. diagram

​
From YAML to metadata

When a powersheet document is opened, the domain model YAML is processed through a metadata generation pipeline. Each domainModelTypes entry becomes an entity type with:
  • A primary key property (objectId)
  • A polarionType property linking to the Polarion work item type
  • Built-in properties: title, icon, and automatically added document and project navigation properties
  • Custom properties from the properties section, each mapped to Polarion work item fields
The relationships section is similarly processed. Each relationship creates navigation properties on both the source and target entity types (using fromNavPropName and toNavPropName), enables expansion paths for loading related data, and establishes the link to a Polarion link role for persistence. Two built-in entity types are always available regardless of the domain model configuration:
Entity typePurpose
DocumentRepresents Polarion modules (LiveDocs). Exposes properties like moduleName, moduleFolder, title, and allowedWITypes
ProjectRepresents Polarion projects. Automatically linked to all work item entity types

​
The mapping layer

A key advantage of model-driven design is that the domain model acts as a mapping layer between Polarion’s native data structures and the Powersheet view. This is significant because:
  • Different projects can have different Polarion type names for the same conceptual entity. The domain model normalizes these: one project’s sys_requirement and another’s systemReq can both map to a SystemRequirement entity type in the domain model.
  • Link roles vary between projects. The domain model abstracts them behind navigation property names, so the sheet configuration remains identical.
  • A single sheet configuration can be reused across projects that share the same domain model structure but differ in Polarion-level details.
This mapping layer is why the domain model and sheet configuration are separate files. The domain model handles project-specific Polarion mappings, while the sheet configuration handles presentation concerns. Changing one does not require changing the other.

​
Constraints as declarations

Beyond entity types and relationships, the domain model supports declarative constraints that control runtime behavior:
  • load constraints: filter which entities are loaded from the query (e.g., load only work items from documents of a specific type)
  • create constraints: set default values for newly created entities (e.g., automatically assign to a specific document based on context)
  • pick constraints: filter which entities appear in selection pickers (e.g., show only SystemRequirement items from documents matching the source entity’s component)
Constraints can use dynamic context references like $context.source.document.component to resolve values at runtime based on the current user’s context. This enables sophisticated data routing without custom code.

​
Properties and permissions

The domain model also controls property-level permissions through readable and updatable flags on each property. When readable is set to false, the property is hidden in the sheet. When updatable is false, the property is displayed but cannot be edited. These permissions intersect with Polarion’s native security model. A user must have both the domain model permission and the Polarion field-level permission to edit a property.
The exact interaction between domain model permissions and Polarion security depends on the server configuration. The domain model can only restrict access further — it cannot grant permissions beyond what Polarion allows.

​
Practical implications

The model-driven approach has several practical consequences for administrators:
  1. All customization happens in YAML files — no code changes, no deployments, no server restarts
  2. Changes are versioned in Polarion’s SVN repository — configuration history is preserved and auditable
  3. Domain models can be shared globally — define once, use across multiple projects
  4. Errors are configuration errors, not code errors — debugging means checking YAML syntax and property references
For tutorials on building domain models, see Creating Your First Data Model. For understanding how the domain model relates to the sheet configuration, see Data Model vs Sheet Configuration.
Source Code
  • model.yaml
  • todosBig_model.yaml
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/e2e/admin/admin.cy.ts
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/fixtures/models/constraints-base.yaml
  • rtm_model.yaml