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

# Migration and Upgrade Questions

> This page answers common questions about upgrading Nextedy RISKSHEET, migrating sheet configurations between versions, and adopting new features that ship in incremental releases.

<Tip title="Start from a template, not from scratch">
  Whether you are adopting Risksheet for the first time or moving an existing analysis to a new version, begin from one of the Nextedy solution templates that matches your methodology (FMEA, HARA, TARA, STRIDE, CVSS). Templates carry verified `columns`, `levels`, `dataTypes`, `formulas`, `cellDecorators`, and `styles` sections. Modify a template to match your process rather than authoring a sheet configuration from a blank file. See [Configuration Examples](/risksheet/reference/examples/index) and the [Templates](/risksheet/reference/templates/index) reference.
</Tip>

<AccordionGroup>
  <Accordion title="What gets upgraded when I install a new Risksheet version?">
    A Risksheet upgrade replaces the server-side Polarion plugin and the client-side grid renderer. Your existing sheet configurations, top panel templates, PDF export templates, and Polarion work items are not modified by the upgrade. New configuration properties become *available* to use, but documents continue to function with their existing configuration until you opt in.
  </Accordion>

  <Accordion title="Do I need to migrate my existing sheet configuration after an upgrade?">
    In most cases no. Risksheet upgrades aim to be backwards-compatible — existing `columns`, `levels`, `dataTypes`, `formulas`, `cellDecorators`, and `styles` continue to work. Migration is typically needed only when you want to adopt a new property (for example `createInDocument` or `linkToRisksheet`) or fix a property name that was previously misspelled. See [Configuration Management](/risksheet/guides/configuration/index) for the recommended workflow.
  </Accordion>

  <Accordion title="Where do I edit a sheet configuration after I upgrade to v25.5.0 or later?">
    From version 25.5.0 onward, the configuration editor supports YAML editing with syntax highlighting, error detection, and history. Open the document menu and choose **Menu > Configuration > Edit Risksheet Configuration**. The underlying file remains the sheet configuration (`risksheet.json`) — the editor presents it as YAML so the file is easier to read and review.

    <Frame>
      <img src="https://mintcdn.com/none-17b4493f/-Icoak49xQVOW38R/risksheet/diagrams/faq/migration-faq/diagram-1.svg?fit=max&auto=format&n=-Icoak49xQVOW38R&q=85&s=ba34a75ad9375f70a3ef1af773d3f3fa" alt="diagram" style={{ maxWidth: "640px", width: "100%" }} width="640" height="220" data-path="risksheet/diagrams/faq/migration-faq/diagram-1.svg" />
    </Frame>
  </Accordion>

  <Accordion title="How do I add features that appeared in newer versions to an older configuration?">
    Newer properties can be added incrementally to an existing sheet configuration once the server has been upgraded to the required version. Examples include `createInDocument` for choosing where new tasks are created, `linkToRisksheet` on `dataTypes.task` for subsheet navigation, and dependent enums at the column level. Add only the properties you need and leave the rest of the configuration unchanged.

    <Info title="Verify in application">
      After adding a new property, open the document in Polarion and confirm the grid behaves as expected before rolling the change out to templates and child documents.
    </Info>
  </Accordion>

  <Accordion title="Which property changes most often cause issues after migrating between versions?">
    By far the most common is the column property `bindings` (plural). Some older or hand-edited configurations contain `binding` (singular), which silently fails because the column never resolves a Polarion field. When you migrate, search every `columns` entry and confirm the property is `bindings: <fieldId>`. The reference for column properties is in [Column Types](/risksheet/reference/columns/index) and [Fields](/risksheet/reference/fields/index).
  </Accordion>

  <Accordion title="My old configuration has `ratings`, `enums`, or `relations` at the top level — what should I do?">
    Remove them. Those three top-level sections do not exist in the real Risksheet engine — the engine ignores them entirely. Rating scales and enumerated values are defined as Polarion enumerations in **Administration > Nextedy Risksheet > Setup** and referenced from columns via `type: rating:<enumId>`, `type: enum:<enumId>`, or `type: multiEnum:<enumId>`. Dependent enums are a column-level feature available from v25.3.1, not a top-level configuration section.

    | Section in old config | What to do | Replacement mechanism                                                                                     |
    | --------------------- | ---------- | --------------------------------------------------------------------------------------------------------- |
    | `ratings: {}`         | Delete     | Define ratings as Polarion enumerations; reference with `type: rating:<enumId>`                           |
    | `enums: {}`           | Delete     | Define enums as Polarion enumerations; reference with `type: enum:<enumId>` or `type: multiEnum:<enumId>` |
    | `relations: []`       | Delete     | Configure dependent enums at the column level (v25.3.1+)                                                  |
  </Accordion>

  <Accordion title="How does template inheritance interact with upgrades?">
    A document inherits configuration from its template at the point of creation and on subsequent **Refresh from Template** actions. After an upgrade, you can update a template first, validate it on a sandbox document, and then propagate the change to existing documents at your own pace. Because all data lives in Polarion work items and not in a Risksheet-private store, refreshing a configuration never moves or rewrites your risk items. See [Templates](/risksheet/reference/templates/index) and [Configuration Management](/risksheet/guides/configuration/index).
  </Accordion>

  <Accordion title="What changes when I upgrade between Polarion licensing tiers?">
    The licensing tier affects what users can do, not how Risksheet is configured. Three tiers are supported: ALM, Requirements, and QA licenses provide full create-and-modify access; the PRO license can modify existing Risksheet rows but cannot create new ones; the REVIEWER license is read-only. See [Licensing](/risksheet/guides/licensing/index) and the [Licensing Model](/risksheet/faq/licensing-model) FAQ for details.
  </Accordion>

  <Accordion title="How do I migrate a saved view configuration from older docs to a current configuration?">
    Older generated documentation sometimes used the property name `columns` for saved views — the real property name is `columnIds`. When migrating a `views` entry, rename the array to `columnIds` and check whether you want to use the `@all` shorthand or the `-columnId` exclude prefix:

    ```yaml theme={null}
    views:
      - name: Full Analysis
        defaultView: true
        columnIds:
          - "@all"
      - name: Initial Risk Ranking
        columnIds:
          - failureMode
          - severity
          - occurrence
      - name: No Up/Down Risks
        columnIds:
          - "@all"
          - "-upstreamRisks"
    ```

    The `defaultView` property (v24.1.0+) marks which view loads first when the document opens. See [Saved Views](/risksheet/guides/columns/index) under column configuration guides.
  </Accordion>

  <Accordion title="Will my custom JavaScript in formulas and cell decorators still work after upgrading?">
    Yes — `formulas` and `cellDecorators` are evaluated client-side and are not transformed by upgrades. The recommended pattern, especially in regulated industries, is to keep `formulas` thin and define the heavy logic (risk matrices, multi-field conditional formatting) in the top panel configuration (`risksheetTopPanel.vm`). This separation keeps the sheet configuration auditable while custom logic stays under code review. See [Formulas](/risksheet/reference/formulas/index) and [Styling](/risksheet/reference/styling/index).
  </Accordion>

  <Accordion title="Where do I check whether a feature requires a minimum Risksheet version?">
    The configuration reference for each property notes the minimum version where applicable. Examples include `editableReferencedWorkItems` (v23.3.3+), `checkLinkRoleCompliance` (v24.2.2+), `createInDocument` (v24.8.1+), `moduleOnlyPermissions` (v24.8.5+), the dependent enum column feature (v25.3.1+), and YAML editing in the configuration editor (v25.5.0+). Before adopting a property, confirm your server is at least at the listed version. See [Compatibility](/risksheet/reference/compatibility/index) and [Configuration](/risksheet/reference/configuration/index).

    <Warning title="Coordinate Polarion and Risksheet upgrades">
      Risksheet runs inside Polarion ALM. Always verify the Polarion version your environment runs and the Risksheet plugin version are compatible before upgrading either component. Your Polarion administrator should perform the upgrade and run a sandbox validation before changing production templates.
    </Warning>
  </Accordion>
</AccordionGroup>

## Related pages

* [Configuration Questions](/risksheet/faq/configuration) — general configuration questions
* [Licensing Questions](/risksheet/faq/licensing) — license tiers and entitlement
* [Common Troubleshooting](/risksheet/faq/troubleshooting-faq) — issues seen during and after upgrades
* [Configuration Management](/risksheet/guides/configuration/index) — how to roll configuration changes safely
* [Compatibility](/risksheet/reference/compatibility/index) — version requirements per property