Install and Setup

This article is about the current version of Grooper. Note that some content may still need to be updated.
2025	2024	2023	2022	2021	2.90

Welcome to Grooper 2025!

This guide will instruct you how to get up and running in Grooper.  There are five parts (six if you are scanning documents into Grooper) to installing and setting up Grooper:

1. Installing Grooper
2. Setting up and Installing Grooper Web Client
3. 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.
4. License activation
5. Installing necessary Grooper services - As a practical matter, most Grooper installs will need at least two Grooper services installed: An Activity Processing and an Import Watcher service.
6. Installing Grooper Desktop - This is only required if you are scanning paper documents into Grooper using a scanner attached to a computer. If you are not scanning documents, you may ignore this.

PLEASE NOTE: At the end of this article, you will also find guidance for upgrading an older version of Grooper to the current version. 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 for more information.

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

• Grooper: The primary Grooper installer installs the application files required to run the software and Grooper Command Console (or GCC). Grooper Command Console is an administrative application required to fully configure Grooper installs.
• Microsoft SQL Server: This is a database server software developed by Microsoft for Windows. SQL Server is required to create Grooper Repositories. Microsoft SQL Server 2016 or higher is recommended. For most installs, a dedicated machine for SQL server is recommended. Only the smallest installs and testing installs may host SQL server and IIS on the same machine.
• Internet Information Services (IIS): This is web server developed by Microsoft for Windows. It is necessary to host the Grooper web client.
• Grooper Web Client: The Grooper Web Client installer installs the Grooper Web Client. This is Grooper's interface layer accessible from a web browser.
• A supported web browser: Grooper can be used in one of the following supported browsers:
  • Microsoft Edge
  • Google Chrome
  • Apple Safari
  • Microsoft Internet Explorer is not supported. Other modern browsers (such as Mozilla Firefox and Opera Web Browser) may work but have not been fully tested.
• Grooper Desktop: This is a lightweight desktop application required to scan paper documents into Grooper. It must be installed on any desktop computer connected to an optical scanner.
• Grooper services: While not strictly required to perform basic testing in Grooper. As a practical matter, at least two Grooper services are required for most installs, an Activity Processing and Import Watcher service. See here for more information.

⚠

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. If Grooper Desktop is installed correctly, and you are able to scan using the scanner's native software (but not with Grooper), 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 Grooper 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 install.

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

Click here for an interactive walkthrough.

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

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

2. Log into Grooper xChange at http://xchange.grooper.com.
3. Go to the the "Downloads and Resources" section.
4. The current support versions of Grooper are listed at the top. Click the link for the version you wish to install.
5. On the installers page you will see three links to downloads:
   • The Grooper installer
     • Users setting up a web server to install the Grooper website will need this installer.
     • Users installing Grooper on a processing server running Activity Processing services will need this installer.
   • The Grooper Web Client installer
     • Users setting up a web server to install the Grooper website will need this installer.
   • The Grooper Desktop Installer.
     • Users scanning documents with a digital scanner will need this installer. The Grooper Desktop installer will need to be installed on workstations used for scanning.
6. The installer files will download as ZIP files. You will need to extract each zipped folder. Right-click each ZIP and select "Extract All..."
7. After unzipping the installer ZIP(s), you ready to install the software.

Continue to the next section for installation instructions.

Installing Grooper

The Grooper installer creates the program files for the Grooper application. Grooper must be installed on Grooper web servers hosting the Grooper website and Grooper processing servers where Activity Processing services are installed.

• For Grooper web servers: Both Grooper and the Grooper Web Client application must be installed.
  • It is considered best practice to install Grooper before installing the Grooper Web Client.
• For Grooper processing servers: Only Grooper needs to be installed.

How to install Grooper

Click here for an interactive walkthrough.

1. After extracting the installer ZIP package, open the extracted folder "GrooperInstall_25.00.xxxx_x64" to reveal the installation files.
2. Open the "setup.exe" file to start the Grooper Installer.
3. When the install wizard pops up, select "Next" to start installing Grooper.
4. Select "Install" to start installing prereqs, if prompted.
   • If this is your first time installing Grooper, you may be prompted to install various perquisite applications.
   • BE AWARE: Certain perquisite installs may require a restart. When prompted, please restart. After restarting, you will need to complete steps 1 through 4 again to continue your installation.
