2023:Activity Processing (Service)

This article is about an older version of Grooper. Information may be out of date and UI elements may have changed.
2025	2024	2023	2022	2.90

Activity Processing Services process unattended activities.

Activity Processing is a Grooper Service that executes Activities assigned to edit_document Batch Process Steps in a settings Batch Process. This allows Grooper to automate Batch Steps that do not require a human operator.

When configuring an Activity Processing service, a Processing Queue may or may not be specified.

• When unspecified, the service will assign work using the "default" Processing Queue. The Activity Processing service will pick up tasks for any Batch Process Steps that do not have an assigned Processing Queue.
• When specified, only the Activity Processing service will only process tasks for Batch Process steps with that Processing Queue assigned.
  • Be aware, while an Activity Processing service can only be configured to point to a single Processing Queue, multiple Activity Processing services may be added to the Grooper service list (each referencing their own Processing Queues).

⚠

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

About

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.

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

• You have 8 threads and 5 Batch Folders in this scenario.
• Each one of those threads can process one Batch Folder as a single task.
• With 8 available threads, all 5 Batch Folders could be processed concurrently by 5 individual threads.
• This is multi-threaded Activity processing.

You could then set up an Activity Processing service to process all Unattended Activity steps in a Batch Process with the maximum allowable processing threads available.

How To

Install an Activity Processing service without a Processing Queue

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

Install an Activity Processing service with a Processing Queue

Processing Queues allow Activity Processing services to divide CPU threads amongst different steps in a Batch Process. This is mechanism that allows you to control how many threads are utilized by specified steps.

Commonly, a Processing Queue is created and implemented to throttle certain Activities, such as Recognize or Export, restricting the maximum number of threads that can be used to process those steps (thus freeing up compute for other Activities). In the example below, we describe how to implement a single-threaded Activity Processing service that executes Export steps using a Processing Queue.

When automating Export steps in a Batch Process, you may need to execute the activity single threaded.

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.

• This may be due to a storage platform limiting the number of concurrent connections to the repository.
  • For example, licensing limitations for the platform may restrict how many connections can be made to the repository at a time (as is the case for ApplicationXtender).
• This may be a self-imposed throttle to avoid network/latency related errors when uploading to cloud based platforms (such as Box.com or Microsoft SharePoint).
• This may otherwise be required or preferable for platforms whose 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 in this scenario.

For scenarios like these, it is preferable to run the Export 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 Processing Queue and limiting the number of maximum threads available for that Processing Queue.

Next, we will show you how to create a single threaded Processing Queue 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.

1. Add a Processing Queue

The first thing you'll need to do is add a Processing Queue object. A Processing Queue 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.

To add a Processing Queue:

1. Right-click the Queues folder in the Node Tree.
2. Select "Add".
3. Select "Processing Queue"
4. This will bring up a new window to name the Processing Queue. Enter a name.
   • We named ours "Export Throttle"
5. Select "Execute."

1. This will add a new Processing Queue object to the Node Tree.
2. FYI: No further object configuration is technically required at this point.
   • However, if you want the safest implementation of a single-threaded Processing Queue, 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.

2. Assign the Processing Queue

Next, we need to tell our Batch Process which step should use our new Processing Queue.

1. By default, all Batch Process steps use the "Default" Processing Queue.
2. In the Batch Step property grid, Processing Queues are assigned with the Processing Queue property.

We want to tell the Export step of this Batch Process to use a different Processing Queue, the new one we just created.

1. Select the Export step in the Batch Process.
2. Select the Queue Name property.
3. Using the dropdown menu, select the Processing Queue you wish to use.
   • In our case, the "Export Throttle" Processing Queue.

|

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

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

1. To install a new service, press the "Edit Services..." button in Grooper Config.

1. This will bring up the "Service Manager" window.
2. Press the "Install..." button.

1. In the "Install New Service" window, select Activity Processing.
2. Press the "OK" button.

⚠

If you have multiple Grooper Repository connections, make sure you're installing the Activity Processing service for the intended repository. The Repository property always defaults to the "Default Repository" set in Grooper Config. If you want to install services for a different Grooper Repository, use the Repository dropdown to select it.

1. This will bring up a window to edit the service.
2. Select the Queue Name property.
3. Using the dropdown menu, select the Processing Queue you wish to use for the Activity Processing service.

1. 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.
2. 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.
3. Press the "Execute" button when done.

