2023:Grooper Config (Application)

Grooper Config is part of the Grooper Product Suite. This program is used to configure settings specific to a server or workstation (whereas Grooper Design Studio is used to architect objects such as Content Models and Batch Processes used by all servers and workstations).

Grooper Config has three main purposes:  

1. Setting up new and connecting to existing Grooper Repositories.
2. Installing product licensing
3. Setting up and configuring Grooper Services, such as a Grooper Licensing service for a server to hand out Grooper licenses to client workstations.

About

Grooper Config is a system configuration application. This program allows for required system maintenance functions in order to get your Grooper installation up and running. Grooper Config is in charge of managing three things. Grooper Repository Connections Grooper Services Licensing Activation ⚠ Grooper Config must be run as an administrator to perform most of its functionality. It performs functions that require elevated access in Windows.

FYI

Older Grooper users will notice Grooper Config's UI screen has changed somewhat in version 2021. These changes are detailed briefly below. Grooper Repository Connections The steps to configure Grooper Repository creation and connection are largely the same. However, you will immediately notice your list of Grooper Repository connections is not present on the main screen. You will now configure Grooper Repository connections using the Repositories property by selecting the property and pressing the ellipsis button at the end. This will bring up a new window to configure Grooper Repositories. Visit the How To: Grooper Repository Connections section for more information. Grooper Services Grooper Service installation and management were previously configured using the "Services" tab. Now, you will press the "Edit Services..." button instead. Aside from pressing a button instead of switching to a tab, service installation and configuration remains the same. Default services credentials were previously entered using the "Settings" tab. Now, these are entered using the Service User and Service Password properties on the main screen. Licensing Activation Product licensing was previously activated using Grooper Design Studio. Now, licenses are activated using Grooper Config using the "Manage License..." button. For information on how to activate a license in Grooper Config, visit the How To: Licensing Activation section of this article.

How To: Grooper Repository Connections

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 to perform most of its functionality. It performs functions that require elevated access in Windows.

Creating a New Grooper Repository

Initialize Grooper ConfigEstablish the File Store Location(Optional) Install SQL ExpressCreate a New Grooper Repository

Initialize Grooper Config

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. Press "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: A database connection A file store connection The file store simply needs to be a Windows folder you have readable and writable access to. In this case, it is a folder named "2021FileStore" in a parent folder named "GrooperFileStores" in the "Documents" folder of this server. What you name your file store and where you put it is totally up to you.
⚠ Grooper strongly recommends always using a UNC path to avoid access problems when networking your Grooper Repositories. Mapped and local drive references may not be accessible to other users or machines. The file store can be any folder you have writeable access to. However, using a fully qualified UNC path is always regarded as best practice. UNC paths can be established using the "Sharing" properties of a folder. Right-click the folder Select the "Properties" option.
In the following window, press the "Sharing" tab. If the folder is already shared, you will see the UNC path under "Network Path" The UNC naming convention for Windows paths is as follows: \\host-name\file_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.

Install SQL Express

⚠	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 tab.

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 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. Press the "Download SQL Express..." button. The installer files will download automatically. You will see this dialog box appear upon successful download. Press "Ok" to continue.
Next, you can install SQL Express directly from Grooper Config. Press the "Install SQL Express..." button. The following confirmation box will appear. Press "Yes" to continue installing SQL Express.
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. Press "Ok" to continue.
You will then be prompted through the SQL Express installation process.
Upon successful installation, the following dialog box will appear. 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. Press "Yes" to delete the file.

Create 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. Select the Repositories property in Grooper Config. Press the ellipsis button at the end.
This will open up a new window to add Grooper Repository connections. Press the "Add" button to add a new connection.
Remember, a Grooper Repository is two things: A database connection A file store connection The first part of creating a new Grooper Repository is establishing the database connection. Select the Server property and enter the server's name running the SQL environment. For SQL Express installs, the server instance will default to the machines name followed by \GROOPER as seen here. For standard SQL Server installs, simply enter the server machine's name. Select the Database property and enter a name for the database. Here, we chose to name it 2021Database. Name the database whatever you would like. Press the "Test Connection" button. 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. Press "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.
Upon creating the database, you will get a message letting you know the database has not been initialized. Also note the "Status" of this Repository Connection has changed from Unavailable to NotInitialized. Press "Ok" to continue. Press the "Initialize..." button.
Remember, a Grooper Repository is two things: A database connection 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. Select the Storage Path property and enter the file path for the file store's folder. Press 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 Grooper2021. However, 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 press the "Rename..." button to rename it.
Upon successful initialization, you will receive this confirmation window. Press the "Ok" button to continue. You will see the "Status" of the Grooper Repository change from NotInitialized to Ok. You've officially established a connection to a Grooper Repository at this point. Press the "Ok" button to finish.
This will return you to the main Grooper Config window. Press the "Save" button too finalize your Grooper Repository connection.
After licensing your Grooper installation, you will be able to access the Grooper Repository in Grooper Design Studio. The Grooper Repository forms the root node of the Node Tree when the repository is selected in Grooper Design Studio.