5. Once prerequisite components are installed, the Grooper installer will pop up. Click "Next" to move to the next screen.
6. Read through the End User License Agreement and click the button next to "I accept the terms in the license agreement".
7. Select "Next" to continue.
8. You may choose the location where you want Grooper to be installed. It is recommended to use the default file path, but based on your business needs, you may choose a different location.
9. Select "Next" to continue.
10. Select the button next to your preferred setup type. The vast majority of users will select "Complete" to perform a complete setup.
11. Click "Next".
12. You are now ready to install the program. Click "Install" to begin installation.
    • Installation should only take a few minutes.
13. Press the "Finish" button when prompted to finalize the installation.

Setting up and installing Grooper Web Client

The Grooper Web Client installs the Grooper website on a web server. The Grooper website is the Grooper user interface. It is how users interact with the platform, using a browser-based UI. Before you can open up an internet browser and start using Grooper, you need to stand up a "Grooper web server".

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

1. The Grooper application
   • It is best practice to install Grooper before installing the Grooper Web Client application.
   • If you have not installed Grooper yet and need instructions, refer to the section above.
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 their computer in order to operate the scanner. More information on Grooper Desktop and scanning documents into Grooper can be found in the Scan Viewer article.

Setup: Installing Internet Information Services (IIS)

Before you can install the Grooper Web Client application, you need to install Internet Information Services (IIS) on the host server. IIS is an extensible web server developed by Microsoft for hosting web content and applications (like Grooper). It is not active by default on Windows servers and must be installed before installing a Grooper website.

How to install IIS

Click here for an interactive walkthrough.

To install Internet Information Services (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".
4. In the window that pops up, feel free to read through the information associated with the installation wizard and then click "Next".
5. Make sure "Role-based or feature-based installation" is selected.
6. Click "Next".
7. Select the desired server from the server pool list.
8. Click "Next".
9. 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).
10. Click "Next".
11. On this screen you don't need any additional features, so just click "Next".
12. Feel free to read through the description of what a web server is, and click "Next".
13. Add the role services listed below. Click the box next to each feature (if not already checked).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):
    • These components must be installed in order for the Grooper website to function properly.
    • 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
14. Click "Next" after all components are selected.
15. If desired, click the checkbox next to "Restart the destination server automatically if required".
16. Click the "Install" button and allow the installation to run.
17. Once installation is complete, click "Close" to close the wizard.

Setup: 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 Grooper using the web client. This account must be given certain permissions in order to launch the Grooper website in a web browser and run 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 Command Console	Optional Required if also using the application pool identity as the service account running Grooper services

Installing Grooper Web Client

With IIS installed and configured and the app pool's user permissions defined, you can now install the Grooper Web Client application.

Click here for an interactive walkthrough

1. After extracting the installer ZIP package, open the extracted folder "GrooperWebClient_25.00.xxxx" to reveal the installation files.
2. Open the "setup.exe" file to start the Grooper Installer.
3. When the installer opens, click "Next" to continue.
4. Read through the End User License Agreement and click the radial button next to "I accept the terms in the license agreement".
5. Click "Next" to continue.
6. Enter the user name and password for the "Grooper App Pool" user account.
   • Make sure your user name starts with the domain name using the format: "DOMAIN\username"
   • You can also use the "Browse..." button to search a domain or server for an account.
   • BE AWARE: The user you enter here will be the Grooper App Pool user. 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 (MSSQL Server) 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 in Grooper.
7. Click "Next".
8. Click the "Install" button to begin installation.

SSL and HTTPS: 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. You will need to enable 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.

• Most notably, browsers won't allow you to paste text copied to your clipboard to properties in Grooper from an insecure connection.

To connect to a website with a secure connection (HTTPS), you have the following options:

1. Obtain an SLL certificate from a Certificate Authority (CA) and bind the certificate to the default website on your web server.
   • Your organization can create a Certificate Signing Request (CSR) on your server. This creates a public and private key.
   • You then send the CSR data file to a CA. The CSR file has the public key.
   • At the time of writing this article, according to Wikipedia, the most common CA providers (by usage share) are:
     • Let's Encrypt
     • GlobalSign
     • Sectigo
     • GoDaddy
     • DigiCert
2. Create a self-signed SSL certificate.
   • This is an easy way for most users. We will instruct you how to do this method.
   • After binding the self-signed cert, users will be warned before continuing to the Grooper website. You have two options:
     • You can instruct your users to ignore this warning.
     • Or you can add the certificate to the browsers "trusted root certification authorities" to initiate trust between the browser and the Grooper web server.
       • We will instruct you how to do this.
       • You will need to do this for every browser opening the Grooper website.
3. Stand up your own Certificate Authority to issue certs on your local network.
   • OpenSSL is a common tool people use to do this.

We will instruct you how to do option 2. Keep reading to learn how to create a self-signed certificate and set up your browser to trust the certificate.

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 allowing it to connect via HTTPS.
• 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.

Option 1: Create a self-signed cert in IIS

Click here for an interactive walkthrough.

1. Open the "Information Internet Services (IIS) Manager" application on your web server.
2. Select your server in the left-hand "Connections" panel.
3. Double-click "Server Certificates".
4. In the right-hand "Actions" panel, select "Create Self-Signed Certificate..."
5. In the dialog box that appears, enter a name for the certificate.
6. Click "OK".
7. In the left-hand "Connections" panel, expand the server connection and "Sites" folder and select the "Default Web Site".
8. In the right-hand "Actions" panel, select "Bindings..."
9. In the window that appears, select "Add..."
10. In the next window, under "Type" select "https" from the drop down list.
11. Under "Host name" enter the host address (if applicable).
12. Under "SSL certificate", select the self signed certificate you created earlier.
13. Click "OK" when finished.
14. In the previous window, you should now see the binding for port 443.
15. Click "Close".

Option 2: Create a self-signed cert from PowerShell

Some organizations have reported issues with how IIS creates a self-signed cert. If you attempt to open the Grooper website and run into an error message that says "ERR_SSL_KEY_USAGE_INCOMPATIBLE", this method should resolve your issue.

Click here for an interactive walkthrough.

1. Open Windows PowerShell on your web server.
2. Enter the following:

   • New-SelfSignedCertificate -FriendlyName YourCertName -DnsName YourServerName -KeyUsage DigitalSignature -NotAfter (Get-Date).AddYears(20)

   • Replace YourCertName with whatever you want to name the certificate.
   • Replace YourServerName with your web server's name.
   • You can adjust the value in AddYears() to whatever you'd like. This adjusts the expiration date of the self-signed cert.
3. This self-signed cert can now be selected in IIS. Open "Information Internet Services (IIS) Manager" on your web server.
4. In the left-hand "Connections" panel, expand the server connection and "Sites" folder and select the "Default Web Site".
5. In the right-hand "Actions" panel, select "Bindings..."
6. In the window that appears, select "Add..."
7. In the next window, under "Type" select "https" from the drop down list.
8. Under "Host name" enter the host address (if applicable).
9. Under "SSL certificate", select the self signed created from PowerShell.
10. Click "OK" when finished.
11. In the previous window, you should now see the binding for port 443.
12. Click "Close".

How to add the cert to a browsers trusted root certification authority store (from Chrome)

