Upgrading Grooper to a New Version - 2021

From Grooper Wiki
Jump to navigation Jump to search

So you're ready to upgrade?


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

The upgrade process is essentially three steps:

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

Depending on your Grooper install, your upgrade process may be slightly more involved. If you are running scripts in your environment to customize Grooper's functionality, you may need to update the associated Object Libraries code. However, these three basic steps will apply to all upgrades.

How To

Perform a Simple Upgrade

You should always perform a complete backup of your filestore and Grooper database before upgrading to any newer Grooper version.
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.

Starting Point

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

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

  1. 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.
  2. 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).


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.

  1. 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:

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


  1. Select "Tools" from the toolbar.
  2. Select "Validate Branch..."
  3. This will bring up the "Validate Branch" window.
  4. Press the "Validate" button.
  5. 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.
  6. 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 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.

  1. Access a list of your currently installed programs by traversing the following path in Control Panel
    • Control Panel\Programs\Programs and Features
  2. Select Grooper from the program list.
  3. Press the "Uninstall" button. If it appears, confirm you want to uninstall on the subsequent dialog box.
  4. 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

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:


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.


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.

  1. Select the Repositories' property.
  2. Press the ellipsis button at the end of the property.


Notice two things about our Grooper Repositories here:

  1. 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.
  2. 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).


  1. To upgrade a Grooper Repository, select the repository that needs upgrading.
  2. Press the "Upgrade..." button in the upper toolbar.
  3. An "Upgrade" window will appear.
  4. Press the "Execute" button to confirm the upgrade.


  1. You will be prompted to execute a Version Upgrader.
  2. 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.


  1. After the upgrade is complete, press the "Test Connection.." button to ensure you're now property connected to the upgraded database.
  2. If successful you will see the following message window. Press Ok.
  3. You will see the upgraded Grooper Repository's Status change from "NeedsUpgrade" to "Ok".
  4. Press the "Ok" button to exit the Repositories window.


Congratulations! You've upgraded Grooper.

  1. 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.
  • 2021-upgrading-grooper-repo-connection-6.png