Skip to main content

​
Revision Query Flow

diagram

​
Revision Parameter

ParameterTypeDefaultDescription
revisionintegernullDocument revision number to query. null means HEAD (latest). Must be >= 0.

​
URL Parameter

The revision is specified via the revision URL query parameter: 
/polarion/#/project/MyProject/powersheet?document=Requirements/SystemReqs&revision=42
ValueBehavior
Not specifiedShows latest data (HEAD)
0 or positive integerShows data at the specified revision

​
Setting Revision Programmatically

The revision can be changed without a full page reload. The URL parameters are updated and the data is re-fetched at the new revision.
Use the revision picker in the Powersheet UI to navigate between document revisions. Pass undefined to clear the revision and return to HEAD.

​
Read-Only Mode

Historical revisions are always displayed in read-only mode. The sheet enters read-only mode when any of these conditions is true:
ConditionDescription
revision is setViewing a historical revision
config.isReadOnly is trueConfiguration flag forces read-only
User has readOnly permissionPermission-based restriction
When viewing a historical revision, all editing operations (cell editing, row creation, row deletion, save) are disabled. The sheet displays data as it existed at the specified revision.

​
Query Execution with Revision

The query processor handles revisions at two levels:

​
1. Query Parameter Revision

The revision parameter in the entity query controls which historical version of the data is queried:
Parameter SourcePriorityDescription
Query parameter revisionHighestExplicitly set on the query
Context baselineLowerInherited from the query context baseline

​
2. Configuration Processing

When a revision is active, the configuration processor:
  • Injects the revision parameter into the main data source query
  • Appends the revision number to the document display name (e.g., SystemReqs (Rev 42))
  • Sets the sheet to read-only mode

​
Document Context with Revision

PropertyTypeDescription
document.fullstringFull document path (folder/name). Does not change with revision.
document.folderstringDocument folder/space component
document.namestringDocument name component
revisionintegerCurrent revision number, or null for HEAD
The document display name includes the revision when viewing historical data: 
SystemReqs (42)

​
Configuration URL with Revision

The configuration URL includes a cache-busting timestamp. When the revision changes, the configuration is re-fetched to ensure the correct version of the sheet configuration is loaded.
Configuration re-fetching on revision change depends on the server’s handling of revision-aware configuration. Verify that your Polarion server supports revision-specific configuration retrieval.

​
Entity Metadata at Revision

Entity query results at a specific revision include standard metadata fields:
FieldTypeDescription
objectIdstringUnique entity identifier
idstringPolarion work item ID
titlestringWork item title at the specified revision
updateddatetimeLast modification timestamp at or before the revision
projectIdstringProject foreign key

​
Baseline vs. Revision

ConceptDescription
RevisionA specific SVN revision number representing a point in the project’s history
BaselineA named project baseline that maps to a specific revision number
The query processor supports both approaches. The revision can come from an explicit query parameter or from a project baseline associated with the query context.
The relationship between Polarion project baselines and SVN revision numbers depends on your Polarion server configuration. Consult your administrator for baseline-to-revision mapping.

​
Complete YAML Example

sources:
  - id: requirements
    title: System Requirements
    model: rtm
    query:
      from: UserNeed
      where: "<WHERE>"
    constraints:
      applyCurrentDocumentTo: UserNeed
    expand:
      - name: systemRequirements
        title: System Requirements
        expand:
          - name: systemRequirement

columns:
  id:
    width: 80
    sort: asc
  title:
    width: 300
    hasFocus: true
  systemRequirements.systemRequirement.title:
    width: 250
  systemRequirements.systemRequirement.severity:
    width: 100
When this configuration is loaded with ?revision=42 in the URL, the query processor:
  1. Fetches UserNeed entities as they existed at revision 42
  2. Expands systemRequirements.systemRequirement at the same revision
  3. Displays the sheet in read-only mode
  4. Shows the document name with revision suffix
Source context: PolarionQueryProcessor, DocumentProvider, ConfigProvider, GenericQueryResolver
Source Code
  • PolarionQueryProcessor.java
  • prod-powersheet-src/com.nextedy.powersheet.client/src/modules/DocumentProvider/DocumentProvider.tsx
  • powersheet.yaml
  • GenericQueryResolver.java
  • prod-powersheet-src/com.nextedy.powersheet.client/src/modules/ConfigProvider/ConfigProvider.tsx