Powersheet Architecture

This page explains the architectural layers, how data flows between them, and how security is enforced — giving you the mental model needed to reason about configuration changes, troubleshoot loading behavior, and plan data model design.

​

High-Level Architecture

The diagram above captures the key insight: there is no external database, no middleware cache, no separate service to operate. Powersheet is an in-process Polarion extension. YAML configuration and work item data both reside in the same Polarion SVN repository. When you edit a cell in the sheet, the write goes directly to Polarion’s work item API — not to an intermediary.

​

No Separate Data Store

This is the single most important architectural concept to internalize. Unlike tools that synchronize data to an external database, Powersheet works entirely within Polarion:

• Work items are the rows in the sheet. They are standard Polarion work items, queryable and editable through any Polarion interface.
• Link roles connect work items across entity types. Powersheet reads and writes these native Polarion links — it does not maintain its own relationship tables.
• Custom fields on work items store property values. Powersheet columns bind to these fields through the data model.
• YAML files stored in the project SVN repository define what data to show and how to present it. They are version-controlled alongside the rest of the project.

This design means that anything you do in a Powersheet is immediately visible in Polarion’s native views and vice versa. There is no synchronization lag, no import/export step, and no risk of data divergence between the sheet and the underlying platform.

​

Three-Tier Architecture

​

Server Extension

The server extension runs as a Java plugin inside the Polarion application server process. It handles four responsibilities: The server extension registers four administration pages within Polarion at Administration > Nextedy Powersheet:

• Data Models — file manager for data model YAML files
• Sheet Configurations — file manager for sheet configuration YAML files
• Setup — initial setup and configuration
• License — license status and management

These pages are available at project, project group, and repository (global) scope, following Polarion’s standard administration hierarchy.

​

Client Application

The client application runs in the user’s browser and renders the interactive sheet. It receives the parsed configuration and typed metadata from the server, then builds the sheet UI with:

• Hierarchical row expansion based on the data model’s expansion paths
• Inline cell editing with type-aware editors (text, dropdowns, reference pickers)
• Column filtering and sorting including multi-column sort
• Row grouping by column values with collapsible headers
• Copy and paste with level-aware restrictions that prevent cross-hierarchy paste errors
• Keyboard shortcuts for common operations (add row, export, freeze columns, grouping)

The client uses a data guard mechanism that blocks rendering until the metadata system has fully initialized. This prevents displaying an empty sheet while data is still loading — a common source of confusion when network latency is high.

​

Configuration Layer

All behavior in Powersheet is driven by two types of YAML files: The data model acts as a semantic abstraction layer over Polarion’s native work item types and link roles. You can reuse the same sheet configuration across projects that have different Polarion type setups — only the data model mapping needs to change. The sheet configuration is assigned to a document through a custom field on the Polarion LiveDoc. When a user opens that document, Powersheet reads the assigned configuration and renders the sheet accordingly. For a deeper comparison, see Data Model vs Sheet Configuration.

​

Data Flow: Loading a Sheet

The following diagram traces the sequence from the moment a user opens a Powersheet document to the fully rendered sheet. The load sequence in detail:

1. Document opens — The document’s custom field identifies which sheet configuration to use
2. Server loads YAML — The server reads the sheet configuration and the referenced data model from the SVN repository
3. Metadata generation — The server generates a typed metadata schema from the data model and sends it along with the configuration to the client
4. Client initializes — The client builds columns from the configuration, sets up type-aware editors, and prepares the sheet structure
5. Data query execution — The client issues queries that the server translates to Polarion Lucene queries, expanding along configured expansion paths to load related entities at each level
6. Sheet renders — All rows, columns, formatting, and grouping are applied

After initial load, the configuration and metadata remain cached in the client. Subsequent user actions (editing cells, adding rows, creating links) interact directly with the server API, which writes through to the Polarion data layer. No YAML reload occurs during normal editing — you only need to refresh the page when you change the configuration itself.

​

Security Architecture

Powersheet runs entirely inside the customer’s Polarion environment. It adds no independent authentication system and no external network exposure — its servlets run within Polarion’s web container and are reachable only through an authenticated Polarion session. Security is a shared responsibility between the Polarion platform and Powersheet. Handled by Polarion — user authentication and authorization (roles, permissions, project access), session management, HTTPS/TLS, Content Security Policy, CSRF protection on state-changing operations, network and OS/JVM/database hardening, central logging, secure secrets storage through the User Account Vault, and the SQL/Lucene query restrictions that are on by default since Polarion 2410. Powersheet relies on these and never bypasses or replaces them. Handled by Powersheet — correct and secure use of the Polarion APIs, respecting the authenticated user context, safe rendering of user-controlled data, conservative default query and processing limits, and keeping regular usage clearly separated from privileged configuration.

​

Authentication

Powersheet has no login screen of its own; it requires an active Polarion session. Users authenticate through Polarion’s standard mechanisms (SSO, LDAP, or local accounts) before the widget loads.

​

Permission Enforcement

Every data operation goes through the Polarion API, which applies the user’s project, work item, and field-level permissions — if a user lacks write permission on a work item, the server rejects the save regardless of what the client UI allows. Powersheet maintains no access-control lists of its own. Client-side cues (read-only columns, workflow-locked and calculated fields) give immediate UI feedback but are never the sole enforcement; the server independently validates every write.

​

Privileged, Scriptable Configuration

Powersheet configuration is centrally managed and treated as privileged, because it can include advanced or scriptable behavior:

• Storage — configuration lives in the Polarion SVN repository (the project’s .polarion location). Polarion’s default permission schemes restrict write access to these paths to administrators; regular users have no write access.
• Management — configuration is edited through administration interfaces intended for users with at least Project Administrator privileges (Administration > Nextedy Powersheet).
• Regular users work with Powersheet data through the configured views but cannot modify configuration or inject custom logic.
• Scripting — customization can use server-side JavaScript, client-side JavaScript, or server-side Velocity, all with access to the Polarion Open/Rendering APIs and Nextedy APIs. It is restricted to trusted roles and is not sandboxed beyond that role restriction.

​

Safe Rendering

Administrator-configured rendering contexts (custom cell renderers, top-panel content, formulas, and other template-driven output) control how work item data is displayed; their safety depends on the Polarion API the configuration uses:

• Rendering API (e.g. $workItem.title.render) performs built-in HTML sanitization and is recommended for all administrator-configurable rendering.
• Open API / raw access (e.g. $workItem.title) returns unsanitized content; when it is used, the administrator must escape the output — for example $esc.html($workItem.title) on LiveDocs and LiveReport Pages.

​

Configuration Scoping

Powersheet configuration operates at three levels, following Polarion’s standard administration hierarchy: Project-level configurations supplement global ones. A project can reference a global data model while defining its own sheet configurations, or vice versa. This enables organizations to maintain a standard entity model centrally while allowing individual projects to customize their column layouts. For details on how global and project-level configurations interact, see Global vs Project-Specific Configuration.

​

Where Each Component Lives

Understanding the physical location of each component clarifies what is deployed, what is configured, and what is stored:

​

Related Pages

• Core Components — Detailed look at each building block
• Data Model vs Sheet Configuration — Why two YAML files exist and how they divide responsibilities
• Model-Driven Design — How the data model shapes the entire sheet experience
• Polarion Integration — How Powersheet extends the Polarion platform
• Global vs Project-Specific Configuration — Configuration inheritance and scoping
• YAML Configuration System — How configuration files are discovered and loaded