With the self-signed cert created and bound, you will be able to navigate to the Grooper website (https://yourServerName/Grooper). However, your browser will warn you the connection is not secure. You now have two options:

• Instruct your users to ignore the warning and proceed to the website.
• OR, create a trust relationship between the browser and web server.

To create this trust, you will need to add the self-signed cert to the browser's trusted root certification authority store.

Click here for an interactive walkthrough.

1. Navigate to your Grooper website.
2. Click the "Not secure" button in the URL bar to view site information.
3. Select "Certificate details".
4. Go to the "Details" tab.
5. Click "Export..."
6. Download the certificate.
7. Next, find the "Manage certificates" setting in your browser. Go to your browser's "Settings"
8. Go to "Privacy and security" in the left navigation bar.
9. Select "Security"
10. Select "Manage certificates".
11. Select "Manage imported certificates from Windows"
12. This brings up the "Certificates" editor. Go to the "Trusted Root Certification Authorities" tab.
13. Select "Import..."
14. This brings up the Certificate Import Wizard. Click "Next."
15. Use the "Browse..." button to find the certificate you downloaded earlier.
16. Click "Next"
17. Ensure the selected certificate store is "Trusted Root Certification Authorities" and select "Next."
18. Click "Finish".
19. Your browser will most likely give you a security warning. Click "Yes" to install the certificate.
20. Exit your browser and re-open it.
21. Navigate to your Grooper website. Your connection is now secure and trusted. The browser will no longer warn you about proceeding to the website.

HTTP WORKAROUND: How to treat a website as secure READ WITH CAUTION!

BE AWARE! THIS IS CONSIDERED A WORKAROUND!

This is appropriate ONLY for testing environments. 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 or a self-signed certificate when possible.

Chromium based browsers can treat HTTP URLs as secure by enabling the "Insecure origins treated as secure" flag.

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.

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 Batch or a Content Model or any other Grooper object). The file store location houses any file content associated with these nodes (such as the image file for a Batch Page node). Grooper is the application layer that sits on top of this two parts of the environment, and the Grooper web client is the interface later that sits on top of that. All this together allows users access to create, configure, test, and process the information stored in the Grooper Repository's database and file store.

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 Command Console application.

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

Prerequisites

Before creating a Grooper Repository, you will need two things:

1. A Microsoft SQL Server instance for the Grooper database
2. A Windows folder location for the Grooper file store

MS SQL Server

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 the Grooper Design page 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 node used to execute document processing in Grooper.

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

Full MS 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.

Windows folder 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 Grooper App Pool user has readable and writable access to.

However, 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. Right-click the folder Select "Properties". In the following window, click the "Sharing" tab. If the folder is already shared, you will see the UNC path under "Network Path" 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

Click here for an interactive walkthrough!

Connecting to a Grooper Repository is the first thing you will do after a fresh Grooper install. If you're not connecting to an existing Grooper Repository, you'll need to create one.

• Creating a Grooper Repository is done using the Grooper Command Console (GCC) application with the following three commands:

  1. databases create <serverName> <databseName> [user] [password]

  2. connections add <serverName> <databaseName> [user] [password]

  3. connections init <connectionNo> <repositoryName> <storagePath>

• Full instructions for creating a Grooper Repository can be found in the GCC article.

Connecting to an existing Grooper Repository

Click here for an interactive walkthrough!

Connecting to a Grooper Repository is the first thing you will do after a fresh Grooper install. Connecting to an existing Grooper Repository is simpler than creating a new one.

• Creating a Grooper Repository is done using the Grooper Command Console (GCC) application using the following command:

  connections add <server> <database> [user] [password]

• Full instructions for creating a Grooper Repository can be found in the GCC article.

License activation

Now that you have your Grooper Repository initialized, you need to license the Grooper Repository. When you purchased Grooper, you should have received a license serial number (or "key"), something like "1a2b3c4d-5e6f-7g8h-9i10-j11k12l13m14". You will need this key to license your Grooper installation.

There are two ways to activate a license:

1. Using the "cloud hosted" method
2. Using the "self hosted" method.

The "cloud hosted" method is the quickest and easiest way to license a Grooper Repository. All it requires is an internet connection and your license key. Licensing is decremented using a web service.

The "self hosted" method is more involved. For this method, users install their own licensing service on their local network. This licensing service distributes licensing to each Grooper Repository.

For more information on both methods, visit the License Activation article.

How to activate your license using the "cloud hosted" method

The most common and easiest method to license Grooper is the "cloud hosted" method.

To license a Grooper Repository using the "cloud hosted" method:

Click here for an interactive walkthrough!

1. Have your Grooper license serial number ready. This is a GUID that looks something like "1a2b3c4d-5e6f-7g8h-9i10-j11k12l13m14"
2. Open Grooper in a web browser and go to the Design page.
3. Select the Grooper Root node of the Grooper Repository.
4. In the "Root" tab, select the "License Serial# or URL" property and enter your license serial number.
5. Press the "Save" button.
6. The Grooper Repository is now licensed! Refresh the page and the top negation bar will show your license name next to "LICENCEE."
   • If licensing more than one Grooper Repository you can license each one by using the "Repository" button to select each Grooper Repository. This button is found in the upper right corner of the top navigation bar.

!!

IMPORTANT: KEEP YOUR LICENSE KEY SECURE Using the cloud hosted method, the license is activated over the internet using a web service. The license serial number is not bound to any single machine. This allows multiple Grooper Repositories to be licensed quickly using a single key with no additional setup on your part. However, this also means any Grooper Repository can be licensed over an internet connection. When using the cloud hosted licensing method, ALWAYS keep your license serial number secure and DO NOT share it with anyone that you do not wish to have access.

Installing necessary Grooper services

To fully complete a Grooper installation, you most typically need two Grooper services installed.

• An Import Watcher service
• An Activity Processing service

Import Watcher services are for Import Jobs

The Import Watcher service is required to import digital documents (like PDFs) into Grooper. The Import Watcher creates "Import Jobs" that bring in files to new Batches in Grooper. It is required to automate scheduled imports as well was for ad-hoc user directed imports from the Imports page.

Activity Processing services are for Processing Jobs

The Activity Processing service is required for multithreaded document processing. The Activity Processing service creates "Processing Jobs" that perform various Grooper activity tasks. It is required to automate Grooper Batch Processes as well as for ad-hoc user directed testing from Batch Process Step tester tabs.

We will show you how to install and start the most basic versions of these Grooper services from the Grooper Command Console.

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

Installing an Activity Processing service

⚠

The Grooper Service user account must have the following permissions: File store access Type: NTFS\Share Reason: Read and write access to the Grooper file store location Database access Type: SQL Reason: Read and write access to the Grooper database Logon As Service Type: Local Security Policy Reason: Run services installed via Grooper Command Console

An Activity Processing service must be running to automate task processing in a Batch Process.

To install a Grooper Activity Processing service:

Click here for an interactive walkthrough.

1. Open GCC.
   • GCC can be accessed from the Windows Start menu.
   • The executable gcc.exe can be found in the Grooper install directory.
2. Use the following GCC command to install the service:

   services install <connectionNo> ActivityProcessing <userName> <password> [threadCount] [queueName]

   • <connectionNo> is a required parameter. Enter the connection number for the Grooper Repository using the service. If you don't know the connection number, enter the connections list command for a list of all Grooper Repository connections.
   • <userName> is a require parameter. Enter the user name to run the service under. This user must have the "Log on as Service" permission in Windows.
   • <password> is a required parameter. Enter the password for the provided user name.
   • [threadCount] is an optional parameter and only pertains to installing Activity Processing services. Here, you can enter the number of worker threads an Activity Processing service will use. If left blank, the thread count will default to 1.
   • [queueName] is an optional parameter and only pertains to installing Activity Processing services. This parameter defines the Grooper Processing Queue to pull work from. The "default" Processing Queue will be used if left blank.

3. After attempting the install GCC will present an installation log. At the end of this log it will inform you if:
   • The service was successfully installed.
   • Or, the service installation FAILED.
4. Start the service in one of three ways:
   1. Open Grooper in a web browser and connect to the Grooper Repository. Go to the Machines node in the Design page. Select the newly installed Activity Processing service instance and press the "Start" button.
   2. Start all services using following GCC command:

      services start

   3. Start only the newly installed Activity Processing service instance by using the following GCC command:

      services start <instanceNo>

FYI

To start and stop specific Grooper services, you must know their service's "instance number". If you don't know the service's instance number use the following GCC command: services list This will list all Grooper services installed on the local machine and display some basic information about them. Please note, the "#" column denotes the service instance number.

