2023:Install and Setup

From Grooper Wiki

This article is about an older version of Grooper.

Information may be out of date and UI elements may have changed.

202520242023202220212.90

Welcome to Grooper 2023!

This guide will instruct you how to get up and running in Grooper.  There are three parts of installing and setting up Grooper:

  1. Installing the Grooper Product Suite
  2. Connecting to a Grooper Repository
    • This section of the article article explains both how to create a new Grooper Repository as well as connecting to an existing one.
  3. License Activation


At the end of this article, you will also find guidance for upgrading an older version of Grooper to the current version.

About

Thank you for purchasing/upgrading to Grooper 2023!

NEW! Expanded Web Client!

In previous versions of Grooper, it was necessary to fully install the software on each server and client workstation you wanted to have access to Grooper. No matter if they were designing your Grooper environment or reviewing documents, Grooper had to be installed on each machine. This could cause difficulties in managing the software on multiple workstations. Furthermore, each user would need read and write access to the Grooper Repository's database and file store location. This could present a security risk to your SQL and file store environments, as the more users have access, the more risk there is of untoward intrusion.

With Grooper 2023, Grooper can be fully hosted on a web server. Users can then connect to the Grooper web application via web browser. This means the software only has to be fully installed on one server! This makes everything a lot easier to manage, as there's no more need to install Grooper on each user's workstation. Furthermore, web deployment is more secure. The only user who needs access to the Grooper database and file store is the web server's IIS account.

  • Web deployments require additional setup to get Grooper up and running over the web. For information on how to install the web client, please be sure to check out the Installing and Configuring the Web Client section of this article.
  • For more information on other new features in Grooper 2023, check out the What's New In Grooper 2023 article.

Installing the Grooper Product Suite

PLEASE NOTE: If you are upgrading an existing install, there are some additional things you need to be aware of. Please visit the Upgrading an Older Version of Grooper section of this article.

To get up and running with Grooper 2023, there are several applications that need to be installed and configured.

  • Grooper: This primary application installs the Grooper thick client and Grooper Config.
  • Microsoft SQL Server: This is a database server software developed by Microsoft for Windows. SQL Server is required to create Grooper Repositories.
  • Internet Information Services (IIS): This is web server developed by Microsoft for Windows. It is necessary to host the Grooper web client.
  • Grooper Web Server: With this application properly installed and configured, multiple users can access Grooper remotely via web browser.
  • Grooper Desktop: This application is only necessary for remote scanning when using the Grooper web client.

⚠

In some cases, antivirus software will interfere with Grooper's installation, preventing a complete install.

  • You may need to whitelist the Grooper installers/software before installing.
    • This will ensure the antivirus software is not preventing DLL files from installing or executing.

Most commonly, this issue has been demonstrated when installing the Grooper Desktop application (required to scan using the web client).

  • If Grooper Desktop is installed correctly, and you are able to scan using the scanner's native software, you may need to (1) uninstall Grooper Desktop, (2) whitelist the Grooper Desktop installer and GrooperDesktop.exe application and (3) reinstall Grooper Desktop to ensure you can scan from the Grooper web client.

Prerequisite Install: MS SQL Server

After installing the Grooper Product Suite for the first time, the first thing you will do is create a Grooper Repository. A Grooper Repository consists of two things: (1) a database and (2) a file store. For the Grooper database, you will need to connect to a Microsoft SQL server instance.

As such, you will need to install Microsoft SQL Server. This may be done on the same machine as the one where Grooper is installed or on a separate one. However, for larger installs, we recommend a dedicated server for the Grooper SQL Server.


Full SQL server requirements are documented below.

  • Windows Server 2016 or later is required.
  • SQL Server 2014 or later is required.
  • The Grooper database should allow for a size of 20GB or more.
  • The scaling of the Grooper database should be set to percentage, ideally, not the default of a few MB. This will reduce frequent scaling that hinders performance.
  • The SQL Port is 1433.
  • Grooper can technically run on Microsoft SQL Server Express as well. However, we would only recommend this for small testing environments not production environments.

Downloading Grooper Installers

If you have not registered at Grooper xChange, do so by clicking the link below.

https://xchange.grooper.com/entry/register

Once you've registered, you will have access to the user forum, including the "Downloads and Resources" section. Follow the link below to the "Download and Resources" section. The top level topic will have download links to the most recent version of Grooper. Links to older versions are available lower in the list of topics.

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

Click on the link for Grooper 2023. Here you will see four links to downloads: The 64-bit installer, the 32-bit installer, Grooper Desktop Installer, and Grooper Web Server Installer.

  • The 64-bit installer is appropriate for most environments.
  • If you are setting up a web server to host the Grooper web client, you must use the 64-bit installer.
    • You will also need to download the Grooper Web Server installer.
  • If you are using ISIS or TWAIN drivers to operate a scanner:
    • For thick client installations, you will need to install the 32-bit version on scanning workstations.
    • For web client installations, you will need to install the Grooper Desktop application on scanning workstations.

