> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Work with Branched Documents

> Enable Nextedy RISKSHEET to display and manage risk items within branched Siemens Polarion ALM LiveDoc documents, supporting referenced and overwritten work items across document branches.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

## Prerequisites

* Polarion administrator access to set project administration properties
* An existing Risksheet document to branch from
* Familiarity with Polarion document branching

<Steps>
  <Step title="Enable Branching Support">
    Branching support is controlled at the **project administration** level, not in the sheet configuration. Navigate to **Administration > Nextedy Risksheet > Setup** and add the following project administration property:

    ```
    nextedy.risksheet.branchingSupport=true
    ```

    <Warning title="Case-Sensitive Property Name">
      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.
    </Warning>
  </Step>

  <Step title="Branch a Document">
    1. Open the source LiveDoc containing your risk analysis in Polarion.
    2. Use Polarion's standard branching mechanism to create a branch of the document.
    3. 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.

    <Frame>
      <img src="https://mintcdn.com/none-17b4493f/yWl5nA2D0IzEnZC1/risksheet/diagrams/guides/integration/branched-documents/diagram-1.svg?fit=max&auto=format&n=yWl5nA2D0IzEnZC1&q=85&s=3c4698fcb9953dbfefc5bc6e0cbf5654" alt="diagram" style={{ maxWidth: "520px", width: "100%" }} width="520" height="270" data-path="risksheet/diagrams/guides/integration/branched-documents/diagram-1.svg" />
    </Frame>
  </Step>

  <Step title="Enable Editing of Referenced Work Items (Optional)">
    If you need users to edit referenced items in branched documents without overwriting them, set the following **project administration property** (available since v23.3.3):

    ```
    nextedy.risksheet.editableReferencedWorkItems=true
    ```

    <Info title="Project administration property, not sheet configuration">
      `editableReferencedWorkItems` is a **project administration property** configured under **Administration > Nextedy Risksheet > Setup** (v23.3.3+). It is NOT a property of the sheet configuration. Setting it inside the sheet configuration has no effect — the engine reads it only from project administration.
    </Info>

    When this property is enabled, referenced work items in branched documents become directly editable in the grid without requiring an overwrite operation. Verify the behavior in your Risksheet version before relying on it for production workflows, as changes may propagate to the source document depending on configuration.
  </Step>

  <Step title="Overwrite Referenced Items">
    To create a local copy of a referenced risk item in your branched document:

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

    <Warning title="Overwriting Loses Links">
      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.
    </Warning>
  </Step>

  <Step title="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.

    <Tip title="Clear Cache After Branching">
      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.
    </Tip>

    <Tip title="Enable branchingSupport for document.id queries">
      If your Risksheet shows no data after branching, verify that `nextedy.risksheet.branchingSupport` is set to `true` in the project administration. This property is required for `document.id`-based queries to populate data correctly. Without it, the grid may appear empty in branched documents.
    </Tip>
  </Step>
</Steps>

## 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` project property, v23.3.3+) | 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                    |

<Warning title="Release field limitation">
  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.
</Warning>

For detailed variant management configuration, see [Configure Variant Management](/risksheet/guides/integration/variant-management).

## refreshOnSave Interaction

When using branched documents with the sheet configuration property `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

## See Also

* [Configure Variant Management](/risksheet/guides/integration/variant-management) — manage product variants with branched documents
* [Configure Upstream Traceability Columns](/risksheet/guides/columns/upstream-traceability) — set up traceability in risk tables
* [Configure Cross-Project Linking](/risksheet/guides/advanced/cross-project-linking) — link work items across projects
* [Troubleshoot Administration Issues](/risksheet/guides/administration/troubleshooting) — resolve common configuration issues

<LastReviewed date="2026-06-24" />