> ## 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.

# Configure Variant Management

> Set up Nextedy RISKSHEET to manage product variants and release-specific risk analyses using branched documents, assigned releases, and document-scoped filtering.

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

* Branching support enabled in your Polarion environment
* Polarion administrator access for custom field configuration
* Familiarity with Polarion document branching and release management

## How Variant Management Works

Risksheet supports variant management through branched documents combined with release-based filtering. A base project contains the master risk analysis, while variant projects branch from it for specific product releases. Each variant filters downstream items by an `assignedReleases` document custom field, showing only the mitigation tasks and controls relevant to that release.

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

<Steps>
  <Step title="Enable Branching Support">
    Variant management builds on Risksheet's branching capabilities. Ensure the branching property is set in your project administration (the project-scoped Risksheet properties), not in the Polarion system configuration:

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

    For the full setup, see [Work with Branched Documents](/risksheet/guides/integration/branched-documents).

    <Warning title="Case-Sensitive Property">
      Use lowercase `n` in `nextedy.risksheet.branchingSupport`. An uppercase `N` will silently fail and branching features will not appear.
    </Warning>
  </Step>

  <Step title="Set Up the Release Custom Field">
    Create a document-level custom field to track which product release each risk document belongs to:

    1. Navigate to **Administration > Document Configuration > Custom Fields**
    2. Create a custom field named `assignedReleases` of type `multiEnum`
    3. Define your release values (e.g., `v1.0`, `v2.0`, `v3.0`)
    4. Apply the field to your risk analysis document types

    <Info title="Verify in application">
      The `assignedReleases` field is used to filter downstream items by release version. Verify the exact field name and type supported in your Polarion environment.
    </Info>
  </Step>

  <Step title="Create a Variant Project Structure">
    For complex variant management, set up a dedicated project structure:

    1. Keep your **base project** with the master risk analysis documents
    2. Create **variant projects** by branching the base project for each release
    3. Assign the appropriate release value to each branched document using the `assignedReleases` field

    <Tip title="Multiple Risksheet Configurations Per Project">
      Risksheet supports multiple different configurations within a single project. Each document can have its own sheet configuration attached, so variant documents can use different column layouts, formulas, or filtering rules than the base project documents. No mandatory fields or work item types are required -- the tool is fully configurable.
    </Tip>
  </Step>

  <Step title="Configure Release-Based Filtering">
    In the variant project's Risksheet configuration, set up downstream item filtering based on the assigned release. The `assignedReleases` document custom field controls which downstream items appear in the Risksheet view for each release.

    <Warning title="Single Release per Document">
      The release filtering currently supports assigning one release value per document. Assigning multiple releases to a single document does not yet enable per-release filtering within the Risksheet view. As a workaround, create separate documents for each release.
    </Warning>
  </Step>

  <Step title="Scope Items to Documents">
    Use the `document` property in your `dataTypes` configuration to restrict linked items to specific LiveDocs, preventing the Risksheet from showing mitigation tasks from other documents or releases:

    ```yaml theme={null}
    dataTypes:
      task:
        type: measure
        role: has_measure
        document: Risks/FMEA Measures
    ```

    You can also use `createInCurrentDocument` to control whether new upstream items are stored in the current document rather than a shared location. This keeps variant-specific items scoped to the correct release context.
  </Step>

  <Step title="Handle Overwritten Items in Variants">
    When working with branched variant documents, you may need to modify items originally inherited from the base project:

    1. Right-click the referenced item in the Risksheet grid
    2. Select **Overwrite Row Item** from the context menu
    3. The item changes from `reference` type to `overwrite`, becoming a local editable copy

    The overwrite functionality is only available when the item's `systemReferenceType` is `reference`. After overwriting, the item can be edited independently of the base project version.

    <Warning title="Link Loss on Overwrite">
      Overwriting upstream work items in branched documents removes **all existing links** except the "is branched from" relationship. Plan for this by:

      * Documenting link structures before overwriting
      * Using custom scripts to restore backlinks after the overwrite
      * Clearing the Polarion cache after branching operations to ensure fresh data
    </Warning>
  </Step>
</Steps>

## Known Limitations

| Limitation                                              | Workaround                                                |
| ------------------------------------------------------- | --------------------------------------------------------- |
| Multi-release document filtering not available          | Assign one release per document, or use separate LiveDocs |
| Overwriting removes all links except "is branched from" | Custom script to restore backlinks                        |
| Release field currently hardcoded to multiEnum          | Assign only one release per document                      |
| Cache may become stale after branching                  | Clear Polarion cache after branching operations           |

## Verification

After setting up variant management:

1. Open a branched variant document in Risksheet
2. You should now see only downstream items filtered by the assigned release
3. Referenced items from the base project should display as read-only
4. Overwriting an item should create a local editable copy in the variant
5. Verify that new items created in the variant are scoped to the correct document

## See Also

* [Work with Branched Documents](/risksheet/guides/integration/branched-documents) -- enable and configure branching support
* [Configure Cross-Project Linking](/risksheet/guides/advanced/cross-project-linking) -- link work items across variant projects
* [Configure Downstream Tasks](/risksheet/guides/risk-management/downstream-tasks) -- set up mitigation task traceability
* [Use Project Templates](/risksheet/guides/integration/project-templates) -- integrate Risksheet with custom project templates
* [Configure Queries](/risksheet/guides/advanced/query-configuration) -- customize data queries for variant filtering

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