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

# Update Risksheet

> Upgrade the Nextedy RISKSHEET plugin to a newer version while preserving your existing configuration, Velocity templates, document data, and user assignments.

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

Before starting the update process, ensure you have:

* Polarion administrator access on the target server
* The new Risksheet plugin version downloaded from the Nextedy website
* A complete backup of your current Polarion installation
* Access to a non-production test environment for validation
* Knowledge of your current Risksheet version (check **Administration** > **Nextedy Risksheet** > **License**)

<Steps>
  <Step title="Back Up Your Environment">
    1. Back up your Polarion server data directory including all project data
    2. Export any custom sheet configurations you have modified at the document level
    3. Back up custom Velocity templates (`risksheetTopPanel.vm`, `risksheetPdfExport.vm`) if you have customized them
    4. Record your current Risksheet version from **Administration** > **Nextedy Risksheet** > **License**
    5. Document the Polarion version running on the server (from **Administration** > **About Polarion**)

    <Tip title="Always test in a non-production environment first">
      Risksheet releases can occasionally be pulled back due to discovered regressions. Always deploy updates to a staging or test environment and validate all critical workflows before applying the update to production. This includes testing document loading, PDF export, and any custom Velocity templates.
    </Tip>
  </Step>

  <Step title="Remove the Old Plugin Version">
    1. **Stop the Polarion server** completely
    2. Navigate to the `[POLARION_INSTALL]/polarion/extensions/` directory
    3. **Delete** the existing Risksheet plugin folder entirely (e.g., `com.nextedy.risksheet_24.7.0`)
    4. Verify that no other Risksheet version folders remain in the `extensions/` directory

    <Warning title="Delete the old version -- do not copy over it">
      A common and critical update mistake is copying the new plugin folder over the old one instead of deleting the old version first. This results in two plugin versions coexisting in the `extensions/` directory, which causes the Risksheet menu to disappear from the Polarion navigation for all users. **Only one version folder per Nextedy product is allowed in the extensions directory.**
    </Warning>
  </Step>

  <Step title="Install the New Version">
    1. Copy the new Risksheet plugin folder into `[POLARION_INSTALL]/polarion/extensions/`
    2. Delete the `[POLARION_INSTALL]/data/workspace/.config` directory to clear all plugin caches
    3. Optionally, delete the `[POLARION_INSTALL]/data/workspace/.metadata` directory if you experience persistent issues after the update
    4. Start the Polarion server

    <Frame>
      <img src="https://mintcdn.com/none-17b4493f/-Icoak49xQVOW38R/risksheet/diagrams/guides/administration/update/diagram-1.svg?fit=max&auto=format&n=-Icoak49xQVOW38R&q=85&s=3eb102d973e26cf05b52243ebc9d3e3c" alt="diagram" style={{ maxWidth: "400px", width: "100%" }} width="400" height="380" data-path="risksheet/diagrams/guides/administration/update/diagram-1.svg" />
    </Frame>

    <Warning title="Clear plugin caches after every update">
      After installing or updating Risksheet, you **must** delete the `[POLARION_INSTALL]/data/workspace/.config` directory to clear plugin caches. Failure to do so is a known cause of empty Setup and License pages in the Polarion administration interface. This step is required for every update, not just the initial installation.
    </Warning>
  </Step>

  <Step title="Verify the Update">
    After the Polarion server has started successfully:

    1. Log in to Polarion as an administrator
    2. Navigate to **Administration** > **Nextedy Risksheet** > **License**
    3. Confirm the version number matches the newly installed release
    4. Navigate to **Administration** > **Nextedy Risksheet** > **Setup**
    5. Verify the setup page loads correctly and displays template installation options
    6. Open an existing Risksheet document and confirm the grid renders with all columns and data
    7. Test PDF export on at least one document to verify Velocity template compatibility
    8. Check the Polarion server logs for any new exceptions or warnings

    <Tip title="Check server logs proactively">
      After an update, review the Polarion server logs for the first 15 minutes of operation. Look for `UnsupportedOperationException` (harmless on versions prior to 24.7.0 running on Polarion 2310), query parsing errors, or template rendering failures. Address any new exceptions before rolling out to end users.
    </Tip>
  </Step>

  <Step title="Handle License Group Changes (v25.11.0+)">
    If you are updating to Risksheet version 25.11.0 or later and have both Risksheet and Powersheet installed with production licenses, a license group migration is required.

    **Background:** Starting with v25.11.0, when both products are installed, Risksheet reads user assignments from the `nextedy_powersheet_users` group instead of the legacy `nextedy_risksheet_users` group. This is a license unification change that aligns user management across Nextedy products.

    **Migration steps:**

    1. In Polarion Administration, create a `nextedy_powersheet_users` global user group if it does not already exist
    2. Add all members from the `nextedy_risksheet_users` group to the new `nextedy_powersheet_users` group
    3. Navigate to **Administration** > **Nextedy Risksheet** > **License** and verify the named user count reflects the expected number of users
    4. Keep the `nextedy_risksheet_users` group in place for backward compatibility until all projects have been verified

    <Warning title="License group migration is mandatory when Powersheet is installed">
      When both Risksheet and Powersheet are installed with production licenses, upgrading to v25.11.0 or later without creating the `nextedy_powersheet_users` group causes the License page to show **0 named users configured** and all Risksheet licenses to appear inactive. Users will lose access to Risksheet until the group is created and populated.
    </Warning>

    | Scenario                             | User Group for Named Users | Notes                 |
    | ------------------------------------ | -------------------------- | --------------------- |
    | Risksheet only (any version)         | `nextedy_risksheet_users`  | No migration needed   |
    | Risksheet + Powersheet (pre-25.11.0) | `nextedy_risksheet_users`  | Legacy behavior       |
    | Risksheet + Powersheet (25.11.0+)    | `nextedy_powersheet_users` | Migration required    |
    | Risksheet + Powersheet (26.1.0)      | `nextedy_powersheet_users` | Improved license flow |
  </Step>

  <Step title="Post-Update Configuration Check">
    After verifying the core installation, check the following configuration aspects:

    1. **Custom Velocity templates** -- Open documents that use custom `risksheetTopPanel.vm` or `risksheetPdfExport.vm` templates. Verify the panels render correctly and PDF exports produce expected output.

    2. **Project-level settings** -- Navigate to project administration and verify Risksheet project properties are intact:
       * Template path configuration (default: `Risks/Risk Specification`)
       * Tool name customization (default: `Risksheet`)
       * Document name labels (default: `Risk Analysis` / `Risk Analyses`)
       * Suggester settings (fuzzy search, wildcard search, result limit)

    3. **Custom queries** -- If your sheet configuration files contain custom `query` properties in `dataTypes.risk` or `dataTypes.task`, verify these Lucene queries still parse correctly. Polarion version upgrades can change query processing behavior.

    4. **Template installation** -- If the new Risksheet version includes updated project templates, consider re-installing them via **Administration** > **Nextedy Risksheet** > **Setup**. Note that template re-installation overwrites previous template versions.
  </Step>