The installer files will download as zipped folders. You will need to extract each zipped folder. Right-click a folder and select "Extract All..."

  1. Choose the folder location you wish to extract the files to.
  2. Click the "Extract" button.

Now you should have all your files extracted and are ready to install the software. Click on the next tab for installation instructions.

Installing Grooper

  1. Open up File Explorer and navigate to your extracted folders.
  2. Open the extracted folder "GrooperInstall_23.00.xxxx" to reveal the installation files.

  2. Double-click "setup.exe" to start the Grooper Installer.

⚠

If this is your first time installing Grooper, you may have some prerequisites to install (Microsoft Visual C++, Access Database Engine, and the Microsoft .NET Framework). If you already have these installed from a previous Grooper installation, please skip to step #8.

  2. When the InstallShield Wizard for Grooper pops up, click "Install" to start installing the prerequisite applications.

FYI

You may already have the Microsoft .NET Framework installed, but this prerequisite installation will check to make sure that all components necessary for Grooper to run are present.

  2. Once Microsoft Visual C++ is installed, your server may require a restart. When prompted, please restart.

  2. After restarting, open File Explorer and navigate back to the setup.exe file and double-click again to restart the InstallShield Wizard.
  3. Click "Install" to continue installing the prerequisite applications.

  2. Once complete, the Grooper installer will pop up. Click "Next" to move to the next screen.

  2. After reviewing the Welcome page to the InstallShield Wizard, click "Next" to continue.

  2. Read through the End User License Agreement and click the radial button next to "I accept the terms in the license agreement".
  3. Click "Next" to continue.

  2. Now you can choose the location where you want the Grooper Application to be installed. It is recommended to use the default file path, but based on your business needs, you may choose a different area for the installation on your server.
  3. Once you are satisfied with the installation location, click "Next".

  2. Select the radial button next to your preferred setup type.
    • Generally we recommend performing a Complete setup of Grooper onto your server, but there are some cases where you might want to customize your installation depending on your business needs.
  3. Click "Next".

  2. You are now ready to install the program. Click "Install" to begin installation.

  2. Installation should only take a few minutes. When complete, a window should pop up saying that the installation is complete. Click "Finish" to finalize your installation.

Installing and Configuring the Web Client

To stand up a Grooper 2023 web server, there are three things that need to be installed first:

  1. The Grooper product suite
    ⚠  It is best practice to install the Grooper product suite first, before installing the Grooper Web Client application.
  2. Internet Information Services (IIS)
  3. The Grooper Web Client application

FYI

Desktop Scanning Advice

Once your Grooper web server is stood up, you can scan remotely from any computer able to connect to the web server via an internet browser. However, each scan operator will need to have an additional application, Grooper Desktop, installed on there computer to operate the scanner.

App Pool Identity Permissions

When installing the Grooper web client, you will need to assign an "application pool identity". The Grooper application pool identity is a Windows account running the Grooper web client. This account must be given certain permissions in order to launch Grooper in a web browser and do work in Grooper from that browser.

From a security standpoint, it is best practice to only give a minimum number of permissions to this account.

  • It is unadvisable to give full local admin privileges to the Grooper application pool identity.
  • The minimum number of permissions required are as follows:

Permission

Type

Reason

Required?

Read Member Of

Active Directory

Required for checking user's group membership

  • The user installing the Grooper web client must also have the capability to query the domain in order to enter the credentials for the Grooper app pool identity.

Yes

Users

Local

Run the installed applications (Grooper)

Yes

C:\Release

Local\NTFS

Run MsBuild for compiling Object Libraries in Grooper

Yes

File store access

NTFS\Share

Read and write access to the Grooper file store location

Yes

Database access

SQL

Read and write access to the Grooper database

Yes

Logon As Service

Local Security Policy

Run services installed via Grooper Config

Optional

  • Required if also using the application pool identity as the service account


Installing IIS

Here we will go through the required Internet Information Services (IIS) installation for your host server. For quick reference, we will be installing/enabling the following roles ands features:

  • Web Server
    • Common HTTP Features
      • Default Document
      • Static Content
    • Security
      • Request Filtering
      • Basic Authentication
      • Windows Authentication
    • Application Development
      • .NET Extensibility 4.5 (or above)
      • ASP
      • ASP.NET 4.5 (or above)
      • ISAPI Extensions
      • ISAPI Filters
      • WebSocket Protocol
  • Management Tools
    • IIS Management Console
    • IIS 6 Management Compatibility
      • IIS 6 Metabase Compatibility
    • IIS Management Scripts and Tools
    • Management Service

