Upgrading Grooper to a New Version - 2023

So you're ready to upgrade?

About

‼

IMPORTANT!!! NEW GROOPER ARCITECTURE DETECTED - PROJECTS

Projects are a new way of organizing Grooper resources in the node tree. After upgrading, all your resources will work as they did before, but their organization will shift from certain parts of the node tree to a Project named "Project 1". You may choose to move resources out of this Project and into new Projects or you can choose to keep everything in "Project 1". For more information and guidance, refer to the links below:

Project - This is the full Projects article. It has general information about what Projects are and how to use them.
Projects and Upgrading to 2023 - This contains specific guidance around upgrading from an older version of Grooper to version 2023, how to navigate the new Project architecture, and how to move from "Project 1" to new Projects.

Upgrading to 2023 is now easier than ever. You can upgrade directly from version 2.72, 2.80, 2.90, 2021, or 2022 to version 2023 (For upgrading from versions older than 2.72, you must upgrade to 2.72 before upgrading to 2023).

The upgrade process is essentially three steps:

Uninstall the older version of Grooper.
Install Grooper 2023.
Upgrade Grooper Repositories from the older version to 2023.

⚠

This article instructs users on how to perform simple upgrades. The instructions in this article outline the basic steps for all upgrades.

However, depending on your Grooper install, your upgrade process may be more involved.

If you are running scripts in your environment to customize Grooper's functionality, you may need to update the associated scripting code and Object Libraries, as some code objects may have been altered or obsoleted or their names may have changed.
- If present, make sure you re-compile all Object Libraries after the upgrade.
- Custom scripts are not guaranteed to work without changes upon upgrading to a new major version of Grooper.
If you are running custom reports polling the Grooper database, you may need to update the report query, as Grooper's database tables may have changed.
If you are using expressions in your Batch Processes, IP Profiles, Data Models or Import/Export Mappings, please verify all expressions are working as intended as some as some code objects may have been altered or obsoleted or their names may have changed.
If you are moving across multiple major versions, it's likely Grooper's architecture has changed more than if upgrading from one major version to the next. Your solution design may not be taking advantage of newly added features in newer versions.
- In all cases, you should take some time to test your Grooper system after an upgrade to ensure everything is working as expected. When upgrading across multiple major versions, please take extra care to do so.

How To Perform a Simple Upgrade

FYI

If you are upgrading from version 2.72, 2.80 or 2.90, 2021, or 2022 to 2023, you may upgrade directly to version 2023. However, if you are upgrading from version 2.70 (or older) to 2023, you must first upgrade to version 2.72, and then upgrade to version 2023.

‼

IMPORTANT!!! DON'T FORGET TO BACKUP YOUR REPOS

You should always perform a complete backup of your Grooper Repository's file store and database before upgrading to any newer Grooper version.

If, for whatever reason, something goes wrong during the upgrade process and your file store and/or database is corrupted, you could loose critical components, such as your Batch Processes, Content Models, or document files for any Test or Production Batches.
Performing a backup will ensure you have something to revert to in the rare cases where the upgrade does improperly overwrite existing database values or files in your file store.

For information how to backup and restore your Grooper database and file store, please visit the article below:

Backup and Restore Grooper Repository

Before You BeginStop ServicesUninstall GrooperInstall the New Grooper VersionUpgrade Grooper Repositories

Backup and Validate Your Grooper Repository

You should always perform a complete backup of your Grooper Repository's file store and database before upgrading to any newer Grooper version. If, for whatever reason, something goes wrong during the upgrade process and your file store and/or database is corrupted, you could loose critical components, such as your Batch Processes, Content Models, or document files for any Test or Production Batches. Performing a backup will ensure you have something to revert to in the rare cases where the upgrade does improperly overwrite existing database values or files in your file store.

For information how to backup and restore your Grooper database and file store, please visit the article below:

Backup and Restore Grooper Repository

FYI

Repository validation can only be performed on the Grooper thick client. You cannot validate from the web client.

While not strictly necessary, the Grooper developers strongly encourage you perform validation on your Grooper Repository before upgrading from and older version to a newer version of Grooper. Improperly configured nodes can cause unexpected issues during upgrade. Validating your repository helps catch these configuration issues to avoid configuration related problems when upgrading the objects in your existing repository to the newer versions of those objects.

For example, a Data Type extractor object whose Collation property is set to Key-Value Pair must have a Layout specification as part of its configuration. If this is left unconfigured, validation will catch the configuration error.

The Data Type selected in the Node Tree here does not have a Layout enabled.

To validate your Grooper Repository and catch configuration errors like the one described above perform the following steps:

In Grooper Design Studio, select the root of the repository's Node Tree in the Tree View window.

Select "Tools" from the toolbar.
Select "Validate Branch..."
This will bring up the "Validate Branch" window.
Click the "Validate" button.
Grooper will check every object in your repository for any property configuration errors. Any object with configuration errors will be listed here.
- By choosing the validate the root, you validate all descendent branches. In other words, the whole repo.
You may select any object in the list and click the "Go To Item" button to go to that object and resolve the configuration error, if you so choose.

Stop Services

Before uninstalling your current version of Grooper, you will need to stop all services currently running in Grooper Config. This will help avoid potential errors regarding the services connected to your repositories.