Example: The first GCC command will install an Activity Processing service to the first Grooper Repository that utilizes three processing threads (with no Processing Queue assigned). The second GCC command will start all services.

services install 1 ActivityProcessing domain\username password 3
services start

Installing an Import Watcher service

⚠

The Grooper Service user account must have the following permissions: File store access Type: NTFS\Share Reason: Read and write access to the Grooper file store location Database access Type: SQL Reason: Read and write access to the Grooper database Logon As Service Type: Local Security Policy Reason: Run services installed via Grooper Command Console

An Import Watcher service must be running to import documents into Grooper.

BE AWARE: These instructions teach you how to install an unconfigured Import Watcher service (one with no import schedules set up).

• Installing the Import Watcher from GCC is the first step to creating any Import Watcher in Grooper.
• Even when unconfigured, the Import Watcher service is required to submit user-directed Import Jobs from the Imports page.
• For automatable/scheduled imports, you will need to configure the Import Watcher service from the Machines node of the Design page by adding one or more Import Schedules.

To install an Import Watcher service:

Click here for an interactive walkthrough!

1. Open GCC.
   • GCC can be accessed from the Windows Start menu.
   • The executable gcc.exe can be found in the Grooper install directory.
2. Use the following GCC command to install the service:

   services install <connectionNo> ImportWatcher <userName> <password>

   • <connectionNo> is a required parameter. Enter the connection number for the Grooper Repository using the service. If you don't know the connection number, enter the connections list command for a list of all Grooper Repository connections.
   • <userName> is a require parameter. Enter the user name to run the service under. This user must have the "Log on as Service" permission in Windows.
   • <password> is a required parameter. Enter the password for the provided user name.

3. After attempting the install GCC will present an installation log. At the end of this log it will inform you if:
   • The service was successfully installed.
   • Or, the service installation FAILED.
4. Start the service in one of three ways:
   1. Open Grooper in a web browser and connect to the Grooper Repository. Go to the Machines node in the Design page. Select the newly installed Import Watcher service instance and press the "Start" button.
   2. Start all services using following GCC command:

      services start

   3. Start only the newly installed Import Watcher service instance by using the following GCC command:

      services start <instanceNo>

FYI

To start and stop specific Grooper services, you must know their service's "instance number". If you don't know the service's instance number use the following GCC command: services list This will list all Grooper services installed on the local machine and display some basic information about them. Please note, the "#" column denotes the service instance number.

Example: The first GCC command will install an unconfigured Import Watcher service to the first Grooper Repository connection. The second GCC command will start all Grooper services.

services install 1 ImportWatcher domain\username password
services start

Installing Grooper Desktop

Grooper Desktop is a lightweight application required to scan paper documents into Grooper using scanner hardware. Furthermore:

• Grooper supports ISIS and TWAIN scanner drivers.
• Grooper Desktop must be installed on any desktop computer connected to scanner hardware.
• Grooper Desktop runs as a service in the background. It can be opened from the Windows system tray to start and stop it.
• Grooper Desktop must be running (started) in order to scan.
• Once installed, users will use the Review activity's "Scan Viewer" to scan documents into Grooper.
• Grooper Desktop drives the scanner from the Scan Viewer. It starts and stops the scanner from the Scan Viewer UI. It "listens" for images being scanned and sends them to the Grooper Repository.

If you are not scanning documents, you do not need to install Grooper Desktop. You may ignore this section.

Click here for an interactive walkthrough on installing Grooper Desktop.

Or, more information on Grooper Desktop (including install instructions) are found in the "Scan Viewer" article.

Upgrading an older version of Grooper

PLEASE NOTE: There are a few things to be aware of before starting your upgrade.

• You can upgrade directly from version 2.72 and above to version 2025.
• When upgrading from versions older than 2.72, you must upgrade to 2.72 before upgrading to 2025.
• Version 2022 introduced Projects to Grooper, which are a new way of organizing Grooper resources in the node tree. Upgraded Grooper Repositories older than 2022 will have many of their nodes reorganized into a Project called "Project 1".
  • For more information on Projects, visit the Project article.
  • For specific guidance on how to navigate the new Project architecture from an upgraded Grooper Repository, visit the upgrade guidance section of the Project article.