</Steps>

## Troubleshooting Update Issues

| Symptom                                         | Likely Cause                                    | Resolution                                                                       |
| ----------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------- |
| Empty Setup and License pages                   | Plugin cache not cleared                        | Delete `[POLARION_INSTALL]/data/workspace/.config`, restart Polarion             |
| Risksheet menu not appearing in navigation      | Two plugin versions in extensions directory     | Delete the old version folder; only one version per product is allowed           |
| `UnsupportedOperationException` in server logs  | Document field rendering issue on Polarion 2310 | Non-harmful log error; fixed in Risksheet 24.7.0+                                |
| License page shows 0 named users                | License group migration needed (v25.11.0+)      | Create `nextedy_powersheet_users` group and add users                            |
| Unparseable query errors after update           | Polarion Auto Assignment configuration conflict | Check Polarion Auto Assignment settings, not Risksheet config                    |
| Risksheet not activating in some projects       | Post-maintenance configuration drift            | Verify version compatibility and complete all update steps including Setup check |
| Grid renders but text formatting is incomplete  | Partial update or cache issue                   | Clear browser cache, delete `.config` directory, restart server                  |
| `backLink` parameter errors when creating tasks | Known bug in versions prior to 24.11.0          | Update to Risksheet 24.11.0 or later                                             |

<Tip title="Persistent issues after update">
  If the Risksheet menu does not appear after following all steps, try also deleting the `.metadata` folder at `[POLARION_INSTALL]/data/workspace/.metadata` and restarting the Polarion server. This forces a complete plugin re-initialization.
</Tip>

## Verification

You should now see:

* The new Risksheet version number displayed on the **License** page in Administration
* The **Setup** page loading correctly with template installation options
* All existing Risksheet documents rendering with their full column layout and data
* The Risksheet menu visible in the Polarion navigation panel for all configured projects
* PDF export producing formatted output using your Velocity templates
* The correct number of named users on the License page (after license group migration if applicable)

## See Also

* [Troubleshoot Administration Issues](/risksheet/guides/administration/troubleshooting) -- resolve common post-update problems
* [Manage User Groups](/risksheet/guides/licensing/user-groups) -- handle license group migration details
* [Assign Active Users](/risksheet/guides/licensing/assigning-active-users) -- configure named user assignments
* [Installation](/risksheet/getting-started/installation) -- first-time Risksheet setup instructions
* [Add Risksheet to Existing Project](/risksheet/guides/administration/project-setup) -- add Risksheet to projects after installation

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