Open Grooper Config and click "Edit Services".
If you have any services running they will be listed with a green dot to the left side. You can select each individual service and click "stop" or you can just click "Stop All".
Once a service is stopped, the dot to the left of the service name should turn red.

⚠

If you do not stop running Grooper services, there is a chance a duplicate Windows service will be installed when the new version of Grooper is reinstalled.

If this does occur, you will need to manually delete the service from the Windows Registry Editor, using the following steps:

Open the Registry Editor (regedit.exe)
Navigate to the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services key.
Select the key of the service you want to delete.
From the "Edit" menu select "Delete.
You will be prompted "Are you sure you want to delete this Key?". Click Yes.
Exit the Registry Editor.

Back up your Database and File Store

⚠

You should always perform a complete backup of your Grooper Repository's file store and database before upgrading to any newer Grooper version.

If, for whatever reason, something goes wrong during the upgrade process and your file store and/or database is corrupted, you could lose critical components, such as your Batch Processes, Content Models, or document files for any Test or Production Batches.

Performing a backup will ensure you have something to revert to in the rare cases where the upgrade does improperly overwrite existing database values or files in your file store.

For information how to backup and restore your Grooper database and filestore, please visit this article.

Uninstall the Current Version of Grooper

The first thing you need to do is uninstall the current version of Grooper before installing the new version. This can be done in a number of ways, such as uninstalling from your settings menu.

Open your Windows Settings and click on "Apps".
Scroll down through your list of apps until you find the Grooper application. Click on the app. When it expands, click on "Uninstall".
A small window may pop up to confirm you wish to uninstall the app. Click "Uninstall".
Wait for the application to be uninstalled.

Install the New Grooper Version

If you have not done so, you will need to download the current installer file from Grooper xChange. Zip archives containing the installer files can be found in the "Downloads and Resources" section, linked bellow

https://https://xchange.grooper.com/categories/downloads-and-resources

Once downloaded, unzip the installer file, open the "Setup" executable file and follow the onscreen instructions to install the current Grooper version. If you need more help, you can find the full Grooper installation instructions by following the link below:

Installing the Grooper Product Suite

Additional Guidance for Web Client Deployments

If you are upgrading the Grooper web client, you must also uninstall the Grooper Web Client application on your web server and install the newer version.
- IMPORTANT It is best practice to stop the Grooper app pool in IIS before uninstalling the Grooper Web Client application.
After upgrading the Grooper web server, if you have remote scan workstations with Grooper Desktop installed, you will also need to uninstall Grooper Desktop and install the newer version on each workstation.

|}

Upgrade Grooper Repositories from Grooper Config

After installing Grooper 2023, open Grooper Config to upgrade the previous versions of Grooper Repositories to 2023.

FYI

Major versions of Grooper change the Grooper Database in meaningful ways. These changes to the database must be reflected by upgrading the Grooper Repository. For major version upgrades (For example, 2.80 to 2021 or 2021 to 2023), all Grooper Repositories configured on an older version must be upgraded in order to connect to them to Grooper.

For minor version upgrades (For example, 2.90.0001 to 2.90.0002) you do not need to upgrade each Grooper Repository. No major changes are made to the Grooper Database, and you can skip this step.

However, you should still always uninstall the old version of Grooper before installing the new version, even when upgrading to a new minor version.

When upgrading from a version older than 2021 to version 2021 or later, you'll notice the Grooper Config application's UI has changed. Previously, Grooper Repository connections were listed in a grid. Now, we will need to get into the Repositories configuration window to upgrade the previous versions of the Grooper Repositories to the new versions.

Select the Repositories property. Click the ellipsis button at the end of the property.
Currently, Grooper version 2023 is installed on this machine. As seen here, in Grooper Config, we have two Grooper Repository connections: one named "okcstrpa01_001" and the other "okcstrpa01_002". The Grooper Repository named "okcstrpa01_001" is a networked repository. Its status is listed as "Ok" because it has already been updated to Grooper 2023. This repository's version matches the version of Grooper installed on this machine. The Grooper Repository named "okcstrpa01_002" is another networked repository. Its status is listed as "Needs Upgrade" because it has not been updated to Grooper 2023 yet. After upgrading to Grooper 2023 you will need to upgrade all previous repositories to 2023.
To upgrade a Grooper Repository, select the repository that needs upgrading. Click the "Upgrade..." button in the upper toolbar.
An "Upgrade" window will appear. Click the "Execute" button to confirm the upgrade.
You will be prompted to execute a Version Upgrader. Click "Execute" to start the upgrader.
When the upgrader is finished, click "Ok". In instances where you are upgrading multiple versions of Grooper (i.e. 2.80 to 2021) you must run each Version Upgrader sequentially. For example, in our case, we had to execute the Version 2021 to 2022 Upgrader first, followed by the Version 2022 to 2023 Upgrader. Repeat steps 6. and 7. for each version of Grooper you are needing to upgrade.
After the upgrade is complete, click the "Test Connection.." button to ensure you're now property connected to the upgraded database. If successful, a message box will pop up confirming your connection. Click Ok.
You will see the upgraded Grooper Repository's Status change from "NeedsUpgrade" to "Ok". Click the "Ok" button to exit the Repositories window.
Click the "Save" button in the main screen of Grooper Config to complete the upgrade.
Congratulations! You've upgraded Grooper.