These components must be installed in order for the Grooper web client to function properly.

To install IIS:

  1. Open Server Manager.

  2. In the top right corner, click on "Manage" to bring up the drop down menu.
  3. Click "Add Roles and Features".

  2. In the window that pops up, feel free to read through the information associated with the installation wizard and then click "Next".

  2. Make sure "Role-based or feature-based installation" is selected.
  3. Click "Next".

  2. Select the desired server from the server pool list.
  3. Click "Next".

  2. Click the check box next to Web Server (IIS) under "Roles" to add the option (When the dialogue box pops up, click the "Add Features" button at the bottom).
  3. Click "Next".

  2. On this screen you don't need any additional features, so just click "Next".

  2. Feel free to read through the description of what a web server is, and click "Next".

  2. We need to make sure that the appropriate role services are installed for Grooper to function. Scroll through the list and select the following components (If a window appears asking you to add features, click the "Add Features" button):
    • Web Server
      • Common HTTP Features
        • Default Document
        • Static Content
      • Security
        • Request Filtering
        • Basic Authentication
        • Windows Authentication
      • Application Development
        • .NET Extensibility 4.5 (or above)
        • ASP
        • ASP.NET 4.5 (or above)
        • ISAPI Extensions
        • ISAPI Filters
        • WebSocket Protocol
    • Management Tools
      • IIS Management Console
      • IIS 6 Management Compatibility
        • IIS 6 Metabase Compatibility
      • IIS Management Scripts and Tools
      • Management Service
  3. Click "Next" after all components are selected.

  2. If desired, click the checkbox next to "Restart the destination server automatically if required".
  3. Click the "Install" button and allow the installation to run.

  2. Once installation is complete, click "Close" to close the wizard.


Installing the Web Client

⚠

If you wish to perform ad hoc processing or multi-threaded process step testing via web client, you will need to install two services in Grooper Config: an Import Watcher and an Activity Processor. Please see installation instructions in the next section.

  1. Open up File Explorer and navigate to your extracted folders.
  2. Open the extracted folder "GrooperWebClient_23.00.xxxx" to reveal the installation files.

  2. Double-click "setup.exe" to start the Grooper Installer.

  2. After reviewing the Welcome page to the InstallShield Wizard, click "Next" to continue.

  2. Read through the End User License Agreement and click the radial button next to "I accept the terms in the license agreement".
  3. Click "Next" to continue.

  2. Enter the user name and password for the account that will logon to use Grooper.
    • Make sure your user name starts with the domain name using the format: "DOMAIN\username"

!!

BE AWARE!!

The user you enter here will be tied to the Grooper App Pool once installation is complete. The Grooper App Pool user is effectively the user executing the Grooper application.

With this in mind, please consider the following:

  • This account must have read and write permissions to both the Grooper database and the Grooper file store locations.
  • This account must be tied to your domain in order to define user permissions when configuring Permission Sets and Review Queues.
  2. Click "Next".

  2. Click the "Install" button to begin installation.

  2. Installation should only take a few minutes. When complete a window should pop up saying that the installation is complete. Click "Finish" to finalize your installation.


Installing Necessary Services

When using the Grooper web client, two Grooper services must be installed and running for certain ad-hoc operations.

  • The Import Watcher service must be installed to perform ad-hoc document imports from the Imports page.
  • The Activity Processing service must be installed to submit multithreaded jobs when using the Unattended Activity tester on a step in a Batch Process.

Here we will show you how to install and start the services needed.


  1. Open Grooper Config and click on "Edit Services".

  2. Once the "Service Manager" window pops up, click "Install..." in the top left corner.

  2. In the "Install New Service" window, select "Import Watcher".
  3. In the top right corner, select the repository needing the service from the drop down list.
  4. Click "OK".

  2. When the "Import Watcher" window pops up, enter the user name and password associated with the server Grooper is installed on.
    • Make sure to include the domain name in your user name following the convention DOMAIN\username.
  3. Click "Execute".

FYI