Connecting to an Existing Grooper Repository

Add a Repository ConnectionConfigure the Connection

Add the Repository Connection

Connecting to an existing Grooper Repository is very similar to creating a new one. If anything it's the exact same process, just with less steps. For this tutorial, we have a second machine that will connect to the Grooper Repository created in the Creating a New Grooper Repository tutorial. This machine has Grooper installed, but does not have a local SQL environment. However, it doesn't need one. As long as it has networked access to the SQL server where the Grooper Repository's database is created, as well as access to the Grooper Repository's file store location, it can connect to the Grooper Repository.

This will open up a new window to add Grooper Repository connections. Press the "Add" button to add a new connection.

Configure the Connection

Select the Server property and enter the server's name running the SQL environment. Select the Database property and enter the Grooper Repository's database name. Press the "Test Connection" button. In this case, the Grooper Repository has already been created from on the listed server machine. The database has already been created and it's associated file store has been initialized. Furthermore, this machine has network access to the database and file store. Therefore, a dialog box appears letting you know the connection is successful. Press "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.
You will see the "Status" listed as Ok indicating you have successfully connected to the Grooper Repository. Press the "OK" button to continue.
This will return you to the main Grooper Config window. Press the "Save" button to finalize your Grooper Repository connection.
After licensing your Grooper installation, you will have full access to the Grooper Repository in Grooper Design Studio. The Grooper Repository forms the root node of the Node Tree when the repository is selected in Grooper Design Studio. Any machine connecting to this Grooper Repository will have access to the objects in the repository. Each machine can create new and configure existing objects. Essentially, you have now networked access to the Grooper environment.

Setting the Default Repository

About Default RepositoriesChange the Default Repository in Grooper ConfigSet the Default Repository from Grooper Design Studio

You may have multiple connections to multiple Grooper Repositories on a single workstation. In Grooper Design Studio, you can access any Grooper Repository you're connected to. You can switch to a different Grooper Repository using the "File" menu, selecting "Change Repository" and choosing a Grooper Repository from the list. However, you can only have a single Default Repository. When opening Grooper Design Studio, Grooper always connects to and displays the selected Default Repository. In this case, the Default Repository is set to the repository named "Grooper2021". So, if we want to work in the repository named "Grooper Wiki", we have to switch connections as described above. If you switch to another repository and close Grooper Design Studio, the next time you open the program, it will still connect to the Default Repository first (in this case the "Grooper2021" repository).
The Grooper Unattended Client application also will only process Batch Process Steps in the Default Repository. In most cases, this does not really matter for Grooper architects building objects in Grooper Design Studio. Even when connected to a different Grooper Repository than the Default Repository, there are many different ways to apply an Unattended Activity to a Batch, Batch Folder, or Batch Page to test your object configurations. However, this can cause some confusion when attempting to create production level Batches and process their Batch Processes outside of the Default Repository. Here, we are working in the Default Repository for this Grooper install. It's name is "Grooper2021". We have created a new production level Batch. It is a very simple batch with a very simple Batch Process, just three steps.
If we process this Batch... The first step (the Unattended Activity, Recognize) executes without issue. The Grooper Unattended Client runs successfully and processes the Batch Process Step.
However, we're going to get a different result if we're working outside the Default Repository. Here, we are working in a different Grooper Repository. It's name is "Grooper Wiki". We have created a new production level Batch, containing the exact same documents as the example above. It uses the exact same Batch Process as well, just three steps.
In this case, if we process the Batch The Unattended Activity Client opens, but will fail to execute. It will just hang there, not knowing what to do. Notice the Batch, Batch Process, and Step properties are blank. Essentially, the Grooper Unattended Client application is looking for a Batch in the Default Repository. Since we tried to process a Batch outside of the Default Repository, the Grooper Unattended Client doesn't see what we told it to process. The information just doesn't line up with the information it has access to (only the Default Repository). We can resolve this issue by switching the Default Repository'.

