2023:Grooper Config (Application): Difference between revisions

From Grooper Wiki
← Older edit
No edit summary
 
(23 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<blockquote style="font-size:14pt">
{{AutoVersion}}
<section begin="glossary" />
<blockquote>
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 Model]]s''' and '''[[Batch Process]]es''' used by ''all'' servers and workstations).
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 Model]]s''' and '''[[Batch Process]]es''' used by ''all'' servers and workstations).
</blockquote>
</blockquote>
 
<section end="glossary" />
Grooper Config has three main purposes:  
Grooper Config has three main purposes:  


# Setting up new and connecting to existing [[Grooper Repository|Grooper Repositories]].
# Setting up new and connecting to existing [[Grooper Repository|Grooper Repositories]].
# Setting up and configuring [[Grooper Service]]s, such as a [[Grooper Licensing]] service for a server to hand out Grooper licenses to client workstations.
# Installing product licensing
# Installing product licensing
# Setting up and configuring [[Grooper Service]]s, such as a [[Grooper Licensing]] service for a server to hand out Grooper licenses to client workstations.


== About ==
== About ==
{|cellpadding=10 cellspacing=5
{|cellpadding=10 cellspacing=5
|valign=top style="width:40%"|
|valign=top style="width:40%"|
Line 17: Line 18:
# [[Grooper Repository]] Connections
# [[Grooper Repository]] Connections
# [[Grooper Service]]s
# [[Grooper Service]]s
# Licensing Activation
# [[2023:License Activation]] (for "self hosted" licensing installs)


{|cellpadding="10" cellspacing="5"
{|class="attn-box"
|-style="background-color:#f89420; color:white"
|-
|style="font-size:22pt"|'''&#9888;'''||Grooper Config must be run as an administrator to perform most of its functionality.  It performs functions that require elevated access in Windows.
|⚠
|
Grooper Config must be run as an administrator to perform most of its functionality.  It performs functions that require elevated access in Windows.
|}
|}


Line 29: Line 32:




{|cellpadding="10" cellspacing="5"
{|class="fyi-box"
|-style="background-color:#36b0a7; color:white"
|-
|style="font-size:14pt"|'''FYI'''
|
|Older Grooper users will notice Grooper Config's UI screen has changed somewhat in version 2021.  These changes are detailed briefly below.
'''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'''
'''Grooper Repository Connections'''
Line 59: Line 64:
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.
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.


{|cellpadding="10" cellspacing="5"
{|class="attn-box"
|-style="background-color:#f89420; color:white"
|-
|style="font-size:22pt"|'''&#9888;'''||Grooper Config must be run as an administrator to perform most of its functionality.  It performs functions that require elevated access in Windows.
|
⚠
|
Grooper Config must be run as an administrator to perform most of its functionality.  It performs functions that require elevated access in Windows.
|}
|}


Line 105: Line 113:
|valign=top|
|valign=top|


{|cellpadding="10" cellspacing="5"
{|class="attn-box"
|-style="background-color:#f89420; color:white"
|-
|style="font-size:22pt"|'''&#9888;'''||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.
|⚠
|
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.
|}
|}


Line 130: Line 140:
=== Install SQL Express ===
=== Install SQL Express ===


{|cellpadding="10" cellspacing="5"
{|class="attn-box"
|-style="background-color:#f89420; color:white"
|-
|style="font-size:22pt"|'''&#9888;'''||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.
|⚠
|
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.
|}
|}


Line 221: Line 233:
|-
|-
|valign=top|
|valign=top|
{|cellpadding="10" cellspacing="5"
{|class="fyi-box"
|-style="background-color:#36b0a7; color:white"
|-
|style="font-size:14pt"|'''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.
|
'''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.
|}
|}
|
|
Line 247: Line 262:
# Press the "Execute" button to initialize the Grooper Repository.
# Press the "Execute" button to initialize the Grooper Repository.


{|cellpadding="10" cellspacing="5"
{|class="attn-box"
|-style="background-color:#f89420; color:white"
|-
|style="font-size:22pt"|'''&#9888;'''||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.
|⚠
|
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.
|}
|}


{|cellpadding="10" cellspacing="5"
{|class="fyi-box"
|-style="background-color:#36b0a7; color:white"
|-
|style="font-size:14pt"|'''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.
|
'''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.
|}
|}
|
|
Line 318: Line 338:
|-
|-
|valign=top|
|valign=top|
{|cellpadding="10" cellspacing="5"
{|class="fyi-box"
|-style="background-color:#36b0a7; color:white"
|-
|style="font-size:14pt"|'''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.
|
'''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.
|}
|}
|
|
Line 353: Line 376:


<tabs margin:20px">
<tabs margin:20px">
<tab name="About Default Repositories" style="margin:20px">
{|cellpadding=10 cellspacing=5
|valign=top style="width:40%"|
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).
|
[[File:Default-repository-1.png]]
|-
|valign=top|
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.
|
[[File:Default-repository-2.png]]
|-
|valign=top|
# 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'''.
|
[[File:Default-repository-3.png]]
|-
|valign=top|
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.
|
[[File:Default-repository-4.png]]
|-
|valign=top|
# 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''''.
|
[[File:Default-repository-5.png]]
|}
</tab>
<tab name="Change the Default Repository in Grooper Config" style="margin:20px">
<tab name="Change the Default Repository in Grooper Config" style="margin:20px">
=== Change the Default Repository in Grooper Config ===
=== Change the Default Repository in Grooper Config ===
Line 408: Line 383:
You can change the '''''Default Repository''''' in Grooper Config.  First open Grooper Config.
You can change the '''''Default Repository''''' in Grooper Config.  First open Grooper Config.


{|cellpadding="10" cellspacing="5"
{|class="attn-box"
|-style="background-color:#f89420; color:white"
|-
|style="font-size:22pt"|'''&#9888;'''||You must run Grooper Config as an administrator to change the '''''Default Repository'''''.
|⚠
|
You must run Grooper Config as an administrator to change the '''''Default Repository'''''.
|}
|}


Line 424: Line 401:




{|cellpadding="10" cellspacing="5"
{|class="fyi-box"
|-style="background-color:#36b0a7; color:white"
|-
|style="font-size:14pt"|
|
'''FYI'''
'''FYI'''
|
|
Line 444: Line 421:
You can also change the '''''Default Repository''''' directly from Grooper Design Studio.
You can also change the '''''Default Repository''''' directly from Grooper Design Studio.


{|cellpadding="10" cellspacing="5"
{|class="attn-box"
|-style="background-color:#f89420; color:white"
|-
|style="font-size:22pt"|'''&#9888;'''||You must run Grooper Design Studio as an administrator to change the '''''Default Repository'''''.
|⚠
|
You must run Grooper Design Studio as an administrator to change the '''''Default Repository'''''.
|}
|}


Line 454: Line 433:




{|cellpadding="10" cellspacing="5"
{|class="fyi-box"
|-style="background-color:#36b0a7; color:white"
|-
|style="font-size:14pt"|
|
'''FYI'''
'''FYI'''
|
|
Line 475: Line 454:
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.
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.


{|cellpadding="10" cellspacing="5"
{|class="attn-box"
|-style="background-color:#f89420; color:white"
|-
|style="font-size:22pt"|'''&#9888;'''||Grooper Config must be run as an administrator to install and edit services.
|⚠
|
Grooper Config must be run as an administrator to install, edit, start and stop services.
|}
 
{|class="attn-box"
|-
|⚠
|
The Grooper Service User must have the "Log on as Service" permission.
|}
|}


=== Install or Edit Grooper Service ===
=== Install or Edit Grooper Service ===
Line 523: Line 512:
</tabs>
</tabs>


=== Example: Installing a Grooper Licensing Service ===
=== Example: Installing a generic multi-threaded Activity Processing Service ===
{{#lst:{{NAMESPACE}}:License Activation|grooper_licensing_service_install}}


=== Example: Installing an Activity Processing Service to Throttle Step Processing ===
{{#lst:2023:Activity Processing (Service)|multithreaded_service}}


When automating '''Export''' steps in a '''Batch Process''', you may need to execute the activity ''single threaded''. 
=== Example: Installing a Grooper Licensing Service ===
{{#lst:2023:License Activation|grooper_licensing_service_install}}


'''Unattended Activities''' in a '''Batch Process''' can be automated using an '''Activity Processing''' Grooper service.  The '''Activity Processing''' service will act like a Windows service and automatically start tasks in a '''Batch''', as processing threads in your system's resources become available.  This is one of the ways Grooper leverages your system resources for parallel processing.
== How To: License Activation ==


Imagine you're running Grooper on a machine with eight (8) processing threads.  If you have a '''Batch''' with five (5) '''Batch Folders''', and each one is on the '''Recognize''' step of the '''Batch Process''', there's no need for your system to process each '''Batch Folder''' sequentially (with each '''Batch Folder''' waiting to be processed until the one before it is finished).
License activation is different in version 2023 compared to older versions.
* You have 8 threads and 5 '''Batch Folders''' in this scenario.
* This prompted us to make a whole article on the topic of license activation.
* Each one of those threads can process one '''Batch Folder''' as a single task.
* For more information, please visit the [[2023:License Activation]] article.
* With 8 available threads, all 5 '''Batch Folders''' could be processed concurrently by 5 individual threads.
* This is ''multi-threaded'' '''Activity''' processing.
 
However, depending on which external storage system you're exporting to, you may run into errors if you attempt to run the '''Export''' activity multi-threaded.  Particularly when it comes to cloud-based systems, like SharePoint online or Box.com, their file transfer protocol expects users to upload files ''one at a time''.  If you have 5 threads all attempting to upload 5 different '''Batch Folders''' from the same machine, 4 of those '''Batch Folders''' are going to kick back to Grooper in an error state.
 
Instead, you must run the activity single-threaded, ensuring only one '''Batch Folder''' is processed at a time.  As well as automating '''Batch Processing''' activities, '''Activity Processing''' services allow you to control thread resources by assigning activities a '''Thread Pool''' and limiting the number of maximum threads available for that '''Thread Pool'''.
 
Next, we will show you how to create a single threaded '''Thread Pool''' for an '''Export''' activity, and set up an '''Activity Processing''' service that utilizes it.  This will effectively throttle your export, so '''Batch Folders''' are indeed only exported one at a time, avoiding any issues with external platforms that cannot handle multi-threaded exports.
 
<tabs style="margin:20px">
<tab name="Add a Thread Pool" style="margin:20px">
=== Add a Thread Pool ===
 
The first thing you'll need to do is add a '''Thread Pool''' object.  A '''Thread Pool''' defines the "bucket" of threads available to one step or another in a '''Batch Process'''.  In our case, this will allow us to limit the number of threads the '''Export''' step uses to a single thread.
 
{|cellpadding=10 cellspacing=5
|valign=top style="width:40%"|
To add a '''Thread Pool''':
 
# Expand the '''Infrastructure''' folder in the Node Tree.
# Right-click the '''Thread Pools''' folder.
# Select "Add" then "Thread Pool..."
# This will bring up a new window to name the '''Thread Pool'''.  Enter a name and press "OK".
#* We named ours "Export Throttle"
|
[[File:Export-thread-pools-01.png]]
|-
|valign=top|
# This will add a new '''Thread Pool''' object to the Node Tree.
# FYI:  No further object configuration is technically required at this point.
#* However, if you want the safest implementation of a single-threaded '''Thread Pool''', totally ensuring only a single '''Export''' task is processed per repository environment, you can change the '''''Concurrency Mode''''' property from ''Multiple'' to ''Single''.  With the ''Single'' mode, only a single task will run per Grooper repository.
|
[[File:Export-thread-pools-02.png]]
|}
</tab>
<tab name="Assign the Thread Pool" style="margin:20px">
=== Assign the Thread Pool ===
 
{|cellpadding=10 cellspacing=5
|valign=top style="width:40%"|
Next, we need to tell our '''Batch Process''' which step should use our new '''Thread Pool'''.
 
# By default, all '''Batch Process''' steps use the "Default" '''Thread Pool'''.
# In the '''Batch Step''' property grid, '''Thread Pools''' are assigned with the '''''Thread Pool''''' property.
|
[[File:Export-thread-pools-03.png]]
|-
|valign=top|
We want to tell the '''Export''' step of this '''Batch Process''' to use a different '''Thread Pool''', the new one we just created.
 
# Select the '''Export''' step in the '''Batch Process'''.
# Select the '''''Thread Pool''''' property.
# Using the dropdown menu, select the '''Thread Pool''' you wish to use.
#* In our case, the "Export Throttle" '''Thread Pool'''.
|
[[File:Export-thread-pools-04.png]]
|}
</tab>
<tab name="Configure an Activity Processing Service" style="margin:20px">
 
=== Configure an Activity Processing Service ===
 
On to Grooper Config!  Grooper services are installed and edited using Grooper Config.  Open Grooper Config to install a new '''Activity Processing''' service.
 
{|cellpadding="10" cellspacing="5"
|-style="background-color:#f89420; color:white"
|style="font-size:22pt"|'''&#9888;'''||Grooper Config must be run as an administrator to install and edit services.
|}
 
{|cellpadding=10 cellspacing=5
|valign=top style="width:40%"|
# To install a new service, press the "Edit Services..." button in Grooper Config.
 
 
{|cellpadding="10" cellspacing="5"
|-style="background-color:#36b0a7; color:white"
|style="font-size:14pt"|'''FYI'''||If you have multiple Grooper Repository connections, as is the case for this environment, you will need to ensure one thing first.
 
Make sure the '''''Default Repository''''' selected is the Grooper Repository with the newly added '''''Thread Pool'''''.
|}
|
[[File:Export-thread-pools-05.png]]
|-
|valign=top|
# This will bring up the "Service Manager" window.
# Press the "Install..." button.
|
[[File:Export-thread-pools-06.png]]
|-
|valign=top|
# In the "Install New Service" window, select ''Activity Processing''.
# Press the "OK" button.
|
[[File:Export-thread-pools-07.png]]
|-
|valign=top|
# This will bring up a window to edit the service.
# Select the '''''Thread Pool''''' property.
# Using the dropdown menu, select the '''Thread Pool''' you wish to use for the '''Activity Processing''' service.
|
[[File:Export-thread-pools-08.png]]
|-
|valign=top|
# The '''''Number Of Threads''''' property allows you to define how many of your system's processing threads should be utilized by the '''Activity Processing''' service.
#* In our case, we're using this '''Activity Processing Service''' to throttle our '''Export''' activity, forcing it to run single-threaded.  So, we will keep this set to ''1''.
# You must also provide user credentials to run the service.  This must be a user who has the following access rights:
#* Have the "Logon as Service" permission on the machine which the Grooper service is running.
#* Have access to the Grooper Repository's database.
#* Have access to the Grooper Repository's file store location.
# Press the "Execute" button when done.
|
[[File:Export-thread-pools-09.png]]
|-
|valign=top|
# This will add a Grooper Activity Processing service instance to the services list.
# Newly installed services, must be started.  Notice its '''''Status''''' is listed as ''Stopped''.
# Select the service, and press the "Start" button to start it.
|
[[File:Export-thread-pools-10.png]]
|-
|valign=top|
# The '''''Status''''' will change to ''Running''
# The icon next to the service name will also change from red to green.
# Your service is now installed and running.  Press the "Close" button to exit the Service Manager window.
|
[[File:Export-thread-pools-11.png]]
|
|-
|valign=top|
# Upon processing a '''Batch''' the '''Export''' step in our '''Batch Process''' will be executed by the '''Activity Processing Service'''.
#* This automates the step's execution using the "Export Throttle" '''Thread Pool''' and limits the number of threads processing '''Batch''' objects ('''Batch Folders''' in this case) to a single thread, preventing export errors to systems that cannot handle multi-threaded exports.
 
{|cellpadding="10" cellspacing="5"
|-style="background-color:#36b0a7; color:white"
|style="font-size:14pt"|'''FYI'''||You can have multiple '''Activity Processing''' services running, each with their own '''Thread Pool'''.
 
You can automate the rest of the '''Unattended Activities''' in a '''Batch Process''' by added a second '''Activity Processing''' service, assigning it the "Default" '''Thread Pool''', and assign the number of threads you want to utilize with the '''''Number of Threads''''' property.
|}
|
[[File:Export-thread-pools-12.png]]
|}
</tab>
</tabs>
 
== How To: Licensing Activation ==
 
The last step in the process of installing Grooper is license activation.  As of Grooper version 2021, license management is now done through Grooper Config.
 
Grooper can be licensed as "stand-alone" installations, where a single license is activated and registered to a local machine.  Or, you can use a licensed installation as a server to hand out licenses to client machines.  In this case, the licensed machine will run a Grooper Service, called '''Grooper Licensing'''.  The client Grooper installations will then call to the service to receive their licensing.  This way, a single product license can be used to register multiple Grooper installations.
 
Regardless, at some point you will need to activate a license on a single machine, whether that machine is a stand-alone install or hosting the '''Grooper Licensing''' service.  We will start with licensing Grooper to an individual machine.
 
{|cellpadding="10" cellspacing="5"
|-style="background-color:#36b0a7; color:white"
|style="font-size:14pt"|'''FYI'''||License activation changed somewhat in Grooper version 2021.  Prior to this version, license activation was performed in Grooper Design Studio.  As of Grooper 2021, license activation is performed in Grooper Config.
|}
 
=== Licensing Grooper to an Individual Machine ===
 
<tabs style="margin:20px">
<tab name="Obtain a Grooper License" style="margin:20px">
=== Obtain a Grooper License ===
 
First, you will need to obtain a Grooper license in order to register and activate your installation.  You may receive your license in one of two ways.
 
# As a license key.
#* This is by far the most common method.  You will receive a serial number key you can use to activate the product online (something like "a1bc2de3-12a3-a123-a1b2345c6de7")
# As a license package.
#* This is much less common.  A license package is a ".lic" file you can use to activate the product.  This is typically used for "locked down" environments where activating online is not an option.
 
{|cellpadding="10" cellspacing="5"
|-style="background-color:#f89420; color:white"
|style="font-size:22pt"|'''&#9888;'''||If you are planning on installing a '''Grooper Licensing''' service to hand out licenses to other workstations, the machine activating the license '''''must''''' be the one to install the service.  If you try to install the '''Grooper Licensing''' service on a product that has '''''not''''' activated a license as described in the next steps, it will fail to distribute licensing to other machines.
|}
</tab>
<tab name="Open Grooper Config" style="margin:20px">
 
=== Open Grooper Config ===
 
{|cellpadding=10 cellspacing=5
|valign=top style="width:40%"|
License activation and management is performed in the Grooper Config application.  Open Grooper Config and you will immediately see two things relating to licensing.
 
# The '''''License''''' property will inform you if the product has activated and registered a license.  In this case, we have not registered a license yet.  So, the property is blank indicating that no license was found.
# The "Activate License..." button.  This button will navigate us to a license activation window.
 
{|cellpadding="10" cellspacing="5"
|-style="background-color:#36b0a7; color:white"
|style="font-size:14pt"|'''FYI'''||License activation changed somewhat in Grooper version 2021.  Prior to this version, license activation was performed in Grooper Design Studio.  As of Grooper 2021, license activation is performed in Grooper Config.
|}
|
[[File:Grooper-config-license-activation-1.png]]
|}
</tab>
<tab name="Activate the License:  Online Activation" style="margin:20px">
=== Activate the License:  Online Activation ===
 
This is the most common license activation method, activating online with a serial number key.
 
{|cellpadding=10 cellspacing=5
|valign=top style="width:40%"|
# Press the "Activate License..." button.
# The "Activate License" window will appear.
# The default '''''Activation Method''''' is set to ''Online''.  Keep this set to ''Online''
# Select the '''''Serial Number''''' property.
# Enter your license serial number key.
# Press the execute button to activate your license.
|
[[File:Grooper-config-license-activation-2.png]]
|-
|valign=top|
# Upon successful license activation, you will see the following notification.
# Press the "OK" button to continue.
|
[[File:Grooper-config-license-activation-4.png]]
|}
</tab>
<tab name="Activate the License: Offline Activation" style="margin:20px">
=== Offline License Activation ===
 
''Offline'' activation allows you to license your machine using a .lic licensing file.  This is a less common activation method.  This is more appropriate for scenarios where your machine cannot access the internet due to security restrictions.
 
{|cellpadding=10 cellspacing=5
|valign=top style="width:40%"|
# Press the "Activate License..." button.
# The "Activate License" window will appear.
# Change the '''''Activation Method''''' property from ''Online'' to ''Offline''
# Select the '''''Serial Number''''' property.
# Enter your license serial number key.
# This will populate a URL in the '''''Download URL''''' property.  Copy this URL.
|
[[File:Grooper-config-license-activation-9.png]]
|-
|valign=top|
# Get to a computer with internet access.  In a web browser, paste the copied URL.
# This will download a .lic file.  You will need to copy this file to the machine you're attempting to license Grooper.
|
[[File:Grooper-config-grooper-licensing-10.png]]
|-
|valign=top|
# Once saved to the machine with Grooper installed, find the .lic file using the '''''File Path''''' property.
# Press the execute button to activate your license.
|
[[File:Grooper-config-grooper-licensing-11.png]]
|-
|valign=top|
# Upon successful license activation, you will see the following notification.
# Press the "OK" button to continue.
|
[[File:Grooper-config-license-activation-4.png]]
|}
 
</tab>
<tab name="Verify Your License" style="margin:20px">
=== Verify Your License ===
{|cellpadding=10 cellspacing=5
|valign=top style="width:40%"|
After activating your license, you will see the '''''License''''' property change from being blank to ''Licensed to...'' followed by your company's name (or who the license is registered to).
|
[[File:Grooper-config-license-activation-5.png]]
|-
|valign=top|
You can also view more specific information about your license from Grooper Config.
 
# Expand the '''''License''''' property.
# This expands the property grid, displaying basic information about your license: the serial number used to activate Grooper, the licensee name, its expiration, the last time the license was reset, and more.
 
You can expand the '''''Licenses''''' property to view even more specific information about your license.
|
[[File:Grooper-config-license-activation-6a.png]]
|-
|valign=top|
# Expand the '''''Licenses''''' property.
# This will expand the property grid, displaying the specifics of your product license, including licensed OCR engines, how many concurrent connections to Grooper Design Studio can be made, volume licensing, and worker thread licensing.
|
[[File:Grooper-config-license-activation-7.png]]
|}
 
</tab>
</tabs>

Latest revision as of 14:43, 21 November 2024

This article is about an older version of Grooper.

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

2025202320212.72

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. Setting up and configuring Grooper Services, such as a Grooper Licensing service for a server to hand out Grooper licenses to client workstations.
  3. Installing product licensing

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.

  1. Grooper Repository Connections
  2. Grooper Services
  3. 2023:License Activation (for "self hosted" licensing installs)
⚠

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

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

  1. A database connection
  2. 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.

  1. Right-click the folder
  2. Select the "Properties" option.

  1. In the following window, press the "Sharing" tab.
  2. 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
  3. 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:

  1. A database connection
  2. A file store connection

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

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

  1. Press the "Download SQL Express..." button.
  2. The installer files will download automatically. You will see this dialog box appear upon successful download.
  3. Press "Ok" to continue.

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

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

  1. 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.
  2. Press "Ok" to continue.

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

  1. Upon successful installation, the following dialog box will appear.
  2. 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.

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

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

  1. Press the "Add" button to add a new connection.

Remember, a Grooper Repository is two things:

  1. A database connection
  2. A file store connection

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

  1. 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.
  2. 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.
  3. Press the "Test Connection" button.
  4. 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.
  5. 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.

  1. Upon creating the database, you will get a message letting you know the database has not been initialized.
  2. Also note the "Status" of this Repository Connection has changed from Unavailable to NotInitialized.
  3. Press "Ok" to continue.
  4. Press the "Initialize..." button.

Remember, a Grooper Repository is two things:

  1. A database connection
  2. A file store connection

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

  1. Select the Storage Path property and enter the file path for the file store's folder.
  2. 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.

  1. Upon successful initialization, you will receive this confirmation window.
  2. Press the "Ok" button to continue.
  3. 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.
  4. Press the "Ok" button to finish.

This will return you to the main Grooper Config window.

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

  1. Press the "Add" button to add a new connection.

Configure the Connection

  1. Select the Server property and enter the server's name running the SQL environment.
  2. Select the Database property and enter the Grooper Repository's database name.
  3. Press the "Test Connection" button.
  4. 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.
  5. 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.

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

This will return you to the main Grooper Config window.

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

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.

  1. Select the Default Repository property.
  2. Press the drop down menu button to reveal a list of all Grooper Repository connections.
  3. Select the Grooper Repository you wish to be the Default Repository.

  1. You will see the selected Grooper Repository listed as the Default Repository.
  2. 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.

  1. Select "File" from the menu bar.
  2. Select "Change Repository".
  3. 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.

⚠

The Grooper Service User must have the "Log on as Service" permission.


Install or Edit Grooper Service

Installing or Editing a Grooper Service

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

  1. To install a new Grooper Service, press the "Install..." button.
  2. 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.

  1. To stop a Grooper Service, select the service from the list, and press the "Stop" button.
  2. 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.

  1. Select the stopped Gropper Service.
  2. Press the "Uninstall" button to uninstall it.
  3. On the following dialog box, press "Yes" to confirm the uninstallation.

Example: Installing a generic multi-threaded Activity Processing Service

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.

  2. 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.
  3. 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.
  4. 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.
  5. Press the "Execute" button when finished.


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

  2. Select the service you wish to start.
  3. Press the "Start" button"
  4. Upon successfully starting, you will see the Status change from "Stopped" to "Running".


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.

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

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

  1. Press the "Install..." button.
  2. This will bring up a window to install a Grooper Service.
  3. Select Grooper Licensing
  4. 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.

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

  1. Upon pressing the "Execute" button, a new Grooper Licensing server is added to the list of services.
  2. 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.

  1. Select the service you wish to start.
  2. Press the "Start" button.

  1. Upon successfully starting the service, you will see the Status change to Running
  2. 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.


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 2023:License Activation article.
Retrieved from "https://wiki.grooper.com/index.php?title=2023:Grooper_Config_(Application)&oldid=26800"