While setting up the Import Watcher, you can configure the Scheduled Imports, but this is optional. The Import Watcher must be running to perform ad-hoc imports in the web client, with or without Scheduled Imports.

  2. Once back in the "Service Manager" window, click "Install..." in the top left corner again.

  2. In the "Install New Service" window, select "Activity Processing".
  3. In the top right corner, select the repository needing the service from the drop down list.
  4. Click "OK".

  2. When the "Activity Processing" window pops up, enter the user name and password associated with the server Grooper is installed on.
    • Make sure to include the domain name in your user name following the convention DOMAIN\username.
  3. If desired, change the Number of Threads property to reflect the thread count you wish to use for processing.
    • The maximum number of threads should not exceed the total number of processor threads available minus one.  One thread must be reserved to run the operating system.  e.g. If the machine has 20 total threads, the highest value you should enter for Number of Threads should be 19.
      • If the service is running on the same server where IIS is installed, an additional thread should be reserved for IIS.
      • If the service is running on the same server where SQL is installed, an additional thread should be reserved for SQL.
  4. Click "Execute".

  2. When back at the "Service Manager" window, click "Start All" if you wish to start all of your services. You can also choose specifically which services to start by selecting each one individually and clicking "Start".

  2. When activated, the dot to the left of the service will turn from red to green.

Additional info: The web client and secure website connections

Generally speaking, you should always connect to a website with a secure connection. Browsers will not allow you to do certain things when accessing an insecure website. Most notably browsers won't allow you to paste from a clipboard to Grooper from an insecure connection.

There are two ways to ensure you're connecting to a Grooper website using a secure connection:

  1. Enable HTTPS (also known as SSL or Secure Socket Layers) by binding an SSL certificate to the Default website.
    • This is the highly preferred, best practice method.
    • Even if using a "self-signed certificate" to enable HTTPS, this method is preferred.
    • This will allow users to connect to Grooper websites using the secure HTTPS protocol.
  2. Instruct your web browser to treat the Grooper website as secure.
    • This is not preferred but may be necessary depending on your browser preference and how your organization manages your browsers.
    • This will allow users to connect to Grooper websites using the insecure HTTP protocol but treat the connection as secure, allowing access to the clipboard to copy and paste into Grooper.
    • Be aware each user will have to configure their own browser to connect to Grooper in this way. This is one of the reasons why this is less preferable to enabling SSL on your web server.
How to create and bind a self-signed certificate

Enabling HTTPS (also known as SSL or Secure Socket Layers) on your Grooper web server will allow you to connect to the Grooper web client's URL using the secure HTTPS protocol and not the insecure HTTP protocol.

  • Even for internal use, you should at least use a "self-signed SSL certificate" to do so.
  • Enabling SSL on your web server will allow you to do so. We are not exposing the Grooper website publicly, but should still connect via HTTPS, if possible.
  • Browsers will not allow you to do certain things when accessing an insecure website.
    • Most notably, you will not be able to paste from a clipboard to Grooper using an insecure connection (i.e. HTTP)

Here, we will cover the most basic steps to create a self-signed SSL certificate and bind it to the Grooper Web Client's website.


First, open the Information Internet Services (IIS) Manager application on your web server.

  1. Select your server in the left-hand Connections panel.
  2. Click "Server Certificates".


  2. In the right-hand Actions panel, click "Create Self-Signed Certificate..."


  2. Enter a name for the certificate.
  3. Click "OK".


  2. Expand the server connection and select the "Grooper" site.
  3. Click "Bindings..."


  2. Click "Add..."


  2. Under "Type" select "https" from the drop down list.
  3. Under "Host name" enter the host address (if applicable).
  4. Under "SSL certificate", select the self signed certificate you created earlier.
  5. Click "OK" when finished.


  2. You should now see the binding for port 443.
  3. Click "Close".


How to treat a website as secure

Certain browser configurations will not allow users to connect to a website bound with self-signed certificate. When trying to connect using HTTPS, you may encounter an error like the one to the right.

  • Note, this is only an issue with self-signed certificates. SSL Certificates obtained from a Certificate Authority will not have this issue.

This can be problematic for users whose browsers are managed by their organization and have restricted them from doing so. In these extreme circumstances, you can instruct the browser to treat the website as if it were secure, even though it is not.

  • Google Chrome version 119.0.6045.160 is known to have this issue
  • Microsoft Edge version Version 121.0.2277.83 is known to have this issue.

  1. Navigate to the following depending on your web browser:
    • chrome://flags for Google Chrome
    • edge://flags for Microsoft Edge
  2. Search for "Insecure origins treated as secure" and change it to "Enabled"
  3. Enter your Grooper web client's host URL (i.e. http://hostname)
  4. Relaunch the browser.
  5. Connect to the Grooper website using HTTP.

With the flag added, the Grooper web client will behave as if you're connecting with HTTPS even though you're connecting with HTTP.


BE AWARE! THIS IS CONSIDERED A WORKAROUND! This is not the preferred method to connect to Grooper using a "secure" connection. It is forcing the browser to act as if the connection is secure, even though it is NOT.

  • Please use an SSL Certificate from a Certificate Authority if possible.
  • If you must use a self-signed certificate, even using an alternative browser that DOES allow users to connect to websites bound with a self-signed certificate is preferable to this method.

