Scripting Setup

From Grooper Wiki
Revision as of 09:55, 2 May 2025 by Dgreenwood (talk | contribs) (Created page with "{{AutoVersion}} <blockquote>Before you start creating custom Grooper scripts, there's a few things you need to do.</blockquote> == About == Grooper's core capabilities can be expanded with custom scripts written in C# or Visual Basic for the .NET platform. With scripts you can: * Create a Grooper {{ObjectLibraryIcon}} '''Object Library''' to create custom Activities, Commands, Services, CMIS Connection Bindings, and other Grooper objects. * Create {{BatchProcessIco...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

This article is about the current version of Grooper.

Note that some content may still need to be updated.

2025 2023.1

Before you start creating custom Grooper scripts, there's a few things you need to do.

About

Grooper's core capabilities can be expanded with custom scripts written in C# or Visual Basic for the .NET platform. With scripts you can:

  • Create a Grooper extension Object Library to create custom Activities, Commands, Services, CMIS Connection Bindings, and other Grooper objects.
  • Create settings Batch Process scripts to alter how Batch Process Steps are executed.
  • This functionality has largely been replaced by the "Should Submit" and "Next Step" expressions in a Batch Process.
  • Create data_table Data Model scripts to perform custom validation events or data normalization logic.
  • This functionality has largely been replaced by Grooper's Data Rules.
  • Create pin Data Type scripts to perform custom extraction validation and manipulation.
  • This functionality too has largely been replaced by Grooper's Data Rules. Most users now prefer to normalize extraction results after it has been extracted with Data Rules and the Apply Rules activity.


Before you get started coding, there are a few requirements:

  1. You must have Visual Studio 2022 installed on your machine.
  2. This installation must have the ASP.NET and web development workload installed.
  3. You must install the Grooper SDK Visual Studio extension.
    • This is required to debug your scripts in a web browser.
  4. You must be on a machine where Grooper and the Grooper Web Client applications are installed. This means either:
    • Visual Studio must be installed on the Grooper web server and you do all your scripting from there.
    • Or (more commonly) you will need to connect to the Grooper Repository and perform some additional setup (See "#Remote web scripting setup" below)

Setting up a scripting environment

Step 1: Decide where you're going to script

The Grooper web server is the server hosting the Grooper website. Most commonly, there is one Grooper web server connected to a Grooper Repository. That way, all users can access the Grooper Repository with a single URL, instead of installing Grooper on their own machines (Yes, I just explained the advantages of web-based applications to you).

In order to debug your scripts, you must be working in Visual Studio on a machine where Grooper is installed and the Grooper Web Client is installed and IIS is hosting the Grooper website.

You have two options. You can script:

  • Locally - On the Grooper web server
  • Remotely - On any other machine that can connect to the Grooper Repository (with some additional setup required)


If you're scripting locally, there is less setup involved. But this is generally not preferred.

  • There are good reasons you won't want to install Visual Studio and script on the Grooper web server.
  • Example: If you ever need to recycle the Grooper app pool during your debugging process or after compiling a script, you want that to affect only you and not every other user connected to the Grooper Repository.
  • Example: Multiple users attempting to script at the same time on the web server may cause issues.

If you're scripting remotely, there is some more setup. But this is generally preferred.

  • To script remotely, you will spin up a local Grooper web server on your own machine, connect to the Grooper Repository and debug using the localhost URL.
  • We will walk you through these steps in Step 3 of this tutorial. But in all circumstances, Visual Studio must be installed and configured properly first.

Step 2: Configure Visual Studio and install the Grooper SDK extension

After deciding if you're scripting locally or remotely, you will need to set up Visual Studio on whatever machine you're going to use. Microsoft Visual Studio 2022 is the supported version for developing with Grooper 2025.

  1. Install Visual Studio 2022 on your machine if you have not done so already.
  2. Be sure your Visual Studio install includes the "ASP.NET and web development" workload. Install it if it does not.

Next, we will install the Grooper SDK extension for Visual Studio. This is required to debug Grooper scripts using a browser target.

  1. Launch Visual Studio (as an administrator).
  2. For now, under "Get Started" choose "Continue without code".
  3. Click the "Extensions" menu.
  4. Choose "Manage Extensions".
  5. Search for "Grooper"
  6. Select "GrooperSDK" and click "Download"
  7. After the extension downloads, close Visual Studio to begin modifications.
  8. After closing Visual Studio, the VSIX installer launches. Click "Modify" to install the GrooperSDK extension.
  9. After installation is finished, click "Close".
  10. Re-launch Visual Studio (as an administrator).
  11. Automatic updates?

Next, set a debug target page. This will ensure the default page opened in your browser will be the Grooper "Home" page or whichever page you prefer.

  1. In Visual Studio, click the "Tools" menu.
  2. Choose "Options".
  3. In the Options menu, select and expand "Grooper".
  4. Select "Debugging".
  5. Using the "Start Page" property, select a debug target. This can be the Home page or any of the other main navigation pages in the Grooper UI.


If you are scripting locally, you can start scripting. You may continue to Step 4: Create a script and local project files in Grooper.

If you are scripting locally, read on to learn how to set up your remote scripting machine.

Step 3: Set up a remote scripting machine (if scripting remotely)

Step 4: Create a script and local project files in Grooper

Step 5: Edit the project in Visual Studio

Step 6: Debug the project in a browser

Step 7: Compile the script and test it in Grooper

Previous instructions

Understanding the Environment

Before we dive into how things are setup, let's take a look at what parts make up the demonstration environment. Variables in your environment will obviously be slightly different, but this is a basic setup that should work as a reasonable template.

Grooper Server

This is the main server that is hosting everything Grooper, and as such will be referred to as "Grooper Server". The following components are installed on this machine.

  • Grooper Software
    • Grooper software is installed on this computer normally. For more information on installing Grooper please visit the Install and Setup article.
  • Grooper Web Server
    • The Grooper Web Client is installed on this "Grooper Server" (along with the requisite installation and appropriate configuration of IIS) to allow remote computers to access the Grooper environment remotely without having to have Grooper installed on their machines.
  • Grooper Repository
    • The infrastructure that establishes a repository of information that the Grooper application points to consists of the following pieces that are also installed on this "Grooper Server":
      • Grooper Filestore
        • Files associated with objects in Grooper reside here. This is a file directory located on this "Grooper Server"
      • SQL Server
        • Objects and their configurations are stored in tables in a SQL database that make the backbone of a Grooper repository.

Remote Scripting Computer

This is a generic workstation used by a developer wanting to do scripting for Grooper that is on the same network the "Grooper Server" is on, but it is not itself the "Grooper Server". The following Components are installed on this machine.

  • Grooper Software
    • This is installed on the computer because of the need to access Grooper code for the developer when compiling. SQL server is not installed on this machine, neither is the Filestore for Grooper so it is pointed at the remote repository (the repository hosted on the "Grooper Server") via Grooper Config.
  • Grooper Web Client
    • The Grooper Web Client is installed on the developer's machine so that they can have a debug target when creating their scripts. This is not the main webpage users will interact with to access Grooper. IIS is installed on this machine to facilitate the appropriate installation of the Grooper Web Client, but IIS Express (which is side-loaded when the Grooper SDK is added to Visual Studio) will actually be leveraged upon testing and debugging of scripts.
  • Visual Studio - with Grooper SDK
    • Visual Studio 2019 is the supported version for developing with Grooper 2023.1. From Visual Studio you can download and install the Grooper SDK.

Understanding Both

We have the "Grooper Server" and we have the "Remote Scripting Computer" and their requisite components on each. As stated, the Grooper Software and the Grooper Web Client are installed on the "Remote Scripting Computer" but the Grooper Repository is established on the "Grooper Server". The "Remote Scripting Computer" is simply referencing the repository as it exists on the "Grooper Server".

How To

With an understanding of what is established in this defacto environment we will now walk through the setup of creating, compiling, and sending a script to Grooper from a remote computer.

Establishing a Connection to the "Grooper Server" from the "Remote Scripting Computer"

As discussed, the "Remote Scripting Computer" has Grooper 2023.1, the Grooper Web Client, and Visual Studio 2019 installed, but itself is not hosting a Grooper repository. We will configure this machine to point at the Grooper repository that is being hosed by the "Grooper Server".

Follow the instructions in the screenshots below.

  • Because Grooper Config has not been run on this computer before, it will need to create its requisite .cfg file that stores its configuration settings.


  • With Grooper Config properly initialized (the requisite .cfg file was made), select the "Repositories" property and click the ellipsis button to configure a connection to a Grooper repo.


  1. In the "Repositories" window that appears, click the "Add" button.
  2. A connection entry ill be added to the list.
  3. Enter connection info to the "Grooper Server" including "Server Name" and "Database Name"
  4. Enter "Authentication" info. In this case the active Windows user has access to the database, so the properties are left blank.
  5. Test the connection to verify settings.
  6. Click "OK" in the "Information" box.
  7. Click "OK" once the connection is established.


  1. With a connection established the "Repositories" property will list the connection.
  2. With only one connection made it will be the default, otherwise verify your "Default Repository"
  3. Click "Save" once settings are confirmed

Installing and Configuring the Grooper SDK

We now have the ability to connect to the Grooper Repository hosted by the "Grooper Server", but before we do any work in Grooper, let's jump into Visual Studio to install and configure the Grooper SDK.

Follow the instructions in the screenshots below.

  • Launch Visual Studio as an administrator


  • For now, continue without code


  1. Click the "Extensions" menu
  2. Choose "Manage Extensions"


  1. Search for "Grooper"
  2. Select "GrooperSDK" and click "Download"


  • With the extension downloaded you will need to close Visual Studio in order for the install to take place


  • Once Visual Studio closes the VSIX installer will launch. Click modify to begin the installation of the extension.


  • Once the installation completes you can close the VSIX installer.


  1. Re-launch Visual Studio as an administrator and in the "Extensions" menu you will notice a "Grooper" sub-menu. We'll worry about this later.
  2. For now click "Manage Extensions"

Turn Off Automatic Updates

The default setting for the Grooper SDK as an extension in Visual Studio is to automatically update. It is suggested by the development team to disable this option.

The Grooper SDK will not get updated frequently, but if it does, you do not want to automatically download the update as it would necessistate installing a new sub-version of Grooper. If your environment is stable it is best practice to not introduce unknown variables that may interfere with your setup.

  1. In the "Manage Extensions" window of Visual Studio, click the "Installed" section.
  2. Click the "GrooperSDK"
  3. Uncheck the "Automatically update this extension" setting.

Set a Debug Target Page

When debugging and testing your scripts the default page that will open in your browser will be the Grooper "Home" page. If you want to set this to a different page to save time, you can change the debug target to whichever page you prefer.

  1. Click the "Tools" menu in Visual Studio
  2. Click "Options" from the list


  1. Select "Grooper" from the list.
  2. Select a "Debug Target" from the drop-down list of the "Start Page" property.

Creating an Object Library and Local Project Files

There are five objects in Grooper where you can apply a custom script:

  • Batch Process
  • Data Model
  • Data Table
  • Data Type
  • Object Library

In the following example an Object Library will be created and a C# script applied to it.

Follow the instructions in the screenshots below.

  • In your web browser (Chrome, Firefox, or MS Edge) put in the url:
    localhost/grooper
    Do not use the: (hostname)/grooper normal convention.


  1. On the "Design" page of Grooper, right-click on a Project
  2. Choose "Add" from the menu
  3. Select "Object Library" from the sub-menu
  4. Type a name for the object
  5. Click "Execute" to create the object

Create Custom Script Button

Because we are using the path localhost/grooper we are using the Grooper website that is hosted on this machine, which is a local site to this "Remote Scripting Computer". However, because the Grooper Repository connection is to the "Grooper Server", this local website is leveraging a Grooper Repository that is remotely hosted.
The "Create a custom script" button is only available to us because we are on a website that is local to this machine. If you use the standard https://(hostname)/grooper your browser is actually connected to a website that is remote, and as a result the "Create a custom script" button would be grayed out.

  1. On the "Design" page of Grooper, select the newly created Object Library
  2. Click on the "Scripting" tab
  3. Click the "Create a custom script" button
  4. Select "C#" from the drop-down


  • You will see the .sln and other associated files related to this project are made

Script Files Created in the Grooper Filestore

While we are accessing the Grooper Repository that lives on the "Grooper Server" via a local website, the files for the custom solution are still made in the Grooper Filestore that is part of the remote Grooper Repository on the "Grooper Server". Historically when you would edit scripts in Grooper it would be on the files in the Grooper Filestore of that repository. We don't want to do this however, so we will create a local copy of the created files that will live on this "Remote Scripting Computer" in the next steps.

  1. On the "Design" page of Grooper, with the newly created Object Library selected, if you go to the "Advanced" tab...
  2. ...you will see the script project files that are created for the object are stored in the "Grooper Filestore" for this repository.


  1. Back on the "Scripting" tab...
  2. Click the "Download script to a local folder" button
  3. In the "Working Directory" dialog box that opens, notice the default directory. You can change it to whatever you want. Grooper will remember the path you set moving forward.
  4. Click "OK" to continue.
  5. The "Edit Script" dialog box will open with a prompt. Notice a sub-folder is made named after the object the solution lives on.
  6. Click "OK" to continue

Local Solution Files Copied

Now that the solution files of the custom script have been copied from the Grooper Filestore of the "Grooper Server", we can work on this solution locally and not worry about a connection to the "Grooper Server".

  1. If you open a File Explorer window and navigate to the path created...
  2. ...you will see the solution files have been copied from the "Grooper Filestore" from the "Grooper Server" to a local directory on your machine.

Editing the Custom Script Solution

In this next section we will add some code to our project.

Feel free to use the following code for your purposes.

using Grooper;
using Grooper.Core;
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Linq;
using System.Runtime.Serialization;
using System.Text;
using System.Threading.Tasks;

namespace SetDescription
{
    [DataContract, IconResource("Tap"), DisplayName("SetDescription")]
    public class ObjectCommand : ObjectCommand<GrooperNode>
    {
        [DataMember, Viewable, Required]
        public string Description { get; set; }

        protected override void Execute(GrooperNode Item)
        {
            Item.Description = Description;
        }
    }
}

The following image is used as an "IconResource" which you can choose to leverage to match what is being used. Be sure to rename it to "Tap.png" so the name matches the code. THIS IS CASE SENSITIVE.

Follow the instructions in the screenshots below.

  • Launch Visual Studio as an administrator and choose "Open a project or solution"


  1. Navigate to where you solution file is saved
  2. Select the file and click "Open"


  1. Right-click on the solution in the "Project Explorer"
  2. Choose "Add"
  3. Select "New Item..."


  1. Select the "C# Class" item
  2. Click the "Add" button (you can name the class before clicking "Add" if you choose)


  1. With the newly created class selected in the "Project Explorer"...
  2. ...feel free to set the name of the class (if you haven't already)
  3. Replace the existing text with the supplied sample code (or your own code if you're following along without the sample)
  4. Notice this portion of the script that has an "IconResource" named "Tap". We will address this next.

Adding an Icon Resource

  1. Right-click the solution in the "Project Explorer"
  2. Select "Properties" from the menu


  1. From the solution properties...
  2. ...select the "Resources" menu
  3. Click the "This project does not contain a default resource file. Click here to create one. prompt to create the requisite resource file.


  1. Click the "Add Resource" drop-down
  2. Select "Add Existing File..."


  1. In the File Explorer that opens, select the supplied image or select one of your choosing
  2. Click the "Open" button


  1. With the image file added...
  2. ...close the project properties
  3. Click "Save" when prompted


  1. From the "File" menu...
  2. ...be sure to "Save All" changes

Testing and Debugging

With the script added, let's now test to see it working and see how we can set a break point for debugging purposes.

Follow the instructions in the screenshots below.

  • Click the "Start" button to test


  • An instance of IISExpress will launch and automatically minimize itself


  • In the browser that launches (hopefully your default is set to a compatible browser like Chrome, Firefox, or MS Edge), from the "Home" page, go to the "Design" page


  • Right-click on a node and you will see that our custom object command is working as intended. Select the "SetDescription..." custom command


  1. In the "Set Description" dialog box, you can set the Description property...
  2. ...and click "Execute" when finished


  • On the node you ran the command from, you can see that a the Description property is successfully set. When done, feel free to close the browser.

Setting a Break Point for Debugging Purposes

  • Back in the solution, set a break point on line 21 then re-run the script


  1. Back on the "Design" page of Grooper, use the custom object command...
  2. ...type something for the Description
  3. ...click "Execute" and...


  2. ...because of the break point you will be back in Visual Studio where you could make edits


  1. Clear the break point
  2. Then continue running the script


  • The script will finish executing and the description will be set

Saving to Grooper and Compiling

The Grooper SDK extension has three commands:

  • Save - This will take the files of the saved solution and "push" them to the original object in Grooper, overwriting the script files on the object. You will need to go to the object in Grooper and run the compile command if you use this option. After compiling you will need to close your web browser, recycle the GrooperAppPool on the "Grooper Server", then reconnect to your Grooper site.
  • Save and Compile - This will do what the Save command will do, but after "pushing" the files over it will immediately compile the script and create the associated .DLL and .XML descriptor file. After compiling you will need to close your web browser, recycle the GrooperAppPool on the "Grooper Server", then reconnect to your Grooper site.
  • Get Latest - This command syncs with the published version of the code and updates your local code/binaries to the most up-to-date.



Follow the instructions in the screenshots below.

  1. Click the "Extensions" menu
  2. In the "Grooper" menu choose "Save"
  3. Click "Yes" in the confirmation prompt
  4. Click "OK" in the following window. Notice the prompt about needing to compile and restart processes.


  • Navigate to your Grooper site. You can use the standard (hostname)/grooper path.


  1. Select the Object Library
  2. Go to the "Scripting" tab
  3. Click the "Compile Script" button
  4. In the "Compile Script" dialog box you should recieve a message informing of a successful compile
  5. Click "OK" to close the window


  • With a successful compile you should now see the compiled .dll and its descriptor .xml file


  1. Go to the "Grooper Server" and launch "IIS Manager"
  2. Click on the "Application Pools"
  3. Right-click the "GrooperAppPool" and choose "Recycle..." from the drop-down menu


  • With the "GrooperAppPool" recycled, go back to your Grooper site and notice the custom object command is now usable

Disabling a Compiled Script

  1. If you want to disable a compiled script, select the object library
  2. Go to the "Scripting" tab
  3. Click the "Disable Script" button


  • This will remove the compiled .dll and it's .xml descriptor file


  1. Once again, go to the "Grooper Server" and launch "IIS Manager"
  2. Click the "Application Pools"
  3. Right-click the "GrooperAppPool" and choose "Recycle..." from the drop-down menu


  1. With the script disabled and the "GrooperAppPool" reset, we can choose to delete the Object Library", or...
  2. ...go back to it's "Scripting" tab...
  3. ...and click the trash can icon to delete all files related to the script and start over.

Thing you can't do in web client scripts

If you're coming from older versions of Grooper that use a Windows client (thick client), you will find there are some things you cannot accomplish with custom scripts in the Grooper web client.

It's important to understand the thick client and web client are essentially two different user interfaces for Grooper. While the functionality is similar, there are necessarily differences in how Grooper is programed to function when installed and running using a machine's operating system versus how Grooper is programed to function using web calls.

Due to this, there are certain things that scripts may have been able to accomplish in the thick client that they cannot in the web client or will need to be rewritten with web functionality in mind.

Field entry and exit in Data Model scripts

The web client does not register an event for when a Data Field is entered or when it is exited in a Review step's Data Viewer. Therefore, you cannot script events based around field entry or exit in the web client.

Windows Dialog Box

Windows dialog boxes are not supported through Grooper in a web browser.

Retrieved from "https://wiki.grooper.com/index.php?title=Scripting_Setup&oldid=28232"