Skip to main content
This page explains the integration architecture — why Powersheet works the way it does inside Polarion, and what that means for configuration, security, and day-to-day use.

​
No Separate Data Store

The most important architectural decision in Powersheet is that it stores nothing outside Polarion. Every piece of data you see in a Powersheet sheet is a Polarion work item, every relationship is a Polarion link role, and every configuration file lives in Polarion’s SVN repository. Think of Powersheet as a specialized lens over data that already exists in Polarion. When you open a sheet, Powersheet reads the domain model and sheet configuration from SVN, translates your view into Polarion Lucene queries, and renders the results as an interactive hierarchical sheet. When you save changes, those changes are written directly to Polarion work items through Polarion’s own APIs. This means:
  • No data synchronization — there is no ETL process or replication lag between Powersheet and Polarion. The sheet always shows the current state of your work items.
  • No backup complexity — backing up Polarion backs up everything Powersheet needs.
  • No migration burden — if you stop using Powersheet, your work items and links remain exactly as they were in Polarion.
Because Powersheet reads and writes Polarion data directly, any change made in a Powersheet sheet is immediately visible in Polarion’s standard work item views, LiveDocs, and reports — and vice versa.

​
How Powersheet Embeds in Polarion

Powersheet registers itself as a web application within Polarion’s embedded application server at startup. The plugin descriptor makes all Powersheet endpoints available through Polarion’s standard web infrastructure. From the user’s perspective, Powersheet appears as a native page within the Polarion web interface — it shares the same browser session, the same navigation chrome, and the same URL structure. diagram Every request to Powersheet passes through Polarion’s authentication layer. Users do not need separate login credentials — if they are authenticated in Polarion, they can access Powersheet. This also means Polarion’s session management, SSO integration, and session timeout policies all apply automatically.

​
Configuration Storage in SVN

All Powersheet configuration — domain models and sheet configurations — lives as YAML files in Polarion’s SVN repository. This is a deliberate design choice with several consequences: Version control is built in. Every change to a domain model or sheet configuration is tracked as an SVN revision. You can view the change history, compare versions, and revert to a previous configuration using standard Polarion tools. Project isolation is natural. Each Polarion project has its own SVN directory tree, so project-level configurations are automatically scoped. Global configurations reside in a shared _global location, providing defaults that any project can inherit or override. Deployment is instant. When you save a configuration change through the administration pages, it is written to SVN and takes effect on the next sheet load. There is no build step, no deployment pipeline, and no server restart required.
Domain models and sheet configurations are stored under the .polarion/nextedy/ directory within each project’s SVN structure. Global configurations use the same path under the _global project. The administration interface manages these files automatically — you do not need to interact with SVN directly.
For a detailed comparison of global and project-level configuration scope, see Global vs Project-Specific Configuration.

​
Administration Interface

Powersheet extends Polarion’s native administration interface rather than providing a separate management console. This means administrators work in the same environment they already know, with the same permission controls and the same navigation patterns. The administration pages are available at three scope levels:
ScopeAccess PathWhat It Controls
GlobalAdministration > Nextedy POWERSHEET (repository-wide)Default configurations available to all projects
Project GroupAdministration > Nextedy POWERSHEET (project group level)Configurations shared by projects in a group
ProjectAdministration > Nextedy POWERSHEET (project level)Configurations specific to one project
Within each scope, the administration interface provides:
Admin PagePurpose
Domain ModelsCreate and edit domain model YAML files that define entity types, relationships, and properties
Sheet ConfigurationsManage sheet configuration YAML files that control column layout, formatting, and behavior
SetupInitial Powersheet configuration and system settings
LicenseLicense key management and status
The administration pages embed a file manager interface that lets you create, edit, rename, and delete YAML configuration files directly in the browser. Changes are saved to SVN immediately.

​
Document-Centric Model

Every Powersheet sheet is anchored to a Polarion LiveDoc document. This is not an arbitrary constraint — it reflects a deliberate design principle: a sheet is a view of a document’s structured content, not a free-floating report. The connection between a document and its sheet configuration works through a custom field:
  1. The Polarion document has a nextedySheetConfig custom field.
  2. This field references the sheet configuration file to use (either by file path or by enum selection).
  3. When Powersheet opens the document, it reads this field and loads the corresponding YAML configuration from SVN.
The configuration field supports both string values (direct file paths) and enum options. When configured as an enum, Polarion provides a dropdown picker that scans available configuration files at both global and project scope, making it easy for document authors to assign the right configuration.
The nextedySheetConfig field must reference the configuration ID, not the display name. Using the display name is a frequent source of “configuration not found” errors during initial setup. See Troubleshooting for resolution steps.
The document URL follows the pattern #/project/{projectId}/powersheet?document={folder/name}, which means you can bookmark, share, and link to specific Powersheet documents just like any other Polarion page.