Installing Grooper Desktop for Scanning in the Web Client

Grooper Desktop is a lightweight application required to scan documents from a remote computer using the Grooper web client.

  • Grooper Desktop can be installed on any desktop computer connected to a document scanner.
  • Once installed, users can use the Review activity's "Scan Viewer" to scan documents using the web client.
    • Grooper Desktop "listens" for users operating the scanner from the Scan Viewer and will send all images coming from the scanner to the Grooper Repository via the web server.
  • The Grooper thick client does not have to be installed on the computer for Grooper Desktop to operate.

Installing Grooper Desktop

⚠

In some cases, antivirus software will interfere with Grooper's installation, preventing a complete install.

  • You may need to whitelist the Grooper installers/software before installing.
    • This will ensure the antivirus software is not preventing DLL files from installing or executing.


Most commonly, this issue has been demonstrated when installing the Grooper Desktop application (required to scan using the web client).

  • If Grooper Desktop is installed correctly, and you are able to scan using the scanner's native software, you may need to (1) uninstall Grooper Desktop, (2) whitelist the Grooper Desktop installer and GrooperDesktop.exe application and (3) reinstall Grooper Desktop to ensure you can scan from the Grooper web client.
  1. Open up File Explorer and navigate to your extracted folders.
  2. Open the extracted folder "GrooperDesktop_23.00.xxxx" to reveal the installation files.

  2. Double-click "setup.exe" to start the Grooper Installer.

  2. After reviewing the Welcome page to the InstallShield Wizard, click "Next" to continue.

  2. Read through the End User License Agreement and click the radial button next to "I accept the terms in the license agreement".
  3. Click "Next" to continue.

  2. Now you can choose the location where you want the Grooper Application to be installed. It is recommended to use the default file path.

FYI

Notice that this application is being installed in Program Files (x86). We are installing a 32-bit application because it interfaces with scanners.

  2. Click "Next".

  2. Click the "Install" button to begin installation.

  2. Installation should only take a few minutes. When finished, a window should pop up saying that the installation is complete. Click "Finish" to finalize your installation.

There is one more thing we need to do to finish the installation of Grooper Desktop. We need to reserve a URL for Grooper Desktop to use. See the next section for instructions on how to do this.

Reserve URL for Grooper Desktop

The first time you run Grooper Desktop, you might notice a notification pop up above your system tray that says Grooper Desktop is "Not Configured".

This is because you need to reserve the URL as the listening location that the service will use to pull from the scanner. We will run a short command line code to reserve this URL.

  1. right click on the Grooper "G" logo in your system tray and click on "Configure..."

  2. When the window pops up, Web Scanning is set to "Disabled".
  3. Click the drop-down arrow and select "Enabled".

  2. Click the down arrow to the left of "Web Scanning" to expand properties.
  3. Down at the bottom, you will see a property called "URL Reservation". It is populated with a netsh command. Select the contents of this property and copy it to your clipboard.

  2. Open a Command Prompt (as an administrator) in Windows and paste the previously copied netsh command. Hit Enter.
  3. The command prompt should return with "URL reservation successfully added".

Now you should be finished with the installation of Grooper Desktop!

Connecting to a Grooper Repository

A Grooper Repository is the environment used to create, configure and execute objects in Grooper. It provides the framework to "do work" in Grooper.

This environment consists of two things:

  1. A database connection
  2. A file store connection

The database stores Grooper nodes and their property settings (such as a Content Model or a Data Type or any other Grooper object). The file store location houses content associated with these nodes (such as the image file for a Batch Page object). Grooper is the application layer that sits on top of this two parts of the environment. It allows readable and writable access and the UI to create, configure, test, and process the information stored there.

Connecting to a Grooper Repository is one of the first things you will do after installing Grooper to start designing (or implementing already architected) document processing solutions. This is done with the Grooper Config application.

⚠

Grooper Config must be run as an administrator. It performs functions that require elevated access in Windows.

Prerequisites

Install SQL Express (Optional)

⚠

This step is only applicable to stand-alone Grooper installations on a local machine. If you are using the full version of Microsoft SQL Server and it is already installed and running, you can skip this step and continue to the next section. Grooper is not designed to run at an enterprise level for your business on SQL Express, but it can be useful for testing/experimentation purposes.

Remember, a Grooper Repository is two things:

  1. A database connection
  2. A file store connection

For Grooper Repositories, nodes and their property values are stored in tables in a SQL database. Node objects created in Grooper Design Studio are stored as rows in a table, with their property values in the row's columns. This can be anything from a Batch of documents, to a Batch Process used to process that Batch, to a Content Model referenced by the Batch Process to classify the documents in the Batch or any object used to execute document processing in Grooper.