Change the Default Repository in Grooper Config

You can change the Default Repository in Grooper Config. First open Grooper Config. ⚠ You must run Grooper Config as an administrator to change the Default Repository. Select the Default Repository property. Press the drop down menu button to reveal a list of all Grooper Repository connections. Select the Grooper Repository you wish to be the Default Repository.
You will see the selected Grooper Repository listed as the Default Repository. Press the "Save" button when finished. FYI If press the "Save" button and see this error message, you have not opened Grooper Config as an administrator. Close the program, and re-run it as an administrator to successfully change the Default Repository.

Set the Default Repository from Grooper Design Studio

You can also change the Default Repository directly from Grooper Design Studio. ⚠ You must run Grooper Design Studio as an administrator to change the Default Repository. Select "File" from the menu bar. Select "Change Repository". Hold the Shift button and select the Grooper Repository you wish to be the Default Repository. FYI If you see this error message, you have not opened Grooper Design Studio as an administrator. Close the program, and re-run it as an administrator to successfully change the Default Repository.

How To: Grooper Services

Grooper Services are various executable applications that run as a Windows Service to aid Grooper. Service Instances are installed, configured, started and stopped using the "Edit Services..." button of Grooper Config.

For example, Import Watcher is a service that watches an assigned external storage location, like a Windows folder or an email inbox, and will automatically import its contents into Grooper for automated Batch creation.

⚠	Grooper Config must be run as an administrator to install, edit, start and stop services.

Install or Edit Grooper Service

Installing or Editing a Grooper ServiceStopping and Uninstalling a Grooper Service

Installing or Editing a Grooper Service

To either install a new or edit an existing Grooper Service, press the "Edit Services..." button from Grooper Config.
This will bring up a new configuration window for Grooper Services, the "Service Manager" window. To install a new Grooper Service, press the "Install..." button. To edit an existing Grooper Service, select a service from the list, and press the "Edit..." button.

Stopping and Uninstalling a Grooper Service

Grooper Services are also uninstalled from the "Service Manager" window. The key thing to keep in mind is services must be stopped before they can be uninstalled. To stop a Grooper Service, select the service from the list, and press the "Stop" button. You will see the icon next to the item change from green to red after it is stopped. Its status in the "Status" column will also change from Running to Stopped.

Once the service is stopped, you can uninstall it. Select the stopped Gropper Service. Press the "Uninstall" button to uninstall it. On the following dialog box, press "Yes" to confirm the uninstallation.

Example: Installing a Grooper Licensing Service

Once a license has been activated on a machine, you can distribute licensing to client workstations by installing a Grooper Licensing service. This makes the single licensed machine a host, serving licenses to multiple machines. Installing the Grooper Licensing service is the first step in creating a "self hosted" licensing setup.

• Grooper Services are various executable applications that run as a Windows Service to aid Grooper.
• The Grooper Licensing service will allow one licensed machine to hand out licensing information to other workstations.
• To do this, the machine installing the service must have an installed version of Grooper that has been activated with a product key or licensing package.
  • Refer to the 2023:License Activation#Stand-Alone Licensing tutorial for more information on how to activate your license.

Open Grooper ConfigAdd a New Grooper Licensing ServiceStart the Service

Open Grooper Config

Services are installed and configured in the Grooper Config application. ⚠ You must run Grooper Config as an administrator to install, configure, start and stop services. ⚠ The Grooper Service User must have the "Log on as Service" permission.

Add a New Service

Press the "Edit Services..." button to add a new service.
This will bring up a Service Manager window to install, configure and otherwise manage Grooper services. Press the "Install..." button. This will bring up a window to install a Grooper Service. Select Grooper Licensing Press the "OK" button to continue. FYI Be aware the service is installed for whichever repository is selected in the Repository dropdown in the upper right corner. This defaults to whatever is selected for the Default Repository in Grooper Config, but can be changed using the dropdown list.
Grooper Licensing runs as a web service. Client machines will point to the host machine, port number and URL path indicated here via the Connection URL. The settings here are populated by default. However, you can edit these if necessary. You must always enter service user authentication in order for the service to run. Use the User Name and Password property to enter service user authentication. Press the "Execute" button to continue.
FYI You may also configure default service user settings on the main Grooper Config screen. If you enter authentication credentials here, you do not need to enter them when configuring the service. This can save you time when installing and configuring multiple services.

