Scripting Setup

From Grooper Wiki

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

Install Visual Studio 2022

  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.


Install the Grooper SDK extension

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

Click here for an interactive walkthrough.

  1. Launch Visual Studio (as an administrator).
  2. Continue to the application.
    • Under "Get Started" you can choose "Continue without code".
  3. Open the "Extensions" menu.
  4. Choose "Manage Extensions".
  5. Search for "Grooper"
  6. Select "GrooperSDK" and click "Download"
  7. Visual Studio will inform you the changes have been scheduled. Close Visual Studio to finish installing Grooper SDK.
  8. After closing Visual Studio, the VSIX installer launches. Click "Modify" to install the Grooper SDK extension.
  9. After installation is finished, click "Close".
  10. Re-launch Visual Studio (as an administrator).
  11. After Grooper SDK is installed, you'll see "Grooper" in the Extensions menu.
    • The Grooper developers recommend turning off "automatic updates" for the Grooper SDK extension. This is not a strict requirement (as of Grooper 2025), but will give you more control over if and when Grooper SDK updates are installed for your environment.

Set the debug start page (Optional)

By default, the debug target for Grooper is the "Home" page. If you'd like, you can set this to whichever page you prefer.

[Click here for an interactive walkthrough.]

  1. In Visual Studio, click the "Tools" menu.
  2. Choose "Options".
  3. In the Options menu, search for and select "Grooper".
  4. Select "Debugging".
  5. Use the "Start Page" property to set the default Grooper page in a debug session. This can be any of the main navigation pages in the Grooper UI.


If you are scripting locally on the Grooper web server, you can start scripting. You may continue to #Creating and debugging Grooper scripts for more information if you need.

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

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

In normal scenarios, when a user wants to open the Grooper web app, they don't need to install anything. They just enter a URL in a browser and hit go. It doesn't matter what machine they are one. Scripting in Grooper is not a normal scenario.

If you are not scripting on the Grooper webserver, you need to set up a "remote scripting machine".

On the remote scripting machine you will need to:

  1. Install the Grooper application
    • This must be installed on the remote scripting machine to (1) connect to the Grooper Repository and (2) use Grooper components required to compile the script you're developing.
    • If you need to know how to install Grooper, visit the Install and Setup article.
    • You do not need to install MS SQL Server on the remote scripting machine. You will be connecting to a Grooper Repository whose database already exists and is hosted elsewhere.
  2. Connect to the Grooper Repository from GCC
    • Because the remote scripting machine is hosting a local Grooper install, you will need to connect it to the Grooper Repository.
    • If you need to know how to connect to a Grooper Repository visit the Connecting to an existing Grooper Repository section of the Install and Setup article.
  3. Install IIS
    • IIS hosts the Grooper website.
    • This will host a Grooper website locally on your remote scripting machine. When debugging from Visual Studio, you will always connect to the Grooper web app using a localhost URL.
    • If you do not know how to install IIS for Grooper, visit the Installing IIS section of the Install and Setup article.
  4. Install the Grooper Web Client application
    • This is required to debug scripts in Grooper's web-based UI.
    • If you do not know how to install the Grooper Web Client, visit the Installing the Grooper Web Client section of the Install and Setup article.

Creating and debugging Grooper scripts

BE AWARE: This was copied from the 2023.1 article. Its advice should be largely accurate. Screenshots may be somewhat outdated.

Create a script and local project files in Grooper

BE AWARE: This was copied from the 2023.1 article. Its advice should be largely accurate. Screenshots may be somewhat outdated.

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.

Edit the project in Visual Studio

BE AWARE: This was copied from the 2023.1 article. Its advice should be largely accurate. Screenshots may be somewhat outdated.

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

Debug the project in a browser

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 script

BE AWARE: This was copied from the 2023.1 article. Its advice should be largely accurate. Screenshots may be somewhat outdated.

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