Upgrading Grooper to a New Version - 2022

So you're ready to upgrade?

About

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

The upgrade process is essentially three steps:

1. Uninstall the older version of Grooper.
2. Install Grooper 2022.
3. Upgrade Grooper Repositories from the older version to 2022.

⚠

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.

‼

IMPORTANT!! The organization of object resources in the node tree has changed drastically in version 2022 with the introduction of Projects. For more information on Projects please visit the following: Project - This is the full Projects article. It has general information about the new Project object in Grooper. Projects and Upgrading to 2022 - This contains specific guidance around upgrading from an older version of Grooper to version 2022 and how to navigate the new Project architecture.

How To Perform a Simple Upgrade

‼

IMPORTANT!! 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 filestore, please visit this article.

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

Before You BeginStep 1: Uninstall GrooperStep 2: Install the New Grooper VersionStep 3: Upgrade Grooper Repositories

Starting Point

In this tutorial, we will upgrade a version 2021 Grooper installation to version 2022.

Currently, Grooper version 2.80 is installed on this machine. As seen here, in Grooper Config, we have two Grooper Repository connections: one named "Grooper" and the other "Grooper280". The Grooper Repository named "Grooper" is a networked repository which has already been upgraded to the newest version of Grooper. The Status column indicates this by listing "Newer Version". We will not be able to connect to this Grooper Repository in Grooper Design Studio or Grooper Dashboard until this machine installs the newest Grooper version in "Step 2" of this tutorial. The Grooper Repository named "Grooper280" is a networked repository which has not been upgraded yet. Since this repository's version matches the version of Grooper installed on this machine its Status is listed as "Ok". In "Step 3" of this tutorial, we will upgrade this Grooper Repository's database to the newest Grooper version, thus upgrading all its objects (Batch Processes, Content Models, etc).

⚠

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 filestore, please visit this article.

Validate Your Grooper Repository

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. Press 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 press the "Go To Item" button to go to that object and resolve the configuration error, if you so choose.

Click Me to Return to the Top

Step 0: 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 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 filestore, please visit this article.

Step 1: 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 the Windows Control Panel. Access a list of your currently installed programs by traversing the following path in Control Panel Control Panel\Programs\Programs and Features Select Grooper from the program list. Press the "Uninstall" button. If it appears, confirm you want to uninstall on the subsequent dialog box. Reboot your computer after the program finishes uninstalling. You should get a notification a reboot is required to complete the setup like the one seen here.

Step 2: 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: Install and Setup - 2021#Installing the Grooper Product Suite

Step 3: Upgrade Grooper Repositories from Grooper Config

After the installer has finished running, open Grooper Config to upgrade the older versioned Grooper Repositories to the newly installed version.

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), all Grooper Repositories configured on an older version must be upgraded in order to connect to them in Grooper Design Studio or Grooper Dashboard. 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.

Upon upgrading from a version older than 2021 to version 2021, the first thing you'll probably notice is the Grooper Config application's UI has changed. Previously, Grooper Repository connections were listed in a grid upon opening the Grooper Config application. Now, Grooper Repository connections are accessed using the Repositories property. We will need to get into the Repositories configuration window to upgrade the older versioned Grooper Repository to the newly installed version. Select the Repositories' property. Press the ellipsis button at the end of the property.
Notice two things about our Grooper Repositories here: The repository named "Grooper" now matches the current version (2021). It's Status is listed as "Ok". Any Grooper Repository whose version matches the currently installed version of Grooper will have a Status of "Ok". This means we can now connect to this repository in Grooper Design Studio. Whereas, before upgrading, we couldn't. The repository named "Grooper280" is still on the older version (2.80) and needs to be upgraded. Its Status is listed as "NeedsUpgrade" Any Grooper Repository whose version is older than the currently installed version of Grooper will have a Status of "NeedsUpgrade". Before we can connect to this repository in Grooper Design Studio, we need to upgrade the repository, upgrading the Grooper database to the current version (and therefore upgrading all the objects in the Grooper Repository to the current version).
To upgrade a Grooper Repository, select the repository that needs upgrading. Press the "Upgrade..." button in the upper toolbar. An "Upgrade" window will appear. Press the "Execute" button to confirm the upgrade.
You will be prompted to execute a Version Upgrader. 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 2.80 to 2.90 Upgrader, followed by the Version 2.90 to 21.0 Upgrader.
After the upgrade is complete, press the "Test Connection.." button to ensure you're now property connected to the upgraded database. If successful you will see the following message window. Press Ok. You will see the upgraded Grooper Repository's Status change from "NeedsUpgrade" to "Ok". Press the "Ok" button to exit the Repositories window.
Congratulations! You've upgraded Grooper. Don't forget to press the "Save" button in the main screen of Grooper Config. ⚠ IMPORTANT - If present, make sure you compile all Object Libraries after the upgrade. IMPORTANT - The devs also strongly recommend that you perform validation on your repository after upgrading. • Object Libraries should be compiled before validating your repository to ensure best results.