Work with Branched Documents - Nextedy Documentation

Prerequisites

Polarion administrator access to set system properties
An existing Risksheet document to branch from
Familiarity with Polarion document branching

Step 1: Enable Branching Support

Set the Polarion system property to activate branching features. Navigate to Administration > Configuration Properties and add:

nextedy.risksheet.branchingSupport=true

The property name uses lowercase n in nextedy.risksheet.branchingSupport. The value is case-sensitive — using an uppercase N or incorrect casing will silently fail to enable branching support.

Step 2: Branch a Document

Open the source LiveDoc containing your risk analysis in Polarion.
Use Polarion’s standard branching mechanism to create a branch of the document.
Open the branched document in Risksheet.

After branching, risk items from the source document appear as referenced work items in the branched document. These items display in read-only mode by default.

Step 3: Enable Editing of Referenced Work Items (Optional)

If you need users to edit referenced items in branched documents without overwriting them, add the editableReferencedWorkItems property to your risksheet.json:

{
  "global": {
    "editableReferencedWorkItems": true
  }
}

The editableReferencedWorkItems property allows direct editing of referenced work items in branched documents. Verify the exact behavior in your Risksheet version, as this may affect how changes propagate to the source document.

Step 4: Overwrite Referenced Items

To create a local copy of a referenced risk item in your branched document:

Right-click the referenced row in the Risksheet grid.
Select Overwrite Row Item from the context menu.
The item changes from reference mode to overwrite mode, becoming fully editable.

When you overwrite an upstream work item in a branched document, all existing links are removed except the “is branched from” relationship. If your workflow requires preserving traceability links, you may need a custom script to restore backlinks after overwriting.

Step 5: Handle Document Queries

When branching support is enabled, Risksheet automatically adjusts its data queries to use the document.id parameter. This ensures that only work items belonging to the current branched document are displayed.

If the Risksheet view does not display expected items after a branching operation, clear the Polarion cache. Branching operations may require a cache refresh for the updated document structure to be recognized.

If your Risksheet shows no data after branching, verify that nextedy.risksheet.branchingSupport is set to true. This property is required for document.id-based queries to populate data correctly. Without it, the grid may appear empty in branched documents.

Variant Management with Branches

For projects that need release-based filtering across branches, Risksheet supports the assignedReleases document custom field to filter downstream items by release version. This is useful in variant projects where you maintain separate branches per product release.

Capability	Status
Branch a document and view referenced items	Supported
Overwrite referenced items to create local copies	Supported
Edit referenced items without overwriting (`editableReferencedWorkItems`)	Supported
Filter by release using `assignedReleases` field	Supported (one release per document)
Multi-release document filtering	Not yet supported
Reference risks across non-branched sheets	Not yet supported

The release filtering is currently hardcoded for the multiEnum release field. Assign only one release per document for reliable filtering. Multi-release filtering within a single document view is not yet available.

For detailed variant management configuration, see Configure Variant Management.

refreshOnSave Interaction

When using branched documents with refreshOnSave set to false, be aware of two behaviors:

A “Discard changes” popup may appear when navigating away, even though changes were saved successfully. This is a known side effect of the non-refresh mode.
The overwrite context menu option requires refreshOnSave to be enabled (the default). If you have disabled it, the overwrite option will not appear.

Known Limitations

Limitation	Description
Cross-sheet referencing	Referencing risks from other non-branched Risksheet documents is not supported
Link preservation	Overwriting upstream items removes all links except “is branched from”
Multi-release filtering	Documents assigned to multiple releases cannot be filtered per-release
Workaround for multi-release	Separate design and risk items into different LiveDocs

Verification

You should now see referenced items from the source document displayed in read-only mode when you open a branched Risksheet document. Verify that:

Referenced items appear with read-only styling in the grid
Right-clicking a referenced item shows the Overwrite Row Item option
Overwriting an item converts it to an editable local copy
The “is branched from” link is preserved after overwriting

​Prerequisites

​Step 1: Enable Branching Support

​Step 2: Branch a Document

​Step 3: Enable Editing of Referenced Work Items (Optional)

​Step 4: Overwrite Referenced Items

​Step 5: Handle Document Queries

​Variant Management with Branches

​refreshOnSave Interaction

​Known Limitations

​Verification

​See Also

Prerequisites

Step 1: Enable Branching Support

Step 2: Branch a Document

Step 3: Enable Editing of Referenced Work Items (Optional)

Step 4: Overwrite Referenced Items

Step 5: Handle Document Queries

Variant Management with Branches

refreshOnSave Interaction

Known Limitations

Verification

See Also