View source for 2024:Install and Setup

{{AutoVersion}}
<blockquote>
Welcome to Grooper 2024!
</blockquote>

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:
# [[#Installing Grooper |Installing Grooper]]
# [[#Setting up and installing Grooper Web Client|Setting up and Installing Grooper Web Client]]
# [[#Connecting to a Grooper Repository|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.
# [[#License activation|License activation]]
# [[#Installing necessary Grooper services|Installing necessary Grooper services]] - As a practical matter, most Grooper installs will need at least two Grooper services installed, an '''Activity Processing''' and '''Import Watcher''' service.
# [[#Installing Grooper Desktop|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|Upgrading an older version of Grooper]] section of this article for more information.'''''


To get up and running with Grooper 2024, 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.  [[#Installing necessary Grooper services|See here for more information.]]

<section begin="antivirus_advice" />
{|class="attn-box"
|
&#9888;
|
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.
|}
<section end="antivirus_advice" />
=== 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 ===
{|class="how-to-table"
|
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

|
[[File:2023-Install and Setup-Installation 04.png]]
|-
|

Click on the link for Grooper 2024. Here you will see three links to downloads:
* The Grooper installer
* The Grooper Web Client installer
* The Grooper Desktop Installer.

All users will need the Grooper and Grooper Web Client installers to set up the Grooper web server.  The Grooper Desktop installer will need to be installed on workstations used for scanning.
|
[[File:2024 InstallAndSetup 02 DownloadingInstallers-01.png|class=simpleborder|800px]]
|-
|
The installer files will download as ZIP files. You will need to extract each zipped folder. Right-click each ZIP and select "Extract All..."

When you have unzipped all the installer ZIPs, you ready to install the software. Continue to the next section for installation instructions. 
|
[[File:2024 InstallAndSetup 02 DownloadingInstallers-02.png|class=simpleborder|800px]]
|}

===Installing Grooper===
The Grooper installer lays down the program files for the Grooper application. 
* Both Grooper and Grooper Web Client must be installed when setting up a "Grooper web server".
**<li class="attn-bullet">'''''BE AWARE:''''' It is best practice to install Grooper ''before'' installing the Grooper Web Client application. 
* Grooper alone is installed when setting up "Grooper processing servers", dedicated to running '''Activity Processing''' services.

{|class="how-to-table"
|

# After extracting the installer ZIP package, open the extracted folder "GrooperInstall_24.00.xxxx_x64" to reveal the installation files.
# Open the "setup.exe" file to start the Grooper Installer.
# When the install wizard pops up, select "Next" to start installing Grooper.
|
[[File:2024_InstallAndSetup_03_InstalGrooper-01.png|class=simpleborder]]
|-
|
If this is your first time installing Grooper, you may be prompted to install various perquisite applications.
#<li value=4>Select "Install" to start installing prereqs, if prompted.
#: '''''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.
|
[[File:2024_InstallAndSetup_03_InstalGrooper-02.png|class=simpleborder]]
|-
|
#<li value=5>Once prerequisite components are installed, the Grooper installer will pop up. Click "Next" to move to the next screen. 
|
[[File:2024_InstallAndSetup_03_InstalGrooper-03.png|class=simpleborder]]
|-
|
#<li value=6>Read through the End User License Agreement and click the button next to "I accept the terms in the license agreement". 
# Select "Next" to continue. 
|
[[File:2024_InstallAndSetup_03_InstalGrooper-04.png|class=simpleborder]]
|-
|
#<li value=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. 
# Select "Next" to continue.
|
[[File:2024_InstallAndSetup_03_InstalGrooper-05.png|class=simpleborder]]
|-
|
#<li value=10>Select the button next to your preferred setup type. The vast majority of users will select "Complete" to perform a complete setup.
#Click "Next". 
|
[[File:2024_InstallAndSetup_03_InstalGrooper-06.png|class=simpleborder]]
|-
|valign=top|
#<li value=12>You are now ready to install the program. Click "Install" to begin installation. 

Installation should only take a few minutes.  Press the "Finish" button when prompted to finalize the installation.
|
[[File:2024_InstallAndSetup_03_InstalGrooper-07.png|class=simpleborder]]
|}

===Setting up and installing Grooper Web Client ===

The Grooper web client is the interface layer of Grooper.  It is how users interact with the platform, using a web-based user interface.  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 2024 web server, there are three things that need to be installed first:
# The Grooper application
#*<li class="attn-bullet"> It is best practice to install Grooper ''before'' installing the Grooper Web Client application.
#*<li class="attn-bullet"> If you have not installed Grooper yet and need instructions, refer to the [[#Installing Grooper|section above]].
# Internet Information Services (IIS)
# The Grooper Web Client application

{|class="fyi-box"
|
'''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.
* For information on how to install '''Grooper Desktop''' please refer to the [[#Installing Grooper Desktop]] and [[#Reserve URL for Grooper Desktop]] sections below.
|}

==== 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 using the Grooper web client. 


For quick reference, we will be installing/enabling the following roles and 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.

{|class="how-to-table"
|
To install Internet Information Services (IIS):

#Open Server Manager. 
|
[[File:2023-Install and Setup-Installation 18.png]]
|-
|
#<li value=2>In the top right corner, click on "Manage" to bring up the drop down menu. 
#Click "Add Roles and Features".
|
[[File:2023-Install and Setup-Installation 19.png]]
|-
|
#<li value=4>In the window that pops up, feel free to read through the information associated with the installation wizard and then click "Next". 
|
[[File:2023-Install and Setup-Installation 20.png]]
|-
|
#<li value=5>Make sure "Role-based or feature-based installation" is selected. 
#Click "Next". 
|
[[File:2023-Install and Setup-Installation 21.png]]
|-
|
#<li value=7>Select the desired server from the server pool list. 
#Click "Next". 
|
[[File:2023-Install and Setup-Installation 22-redacted.png]]
|-
|
#<li value=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). 
#Click "Next".
|
[[File:2023-Install and Setup-Installation 23.png]]
|-
|
#<li value=11>On this screen you don't need any additional features, so just click "Next". 
|
[[File:2023-Install and Setup-Installation 24.png]]
|-
|
#<li value=12>Feel free to read through the description of what a web server is, and click "Next". 
|
[[File:2023-Install and Setup-Installation 25.png]]
|-
|
#<li value=13>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
# Click "Next" after all components are selected.
|
[[File:2023-Install and Setup-Installation 26.png]]
|-
|
#<li value=15>If desired, click the checkbox next to "Restart the destination server automatically if required". 
#Click the "Install" button and allow the installation to run. 
|
[[File:2023-Install and Setup-Installation 27.png]]
|-
|
#<li value=17>Once installation is complete, click "Close" to close the wizard. 
|
[[File:2023-Install and Setup-Installation 28.png]]
|}

==== 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 Grooper 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:

{|class="wikitable"
|style="width:20%"|
'''Permission'''
|style="width:20%"|
'''Type'''
|style="width:30%"|
'''Reason'''
|style="width:30%"|
'''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.

{|class="how-to-table"
|
# After extracting the installer ZIP package, open the extracted folder "GrooperWebClient_24.00.xxxx" to reveal the installation files.
# Open the "setup.exe" file to start the Grooper Installer.
# When the installer opens, click "Next" to continue. 
|
[[File:2024_InstallAndSetup_04_03_InstallWebClient-01.png|class=simpleborder]]
|-
|valign=top|
#<li value=4> Read through the End User License Agreement and click the radial button next to "I accept the terms in the license agreement". 
#Click "Next" to continue. 
|
[[File:2024_InstallAndSetup_04_03_InstallWebClient-02.png|class=simpleborder]]
|-
|valign=top|
#<li value=6> Enter the user name and password for the account that will logon to use Grooper (i.e. the Grooper App Pool user).
#* 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.
{|class="important-box"
|
'''!!'''
|
'''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 (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'''.
|}
#<li value=7> Click "Next". 
|
[[File:2024_InstallAndSetup_04_03_InstallWebClient-03.png|class=simpleborder]]
|-
|valign=top|
#<li value=8> Click the "Install" button to begin installation. 

Installation should only take a few minutes. Press the "Finish" button when prompted to exit the installer.
|
[[File:2024_InstallAndSetup_04_03_InstallWebClient-04.png|class=simpleborder]]
|}

==== 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:
# Enable HTTPS (also known as SSL or Secure Socket Layers) by binding an SSL certificate to the Default website.
#* This is the highly preferred 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.
# 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.

<div style="padding-left: 2em">
===== 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.

# Select your server in the left-hand "Connections" panel.
# Select "Server Certificates".
# In the right-hand "Actions" panel, select "Create Self-Signed Certificate..."
# In the dialog box that appears, enter a name for the certificate.
# Click "OK".
# In the left-hand "Connections" panel, expand the server connection and "Sites" folder and select the "Default Web Site".
# In the right-hand "Actions" panel, select "Bindings..."
# In the window that appears, select "Add..."
# In the next window, under "Type" select "https" from the drop down list.
# Under "Host name" enter the host address (if applicable).
# Under "SSL certificate", select the self signed certificate you created earlier.
# Click "OK" when finished.
# In the previous window, you should now see the binding for port 443.
# Click "Close".

===== How to treat a website as secure =====

'''''BE AWARE!  THIS IS CONSIDERED A WORKAROUND!'''''

'''''This is appropriate primarily 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 when possible.'''''
* '''''Even using a self-signed certificate  is preferable to this method.'''''

[[File:2023 InstallAndSetup 02 WebClient 02 SecureWebsites 01.png|right|class=simpleborder|400px]]

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 121.0.2277.83 is known to have this issue.


Chromium based browsers can treat HTTP URLs as secure by enabling the "'''''Insecure origins treated as secure'''''" flag.
# Navigate to the following depending on your web browser:
#* <code>chrome://flags</code> for Google Chrome
#* <code>edge://flags</code> for Microsoft Edge
# Search for "Insecure origins treated as secure" and change it to "Enabled"
# Enter your Grooper web client's host URL (i.e. <code><nowiki>http://hostname</nowiki></code>)
# Relaunch the browser.
# 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.
</div>

== 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:
# A database connection 
# 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.

{|class="attn-box"
|
&#9888;
|
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:
# A Microsoft SQL Server instance for the Grooper database
# A Windows folder location for the Grooper file store

==== MS SQL Server ====

Remember, a Grooper Repository is two things:

# '''A database connection'''
# 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:

# A database connection
# '''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: <code>\\hostname\file_path\file_path</code>

{|class="fyi-box"
|
'''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 ===

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.
{{#lst:2024:Grooper Command Console (Application)|create_grooper_repo}}

=== Connecting to an existing Grooper Repository ===

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.
{{#lst:2024:Grooper Command Console (Application)|connect_to_repo}}

== 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 key GUID, something like "1a2b3c4d-5e6f-7g8h-9i10-j11k12l13m14". You will need this GUID to license your Grooper installation.

{{#lst:2024:License Activation|about_licensing}}

In this article, we will show you how to perform "cloud hosted" licensing.
* Remember, cloud hosted licensing is the easiest, but least secure method of licensing.
* For more information on other licensing setups, visit the [[License Activation]] article.

=== How to activate your license using the "cloud hosted" method ===
{{#lst:2024:License Activation|cloud_hosted}}

== 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


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. 


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.


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

{|class="attn-box"
|
&#9888;
|
Grooper Command Console must be run as an administrator.  It performs functions that require elevated access in Windows.
|}

=== Installing an Activity Processing service ===

{{GrooperServiceUserRights}}

To install a Grooper '''Activity Processing''' service:
# Open GCC.
#* GCC can be accessed from the Windows Start menu. 
#* The executable gcc.exe can be found in the Grooper install directory.
# Use the following GCC command to install the service:
#: <pre>services install <connectionNo> ActivityProcessing <userName> <password> [threadCount] [queueName]</pre>
#:* <code><connectionNo></code> 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 <code>connections list</code> command for a list of all Grooper Repository connections.
#:* <code><userName></code> 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.
#:* <code><password></code> is a required parameter. Enter the password for the provided user name.
#:* <code>[threadCount]</code> 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.
#:* <code>[queueName]</code> 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.
# 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.
# Start the service in one of three ways:
## 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.
## Start all services using following GCC command:
##: <pre>services start</pre>
## Start only the newly installed '''Activity Processing''' service instance by using the following GCC command:
##: <pre>services start <instanceNo></pre>

{|class="fyi-box"
|
'''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:
<pre>services list</pre>

This will list all Grooper services installed on the local machine and display some basic information about them.

[[File:2024 GrooperCommandConsole 3 3 StartStopServices-01.png|class=simpleborder]]

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.
<pre>
services install 1 ActivityProcessing domain\username password 3
services start
</pre>

=== Installing an Import Watcher service ===

{{GrooperServiceUserRights}}

'''''BE AWARE:''''' These instructions teach you how to install an ''unconfigured'' '''Import Watcher''' service.  This 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.


To install an ''unconfigured'' '''Import Watcher''' service:
# Open GCC.
#* GCC can be accessed from the Windows Start menu. 
#* The executable gcc.exe can be found in the Grooper install directory.
# Use the following GCC command to install the service:
#: <pre>services install <connectionNo> ImportWatcher <userName> <password></pre>
#:* <code><connectionNo></code> 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 <code>connections list</code> command for a list of all Grooper Repository connections.
#:* <code><userName></code> 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.
#:* <code><password></code> is a required parameter. Enter the password for the provided user name.
# 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.
# Start the service in one of three ways:
## 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.
## Start all services using following GCC command:
##: <pre>services start</pre>
## Start only the newly installed '''Import Watcher''' service instance by using the following GCC command:
##: <pre>services start <instanceNo></pre>

{|class="fyi-box"
|
'''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:
<pre>services list</pre>

This will list all Grooper services installed on the local machine and display some basic information about them.

[[File:2024 GrooperCommandConsole 3 3 StartStopServices-01.png|class=simpleborder]]

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.
<pre>
services install 1 ImportWatcher domain\username password
services start
</pre>

== Installing Grooper Desktop ==
{|class="fyi-box"
|
'''FYI'''
|
Grooper Desktop is a lightweight application required to scan physical paper documents into Grooper.  

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

{{#lst:2024:Scan Viewer (UI Element)|installing_grooper_desktop}}

== Upgrading an older version of Grooper ==
{{#lst:Upgrading Grooper to a New Version|UpgradeAbout}}
{{#lst:Upgrading Grooper to a New Version|Upgrade1}}