If you do not have a SQL environment already available, you can download and install Microsoft SQL Express directly from Grooper Config.

  1. Click the "Download SQL Express..." button.

  2. The installer files will download automatically. You will see this dialog box appear upon successful download.
  3. Click "Ok" to continue.

Next, you can install SQL Express directly from Grooper Config.

  2. Click the "Install SQL Express..." button.
  3. The following confirmation box will appear.
  4. Click "Yes" to continue installing SQL Express.

  2. Grooper will then prompt you for a folder location to save the installed files.
    • This defaults to a folder in the "Grooper" folder of the "BIS" folder created during installation.
  3. Click "Ok" to continue.

You will then be prompted through the SQL Express installation process.

  2. Upon successful installation, the following dialog box will appear.
  3. You can elect to either keep the installer executable file or delete it. You don't need it anymore. You may as well delete it. Click "Yes" to delete the file.

Initialize Grooper Config (one-time only)

  1. If this is your first time opening Grooper Config after installation, you will need to initialize the System Configuration. You will see the following dialog box appear.
  2. Click "Yes" to initialize.

Upon initializing the system for the first time, you will see this screen. This is a totally unconfigured Grooper Config! From here, we can create new Grooper Repositories and connect to existing Grooper Repositories accessible on your network.

If starting totally from scratch, you will need to create at least one Grooper Repository.

Establish the File Store Location

Remember, a Grooper Repository is two things:

  1. A database connection
  2. A file store connection

The file store simply needs to be a Windows folder the appropriate Grooper users have readable and writable access to.

  • For web client installs, only the Grooper App Pool user account needs access to the file store.
  • For thick client installs, all users doing work in Grooper will need file store access. This includes Grooper designers and admins doing work in Grooper Config and Grooper Design Studio as well as end-level users doing document review via Grooper Dashboard and Grooper Attended Client.


Do not use drive letters (e.g. "C:") when copying out our file store's path. Drive letters can cause problems. Mapped and local drive references may not be accessible to other users or machines. Instead, always use a fully qualified UNC path when copying the folder's path.