Upgrading to 2025 is now easier than ever. 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.

⚠

BE AWARE: 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. Custom scripts/Object Libraries are not guaranteed to work without changes upon upgrading to a new major version of Grooper. 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. Some code objects may have been altered/obsoleted or their names may have changed. Make sure you re-compile all Object Libraries after the upgrade. If you are using code expressions in your Batch Processes, IP Profiles, Data Models or Import/Export Mappings, please verify all expressions are working as intended. Some as some code objects may have been altered or obsoleted or their names may have changed. 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. When upgrading across multiple major versions, Grooper has changed more than if upgrading from the most recent version. Especially when upgrading across multiple versions, your solution design may not be taking advantage of features added 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.

Best practices before upgrading

Back up your Grooper Repository before upgrading

‼

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 on one way to backup and restore your Grooper database and file store, please visit the article below: Backup and Restore Grooper Repository

Validate your Grooper Repository before upgrading

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 more information on validating your Grooper Repository, visit the Validate Branch article.

Step 1: Stop services

Before uninstalling your current version of Grooper, you need to stop all services currently running in the Grooper Repository. This will help avoid potential errors regarding the services connected to your repositories. The easiest way to do this is from the Machines folder node in the Design Page.

1. Go to the Machines folder.
2. Select the "Services" tab.
   • This will ensure you can select all services installed on any machine connected to the Grooper Repository.
3. Select all services in the list.
4. Press the "Stop" button.
   • Once stopped, you will see each service's "Status" listed as "Stopped".

⚠

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: Open the Registry Editor (regedit.exe) Navigate to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services. Select the key of the service you want to delete. Grooper services will always be named something like Grooper.ServiceTypeName.## 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.

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, most commonly from the Windows Settings menu.

• BE AWARE: When upgrading to a new major Grooper version (##.##.####), always back up your Grooper Repositories (database and file store) before upgrading.
• BE AWARE: Even when upgrading to a new minor Grooper version (##.##.####), it is still considered best practice to back up your Grooper Repositories.

To uninstall Grooper:

1. On the machine(s) where Grooper is installed, open Windows Settings and select "Apps". Scroll down through your list of apps until you find the Grooper application. Or, use the search bar to search for "Grooper".
2. Select the Grooper application.
3. When it expands, select "Uninstall".
   • The uninstallation process may take a few minutes. You may be prompted to restart the computer once finished.
4. If uninstalling the Grooper Web Client, repeat this process for the Grooper Web Client application on the Grooper web server.
   • It is also considered best practice to stop the Grooper app pool in IIS before uninstalling the Grooper Web Client application.
5. If uninstalling Grooper Desktop, repeat this process for the Grooper Desktop application on each workstation where Grooper Desktop is installed.

Step 3: Install the new Grooper version

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

• https://www.bisok.com/grooper-xchange/downloads-and-resources/
• Be sure to download installers for each application required for your install (Grooper, Grooper Web Client, and/or Grooper Desktop).

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

• Installing Grooper
• Installing Grooper Web Client
• Installing Grooper Desktop

Step 4: Upgrade Grooper Repositories

• Grooper Repositories only need to be upgraded when upgrading to a new major Grooper version (##.##.####). For minor version upgrades (##.##.####) you can skip this step.
• BE AWARE: Grooper Repositories can be upgraded to a newer major version but cannot be downgraded. Please be sure you want to upgrade a Grooper Repository before doing so.

After installing a newer major version of Grooper, each Grooper Repository must be upgraded as well. This is done from Grooper Command Console with the following GCC command:

connections upgrade <connectionNo>

Full instructions for upgrading a Grooper Repository can be found in the GCC article.

Click here for an interactive walkthrough!

Congratulations! You've upgraded Grooper! Once a Grooper Repository is upgraded, it is effectively up to date with the installed Grooper version.