Start the Service

Upon pressing the "Execute" button, a new Grooper Licensing server is added to the list of services. However, notice its Status is listed as Stopped Also, the icon next to the item is red.
We need to start the service in order for this machine to start hosting license distribution. Select the service you wish to start. Press the "Start" button.
Upon successfully starting the service, you will see the Status change to Running The icon next to the item will also change from red to green. Now, this machine can use this Grooper Licensing service to hand out licensing information to workstations. We will discuss how to configure workstations to do this in the next tutorial.

Example: Installing an Activity Processing Service to Throttle Step Processing

Activity Processing services allow you to automate Unattended Activity tasks. If you do not assign a Processing Queue to the Activity Processing service, it will pick up tasks in the "default queue", automatically processing any tasks that aren't in a specific Processing Queue. Creating an Activity Processing service without a Processing Queue is generally the easiest way to get started automating steps in a Batch Process.

In this scenario, we will install an Activity Processing service with no associated Processing Queue and give it a certain number of threads to use.

• This service will pick up and process any Unattended Activity tasks for Batch Process Steps with no Processing Queue assigned.

⚠

Be aware of the "n minus one" rule! Services are assigned a number of CPU threads when you install them. For some services, like Import Watcher, the will always run using a single thread. Activity Processing services can run using multiple threads. Keep in mind, your machine only has a certain number of processing threads available. You will run into errors if you over-allocate your available threads. Remember too, the operating system itself must always have a single thread available to run. So, the absolute maximum number of threads you can assign to all your services should not go beyond the total number of threads available minus one reserved for the operating system. Hence, the "n minus one" rule. The "n minus one" rule is as follows: If "n" is the maximum number of threads available on your machine, the maximum number of threads you can distribute to Grooper services is "n" minus one. Be aware of the "n minus x" rule! Other programs running in the background will need threads to run as well. If SQL is installed on the same machine as your Grooper services, you should follow an "n minus two" rule, reserving one for the OS and one for SQL. If IIS and SQL are installed on the same machine as your Grooper services, you should follow an "n minus three" rule, reserving one for the OS, one for SQL, and one for IIS. If other applications, such as anti-virus software, are running in the background you will need to reserve threads for those applications as well. THE LONG STORY SHORT HERE IS DO NOT OVER-ALLOCATE YOUR AVAILABLE THREADS! GROOPER CAN BEHAVE ERRATICALLY IF YOU DO!

Open Grooper Config

1. Press the "Edit Services" button.

⚠	Grooper Config must be run as an administrator to install, edit, start and stop services.

⚠

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

2. In the "Service Manager" window, press the "Install" button.
   • This will bring up the "Install New Service" window.
3. Using the dropdown list, select the Grooper Repository for which you want to install the service.
4. Select Activity Processing.
5. Press the "OK" button when finished.

This will bring up the "Activity Processing" configuration window.

6. Leave the Queue Name property blank.
   • This will create an Activity Processing service that picks up tasks for the "default queue", allowing it to processes tasks for Batch Process Steps with no Processing Queue assigned.
7. Adjust the Number of Threads property to the number of threads you wish to run.
   • Always follow the "n minus one" rule. The VM used for this tutorial only has 4 threads. I have no other services running. So, I can run a maximum of 3 threads.
8. Enter user credentials to run the service.
   • Please note, the account specified must:
     • Have the "Logon as Service" permission on the machine on which the service is to run.
     • Have access to the Grooper database.
     • Have access to the Grooper file store location.
9. Press the "Execute" button when finished.

This will add the service to your list of services. Last, you will need to start the service.

10. Select the service you wish to start.
11. Press the "Start" button"
12. Upon successfully starting, you will see the Status change from "Stopped" to "Running".

How To: License Activation

License activation is different in version 2023 compared to older versions.

• This prompted us to make a whole article on the topic of license activation.
• For more information, please visit the License Activation article.