UNC (Universal Naming Convention) is a naming standard used in Microsoft Windows for accessing shared network folders. These names consist of a host machine name, a share name, and an optional file path. UNC paths must be "fully qualified", meaning the entire path location must be typed out, starting with the top most directory in the hierarchy (such as the server's name). This disambiguates file and folder locations on one networked machine from another.

The UNC naming convention for Windows paths is as follows: \\hostname\file_path\file_path

FYI

UNC paths can be established using the "Sharing" properties of a folder.

  1. Right-click the folder
  2. Select "Properties".
  3. In the following window, click the "Sharing" tab.
  4. If the folder is already shared, you will see the UNC path under "Network Path"
  5. If you have not shared the folder, you can do so by pressing the "Share..." button.
    • From there you can list users or user groups who should have networked access to the folder.

Creating a New Grooper Repository

Now that Grooper is initialized, we have a file store location, and we have an available SQL environment (either a full install of SQL Server or SQL Express) we can create a new Grooper Repository.

Connecting to a Grooper Repository is the first thing you will do in Grooper Config. If you're not connecting to an existing Grooper Repository set up on someone else's Grooper installation, you'll need to create one.

⚠

If you are using the Web Client, you will need to recycle the Grooper app pool in IIS to access any new repository you create or when connecting to a previously configured repository.


  1. Select the Repositories property in Grooper Config.
  2. Click the ellipsis button at the end.

This will open up a new window to add Grooper Repository connections.

  2. Click the "Add" button to add a new connection.

The first part of creating a new Grooper Repository is establishing the database connection.

  2. Select the Server Name property and enter the server's name running the SQL environment.
    • FYI: For SQL Express installs, the server instance will be the machine's name followed by \GROOPER as seen here.
    • For standard SQL Server installs, simply enter the server machine's name.
  3. Select the Database Name property and enter a name for the database.
    • Here, we chose to name it okcstrpa01_001 after the server name. Name the database whatever you would like.
  4. Click the "Test Connection" button.

  2. Since we are creating a new Grooper Repository, the database has not been created yet. A dialog box will appear informing you the database does not exist and asking you if you want to create it.
  3. Click "Yes" to create the database.

FYI

By default, Grooper will use your Windows login authentication to access the SQL environment. However, if you need to access the SQL environment with different rights (for example a SQL admin login), you can do so using the Authentication properties.

  2. Upon creating the database, you will get a message letting you know the database has not been initialized.
  3. Click "Ok" to continue.

  2. Click the "Initialize" button.

Remember, a Grooper Repository is two things:

  1. A database connection
  2. A file store connection

Initializing the Grooper Repository connects the repository to the file store location and establishes the folder structure Grooper uses to store files.

  2. Select the Storage Path property and enter the file path for the file store's folder.
  3. Click the "Execute" button to initialize the Grooper Repository.

⚠

While you can use the ellipsis button to navigate to a local file store location, it is ill-advised. Please use a fully qualified UNC path for your Grooper files store location.

FYI

You may also name the Grooper Repository using the Repository Name property. We named ours okcstrpa01_001.

But don't worry if you don't name it at this time. You may rename your Grooper Repository at any time after it is initialized. Once initialized, you can select the Grooper Repository from the Repositories list and click the "Rename" button to rename it.

  2. Upon successful initialization, you will receive this confirmation window.
  3. Click the "Ok" button to continue.
  4. Click the "Ok" button to finish.

This will return you to the main Grooper Config window.

  2. Click the "Save" button to finalize your Grooper Repository connection.

Connecting to an Existing Grooper Repository

Add the Repository Connection

Connecting to an existing Grooper Repository is similar to creating a new one. It is essentially the same process with fewer steps. For this tutorial, we will connect to a repository that is hosted on another machine.

FYI

When connecting to a networked Grooper Repository, you do not need to have SQL installed on the machine accessing the repository. As long as the machine has networked access to the SQL server where the Grooper Repository's database is created and networked access to the Grooper Repository's file store location, it can connect to the repository.

⚠

If you are using the Web Client, you will need to recycle the Grooper app pool in IIS to access any new repository you create or when connecting to a previously configured repository.


The first steps of connecting to an existing Grooper Repository are the same as creating a new one.

  1. Select the Repositories property.
  2. Click the ellipsis button at the end of the property to bring up the Grooper Repositories connection editor.

  2. In the new window that pops up, click the "Add" button to add a new connection.

Configure the Connection

  1. Select the Server Name property and enter the server's name running the SQL environment.
  2. Select the Database Name property and enter the Grooper Repository's database name.
  3. Click the "Test Connection" button.

FYI

The repository we are connecting to has already been created and initialized on another machine. As long as we have networked access to the SQL environment and file store, we should be able to just connect to it.

  2. A dialog box appears letting you know the connection is successful.
  3. Click "Ok" to continue.

FYI

By default, Grooper will use your Windows login authentication to access the SQL server and database. However, if you need to access the SQL environment with different rights (for example a SQL admin login), you can do so using the Authentication properties.

  2. You will see the "Status" listed as Ok indicating you have successfully connected to the Grooper Repository.
  3. Click the "OK" button to continue.

This will return you to the main Grooper Config window.

  2. Click the "Save" button to finalize your Grooper Repository connection.

License Activation

Now that you have your repositories initialized and connected, you need to activate your Grooper license. When you purchased Grooper, you should have received a license key GUID, something like "1a2b3c4d-5e6f-7g8h-9i10-j11k12l13m14". You will need this GUID to license your Grooper installation.


There are three ways to license Grooper:

  • cloud hosted
  • stand-alone
  • self hosted


Cloud hosted licensing is the easiest but least secure method of licensing.

  • It is easiest because a Grooper Repository is licensed simply by entering the license key/GUID into a property at the root node in Grooper Design. Licensing is decremented over the internet. This has some pros and cons.
    • Pro: No additional setup is required to license Grooper. Just enter the license serial number into the root node of the Grooper Repository.
    • Pro: The license is not bound to any individual server or machine. This makes it easy to distribute licensing to multiple Grooper Repositories across multiple machines.
    • Con: The license is not bound to any individual server or machine. This means any user with the license key/GUID and an internet connection can use the license.
      • ALWAYS keep your license key/GUID secure and DO NOT share it with anyone that you do not wish to have access.
  • Also, be aware licensing is authorized by a licensing server internal to BIS. If that server goes down, you may temporarily loose licensing.
    • This is an exceptionally rare occurrence and our disaster recovery plan will switch to an alternate licensing server. However, that switchover could take between one and two hours, in which time Grooper would not be licensed.


The "stand-alone" and "self hosted" methods require additional setup using Grooper Config but are more secure.

  • These installations are more secure because the license is locked to an individual machine when the license key is activated.
    • If a user attempts to use the license GUID to license another Grooper installation, licensing will fail.
    • For "self hosted" installations, licensing is distributed to client workstations via a URL provided by the Grooper Licensing service not the license GUID.


In this article, we will show you how to perform "cloud hosted" licensing.

  • Remember, cloud hosted licensing is the easiest, but elast secure method of licensing.
  • For more information on other licensing setups, visit the 2023:License Activation article.

How to Activate Your License Using the "Cloud Hosted" Method

To license your Grooper repository using "cloud hosted" licensing, perform the following steps:

  1. Open the Grooper Web Client in a web browser. At the top you will see that the software is currently "UNLICENSED".
  2. Click the "Design" icon.

  2. With the repository selected in the root node, make sure the "Root" tab is selected.
  3. Click to the right of the License Serial# or URL property and paste your activation key.
  4. Click the "Save" button.

!!

IMPORTANT: KEEP YOUR LICENSE KEY SECURE

When licensing Grooper this way, the license serial number is not bound to any one machine. Your license key/GUID can be used by any user with an internet connection. This has pros and cons.

  • Pro: Multiple Grooper Repositories on multiple machines can be licensed quickly without the additional setup in Grooper.
  • Con: Anyone can license their Grooper Repository using the license key, even if they are on a separate domain.

When using the cloud hosted licensing method, ALWAYS keep your license key/GUID secure and DO NOT share it with anyone that you do not wish to have access.

  2. Close and re-open Grooper Design Studio. At the top the "LICENSEE" should now reflect your current license. You may begin using Grooper!


Upgrading an Older Version of Grooper

!!

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 four steps:

  1. Stop any Grooper services.
  2. Uninstall the older version of Grooper.
  3. Install the newer version of Grooper.
  4. Upgrade Grooper Repositories from the older version to the newer.

⚠

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:

Before You Begin: 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:

How to Validate a 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 with its Local Extractor set to Pattern Match but with no pattern set is an issue. If this is left unconfigured, validation will catch the configuration error.

  1. You can see that we do not have this Pattern Match fully configured.
  2. On this Data Type we see we have an error.

  1. If we right-click on the Project object...
  2. ... and click on "Validate Branch"...
  3. ... a window will pop up showing us the validation error. We will need to correct this before upgrading.

!!

It is recommended that you validate your ENTIRE repository before upgrading to a new version of Grooper. However, validation CANNOT be performed at the Root Node in the web client. You MUST open the thick client in order to fully validate your repository.

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.

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

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

  1. Open Grooper Config and click "Edit Services".

  2. If you have any services running they will be listed with a green dot to the left side.
  3. You can select each individual service and click "stop" or you can just click "Stop All".

  2. Once a service is stopped, the dot to the left of the service name should turn red.

⚠

Very rarely, a Grooper service will not uninstall properly when you uninstall a Grooper service service. Or, a user may delete a Grooper Repository connection or purge a Grooper Repository without uninstalling services first.

This can make it appear as though a duplicate or "ghost" Windows service is installed without being listed in GCC (or Grooper Config before version 2024).


If this does occur, you will need to manually delete the service. If you know the name of the service instance (something like Grooper.ServiceTypeName.##) you need to delete, you can use the following command lines to stop the service (if necessary) and manually delete it. 

SC STOP Grooper.ServiceTypeName.##
SC DELETE Grooper.ServiceTypeName.##

OR

You can delete the service from the Windows Registry Editor, using the following steps:

  1. Open the Registry Editor (regedit.exe)
  2. Navigate to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services.
  3. Select the key of the service you want to delete.
    • Grooper services will always be named something like Grooper.ServiceTypeName.##
  4. From the "Edit" menu select "Delete.
  5. You will be prompted "Are you sure you want to delete this Key?". Click Yes.
  6. Exit the Registry Editor.

Step 2: 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.

⚠

REMINDER!! BACK UP YOUR GROOPER REPOSITORY BEFORE UNINSTALLING!

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.


  1. Open your Windows Settings and click on "Apps".

  2. Scroll down through your list of apps until you find the Grooper application. Click on the app.
  3. When it expands, click on "Uninstall".

  2. A small window may pop up to confirm you wish to uninstall the app. Click "Uninstall".

  2. Wait for the application to be uninstalled.

Step 3: 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:

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.
    • It is also considered 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.

Step 4: 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.


  1. Select the Repositories property.
  2. 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.

  2. To upgrade a Grooper Repository, select the repository that needs upgrading.
  3. Click the "Upgrade..." button in the upper toolbar.

  2. An "Upgrade" window will appear. Click the "Execute" button to confirm the upgrade.

  2. You will be prompted to execute a Version Upgrader. Click "Execute" to start the upgrader.

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

  2. After the upgrade is complete, click the "Test Connection.." button to ensure you're now property connected to the upgraded database.
  3. If successful, a message box will pop up confirming your connection. Click Ok.

  2. You will see the upgraded Grooper Repository's Status change from "NeedsUpgrade" to "Ok".
  3. Click the "Ok" button to exit the Repositories window.

  2. Click the "Save" button in the main screen of Grooper Config to complete the upgrade.

Congratulations! You've upgraded Grooper.

⚠

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.
Retrieved from "https://wiki.grooper.com/index.php?title=2023:Install_and_Setup&oldid=25727"