​
Entity Type and Work Item Mapping

Powersheet introduces the concept of entity types as an abstraction layer over Polarion work item types. Rather than working directly with Polarion work item types in your sheet configuration, you define entity types in the domain model and map them to their corresponding Polarion types: 
domainModelTypes:
  UserNeed:
    polarionType: userNeed
    properties:
      title:
      severity:
  SystemRequirement:
    polarionType: systemRequirement
    properties:
      title:
      status:
This indirection is valuable because:
  • Naming independence — your domain model can use names that make sense in your engineering context (UserNeed, Hazard, RiskControl) regardless of what the Polarion work item types are called internally.
  • Property filtering — the domain model exposes only the properties that matter for your traceability analysis, hiding irrelevant Polarion fields from the sheet.
  • Relationship modeling — the domain model defines how entity types relate to each other using Polarion link roles, with explicit cardinality and navigation direction.
When Powersheet executes a query, the server API translates entity type references into Polarion Lucene queries scoped to the mapped polarionType. Properties resolve to Polarion custom fields and built-in fields. Relationships resolve to Polarion link roles with the direct and back navigation directions. For deep coverage of how entity types and relationships work, see Entity Types and Relationships and Navigation Properties. Powersheet registers a navigation extension that adds Powersheet Drive as a topic in the Polarion sidebar. This provides a centralized document browser — users can see all Powersheet documents in the current project at a glance, without navigating through Polarion’s folder hierarchy. By default, Powersheet Drive lists all documents that have a nextedySheetConfig field value. The query that controls which documents appear can be customized through a project property: 
com.powersheet.powersheetDocumentQuery=type:powersheet OR HAS_VALUE:templateDoc.KEY
This flexibility means you can:
  • Show only documents of a specific document type
  • Include template documents for easy duplication
  • Filter by custom criteria using Polarion Lucene syntax
Powersheet Drive also supports template documents. When templates are included in the query results, users can duplicate them to create new Powersheet documents with a preconfigured sheet configuration already assigned.

​
Security and Permission Inheritance

Powersheet inherits Polarion’s entire security model rather than implementing its own. This has practical implications at several levels: Authentication: Powersheet uses Polarion’s authentication realm. If your Polarion instance uses LDAP, SAML, or another SSO provider, Powersheet respects it automatically. There are no separate user accounts to manage. Project access: Users can only open Powersheet documents in projects they have access to. Polarion’s project role assignments control who can view or edit. Work item permissions: When Powersheet renders a sheet, it respects Polarion’s work item-level permissions. If a user cannot edit a specific work item type in Polarion, they cannot edit it in Powersheet either. Property-level control: The domain model adds a finer-grained layer through entity metadata annotations. Properties can be marked as isReadOnly in the server metadata, controlling whether a column is editable in the sheet. These annotations complement (but do not override) Polarion’s native permission model.
The interaction between Polarion’s native permissions and Powersheet’s domain model property annotations depends on your specific configuration. Test your permission setup to confirm the expected read/write behavior for each user role.
For details on how permissions flow through Powersheet, see User Roles and Permissions.

​
Revision and Baseline Support

Powersheet supports opening documents at historical revisions and baselines. When a revision parameter is specified in the URL, Powersheet loads the document state as it existed at that point in time. Historical views are inherently read-only — users can inspect past states of their traceability data without any risk of accidental modification. This is particularly valuable in regulated environments where teams need to demonstrate the state of requirements or risk analyses at specific milestones. Because Powersheet reads directly from Polarion’s data store, revision support requires no additional infrastructure. Polarion’s own revision mechanism (backed by SVN for documents and the work item history for field values) provides the temporal data that Powersheet renders.

​
The Integration Mental Model

If you are coming from standalone spreadsheet or database tools, the most important mental shift is this: Powersheet does not own data. It does not import, export, replicate, or cache your work items. It provides a configurable, hierarchical view directly over Polarion’s native data structures. This means:
  • Changes propagate instantly in both directions
  • Polarion reports, dashboards, and LiveDocs always reflect edits made in Powersheet
  • Existing Polarion workflows, notifications, and automations continue to work
  • Standard Polarion backup and disaster recovery procedures cover Powersheet completely
The only artifacts Powersheet adds to your Polarion environment are YAML configuration files in SVN and the nextedySheetConfig custom field on documents.
Ticket Insights
  • Configuration setup guidance: incremental approach recommended for new users
  • Model connection errors: sources.model must match custom model name
  • Document type constraints must use type ID, not display name
  • Multi-item linked columns require multiItem: true in sheet configuration
Source Code
  • PowersheetService.java — document creation, retrieval, and Lucene query translation
  • PowersheetDocumentConfigurationService.java — YAML configuration loading from SVN
  • PowersheetConfigProperties.java — project-specific properties and customizable queries
  • admin.cy.ts — administration interface scope levels and file manager integration