1. This will add a Grooper Activity Processing service instance to the services list.
2. Newly installed services, must be started. Notice its Status is listed as Stopped.
3. Select the service, and press the "Start" button to start it.

1. The Status will change to Running
2. The icon next to the service name will also change from red to green.
3. Your service is now installed and running. Press the "Close" button to exit the Service Manager window.

1. 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" Processing Queue 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.

FYI

You can have multiple Activity Processing services running, each with their own Processing Queue. You can automate the rest of the "Code Activities" in a Batch Process by added a second Activity Processing service, assigning it the "Default" Processing Queue, and assign the number of threads you want to utilize with the Number of Threads property.

Install an Activity Processing service for the Render activity

An Activity Processing service is required to run the Render activity. This Activity Processing service must use a specially configured Processing Queue.

• The Processing Queue assigned to any Render step must have its Concurrency Mode set to PerMachine.

The following tutorial will instruct you how to set up a Processing Queue and Activity Processing service for a Render step in a Batch Process.

1. Add a new Processing Queue

In order to use the Render activity in a Batch Process, you will need to create a new Processing Queue.

1. Processing Queues are created in the Queues folder.
2. Right click the Queues folder and select "Add" then "Processing Queue..."
3. Name the Processing Queue whatever you'd like. Press "Execute" to finish naming the Processing Queue and create it.
   • Since we are configuring an Activity Processing Service to run the Render activity, it makes sense to name this Processing Queue "Render".

4. This creates a new Processing Queue object with the given name in the Node Tree.
5. Change the Concurrency Mode property from Multiple to PerMachine
   • You may see a popup window saying "You must run Grooper as an Administrator to modify services." This is letting you know you will need to run Grooper Config as an administrator to create and edit the Activity Processing service that will use this Processing Queue. However, you must still create the Processing Queue from the Design page. Just press the "OK" button to get rid of this window.
6. Press the "Save" button when finished.

⚠	Render must run using a PerMachine Concurrency Mode

2. Set up the Activity Processing service

Next, you must Install an Activity Processing Service using the Tread Pool created in the previous step. Grooper Services are installed through the Grooper Config application. You must run Grooper Config as an administrator to install and edit services.

1. Locate the Grooper Config application (seen here using the Windows Start menu).
2. Right click Grooper Config and select "Run as administrator" to run the program with the administrator's rights.

⚠	You must run Grooper Config as an administrator to install or edit a Service.

3. In Grooper Config, click "Edit Services".

4. Press the "Install..." button to add a new service.
5. In the "Install New Service" window, select "Activity Processing"
6. Press the "OK" button. This will take you to the configuration screen for this service.

3. Configure the Activity Processing service

Next, you just need to configure the service's settings. In this case, we will just set the Queue Name property to the Processing Queue created in Step 1.

1. Select the Queue Name property. Using the dropdown menu, select the Processing Queue created in Step 1 (Here, named "Render").

2. Ensure the Number of Threads property remains at 1.
   • The Render activity must run single-threaded.
3. Enter the User Name and Password credentials for the administrator's account if not already present.
4. Press the "Execute" button when finished.

⚠

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

|

5. On the following screen, press the "Start" button to run the Activity Processing Service.

4. Set the Processing Queue in your Batch Process Step

Last, the Render step of your Batch Process must be told which Processing Queue to use.

1. Select the Render step of your Batch Process.
2. In the "Step Properties" panel, select the Queue Name property. Using the dropdown menu, select the Processing Queue created in Step 1 (Here, named "Render").

Addressing "ghost services" - Deleting services from Windows

⚠

Very rarely, a Grooper service will not uninstall properly when you uninstall a Grooper service service. Or, a user may delete a Grooper Repository connection or purge a Grooper Repository without uninstalling services first. This can make it appear as though a duplicate or "ghost" Windows service is installed without being listed in GCC (or Grooper Config before version 2024). If this does occur, you will need to manually delete the service. If you know the name of the service instance (something like Grooper.ServiceTypeName.##) you need to delete, you can use the following command lines to stop the service (if necessary) and manually delete it. SC STOP Grooper.ServiceTypeName.## SC DELETE Grooper.ServiceTypeName.## OR You can delete the service from the Windows Registry Editor, using the following steps: Open the Registry Editor (regedit.exe) Navigate to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services. Select the key of the service you want to delete. Grooper services will always be named something like Grooper.ServiceTypeName.## From the "Edit" menu select "Delete. You will be prompted "Are you sure you want to delete this Key?". Click Yes. Exit the Registry Editor.