Upgrade from version 5#

The setup wizard's Import a Reportworq v5 repository option copies a v5 repository into a new v6 repository. That import does not apply any v5 repository upgrades on the way in. It expects the repository it is given to already be at the current v5 layout, and it does not check the version, so importing an older repository completes without error but leaves data behind, silently.

This page gets a v5 repository current before you import it. Do it first, then follow Import a Reportworq v5 repository in First-run setup.

Before you begin#

• Access to the v5 repository you plan to import, and a way to back it up.
• Either the original v5 instance and server, or just a copy of the repository (this page covers both).
• For the copy-only path: a Windows server to install Reportworq v5 5.0.0.93 on, and an elevated command prompt on it.

Why this matters#

A v5 repository is upgraded in place the first time a newer v5 build starts against it, the same way any product applies its own schema upgrades on startup. Three of those upgrades changed the repository layout enough that a v6 import misses data if they have not already run:

• 5.0.0.81 moved security from permission sets to groups and entitlements. A repository imported from before this version comes across with no groups and no entitlements, so no one has access to the imported workspace, including administrators.
• 5.0.0.85 reorganized contribution runtime storage (input forms and their data). A repository imported from before this version does not bring its contribution runtime data across correctly.
• 5.0.0.91 converted global variables to global parameter values. A repository imported from before this version loses its global variables.

A repository that was already started on v5 5.0.0.91, 5.0.0.92, or 5.0.0.93 has all three upgrades applied and can be imported directly. Installing a newer v5 build is not enough by itself. The repository has to have been started (or upgraded with the command in Method B below) on one of those versions.

Bring the repository to 5.0.0.91 or later before you import. 5.0.0.93, the latest v5 release, is recommended.

Back up the v5 repository first. Both methods below change it in place.

Method A: update and start the original v5 instance#

Use this when the v5 instance can still be run on its own server. It is the simplest path.

1. Update the v5 instance to the latest v5 release (5.0.0.93) using the normal v5 update process.
2. Start it, and let it finish starting: sign in, and confirm your jobs are listed.
3. Import the now-current repository into v6, see Import a Reportworq v5 repository in First-run setup.

Method B: upgrade a repository copy, without running the original instance#

Use this when the v5 instance cannot be run on its original server and you only have a copy of the repository, for example one copied from another server. This installs a temporary Reportworq v5 5.0.0.93 and uses it to apply the same upgrade steps v5 applies at startup, without ever starting the web server against your data.

1. Install Reportworq v5 5.0.0.93 on a Windows server. It does not need to be configured or pointed at your repository, and it does not need a license applied for this purpose.

2. Stop the Reportworq v5 Windows service and set its startup type to Disabled, so it cannot start on its own and touch anything while you work.

3. Back up the repository copy, for example:

   robocopy C:\data\repo C:\data\repo-backup /E
   

4. Open an elevated command prompt in the v5 install folder (the folder containing ReportWORQ.WebApp.exe) and run:

   ReportWORQ.WebApp.exe --upgrade-repo "C:\data\repo"
   

   The path must point at the repository root, the folder that directly contains Segments, Authentication, Settings, and Distributors. This command changes only the folder you pass. It does not start the web server and does not touch the installed instance's own settings or repository.

5. Check the result. An exit code of 0 means success and 1 means failure; check it immediately with echo %ERRORLEVEL%. Progress is written to the console and to Logs\rw_app_log-*.txt under the install folder. The command is safe to run again if you need to.

6. Optional sanity check: the repository should now have Authentication\<provider>\Groups and Authentication\<provider>\Entitlements folders, where <provider> is the sign-in provider you use, for example Native or ActiveDirectory.

7. Uninstall Reportworq v5 from the temporary server if you no longer need it there.

8. Import the upgraded repository into v6, see Import a Reportworq v5 repository in First-run setup. Import requires a Windows or Linux install; a Docker or Azure App Service deployment cannot import a v5 repository, see Install Reportworq.

After the import: the scheduler and Cloud API start off#

An imported repository is not yet verified, so the import deliberately leaves two things switched off so that a side-by-side migration cannot fire your production jobs or register a second connection to the cloud service while v5 is still live:

• The master scheduler is paused. Your schedules come across exactly as they were, each with its own enabled toggle unchanged, but none run until the master scheduler is on. When you are ready to cut over, turn it on with the Scheduler switch in the header of Scheduled Content, see Manage scheduled content.
• The Cloud API connection is disabled. The API key is copied over, but Enable Cloud API under Settings > Configuration > API is cleared. Select it and save when this instance should take over the connection from v5.

Known limit#

Very old jobs, authored in the v4 era, that still use a legacy parameter-value format are not repaired by either method and will not load in v6. After importing, check the v6 log for any jobs that failed to load.

Troubleshooting#

• After import, no one, including administrators, has access to anything. The repository was imported from before 5.0.0.81 and has no groups or entitlements. Restore your backup, bring the v5 repository to 5.0.0.91 or later using either method above, and import again.
• Contribution input forms or their data are missing or wrong after import. The repository was imported from before 5.0.0.85. Restore your backup, upgrade the repository, and import again.
• Global variables used in jobs are missing after import. The repository was imported from before 5.0.0.91, so they were never converted to global parameter values. Restore your backup, upgrade the repository, and import again.
• A Local API key or Microsoft 365 sign-in from an old v5 repository. A repository last started on a v5 build older than December 2024 can still hold these tokens in plaintext. The v6 import carries them across and stores them encrypted, rewrites the retained v5 copy with the token encrypted, and logs a warning naming the file (never the token). Nothing to do; check the v6 log if a key you expected is missing.
• The --upgrade-repo command exits with 1. Check Logs\rw_app_log-*.txt in the v5 install folder for the reason. Re-running the command is safe.
• A job fails to load after import. Check whether it is a v4-era job using the legacy parameter-value format, see Known limit above. These are not repaired by an upgrade and need to be recreated in v6.