Scripting Setup

From Grooper Wiki
(Redirected from Remote Scripting Setup)

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 table Data Table scripts to perform custom lookups.
    • This functionality has largely been replaced by Object Libraries, which can be used to create custom "Lookup Specifications".
  • 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 with installation must have the ASP.NET and web development workload installed.
    • This should not be the production web server or processing servers.
    • Scripting on a production server can cause problems for performance and stability.
  2. You must install the Grooper SDK Visual Studio extension.
    • Grooper SDK is required to successfully edit scripts and debug them in Visual Studio. It synchronizes your debug session with a browser window, creating a developer experience similar to standard web application debugging in Visual Studio. It also provides commands to push local edits to the Grooper Repository and check for any changes made by other developers.
  3. You must be on a machine where Grooper and the Grooper Web Client applications are installed.

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, the Grooper Web Client is installed, and IIS is hosting the Grooper website.

So, the Grooper web server right? NO

It is NOT good practice to install Visual Studio on a production Grooper environment's web server.

How about a processing server running Activity Processing services? NO

It is NOT good practice to install Visual Studio on any production server.

Why not? Performance and stability.

  • Visual Studio is a resource hungry application. It will compete for system resources that should be dedicated to processing production tasks.
  • Even while debugging, you can and are still making changes to a Grooper Repository. You don't want a misstep during a debug session to take down an entire production server.


Instead, you should set up a "scripting machine". This can be any machine that can connect to the Grooper Repository. You will need to do the following on this machine:

  • Install Google Chrome or Microsoft Edge as your default browser.
  • Install Visual Studio with the "ASP.NET and web development" workload enabled.
  • Install the Grooper SDK extension for Visual Studio.
  • Install and configure IIS for the Grooper Web Client
  • Install Grooper and Grooper Web Client applications.

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

First, 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. Grooper SDK is required to successfully edit scripts and debug them in Visual Studio. It lets the editor know where the Grooper libraries installed on your machine are and allows you to debug your scripts in a web browser.

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.

After installing Visual Studio and Grooper SDK, you will need to install Grooper and the Grooper Web Client on your machine.

Step 3: Set up the scripting machine

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.

The scripting machine must have a full Grooper install, including the Grooper Web Client.

On the scripting machine you will need to:

  1. Install Google Chrome or Microsoft Edge and make it your default browser.
    • Chrome and Edge are the two primary supported browsers for Grooper.
    • Grooper SDK opens your default browser when debugging. One of these must be the default browser to debug properly.
  2. Install the Grooper application
    • This must be installed on the 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 scripting machine. You will be connecting to a Grooper Repository whose database already exists and is hosted elsewhere. You just need to be able to connect to that Grooper Repository from your machine.
  3. Connect to the Grooper Repository from GCC
    • Because the 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.
  4. Install IIS
    • IIS hosts the Grooper website.
    • This will host a Grooper website locally on your 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.
  5. 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

Example Object Library for a simple Command

There are five "scriptable" Grooper node types:

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

The Object Library is the most common. Object Libraries exist in Grooper solely to customize Grooper functionality through scripting. They are used to create:

  • Custom Activates
  • Custom Commands
  • Custom Services
  • Or any other custom Grooper object

This tutorial will show you how to create and debug a Grooper script for an Object Library. The Object Library will create a simple custom Command, using a C# script. This will be a right-click command you can use on any Grooper node to set its Description property.

Create a script in Grooper and download its solution files

First, we need to add an Object Library to a Grooper Project. Then, we will create its scripting files in Grooper. Last, we will download those files to a local directory on our scripting machine so we can edit them in Visual Studio.

Click here for an interactive walkthrough.

  1. On your scripting machine, open this URL in a browser: http://localhost/Grooper
    • This opens Grooper in "dev mode" and enables various scripting related commands.
    • You must do this on your scripting machine where Visual Studio and all other necessary components are installed.
    • You must use the localhost URL to enable dev mode.
      • You will not be able to create the scripting files necessary in Grooper if you connect with the machine's hostname or IP address.
      • You will not be able to download those scripting files to edit them in Visual Studio if you connect with the machine's hostname or IP address.
  2. From the Design page, right-click the Project you want to add the Object Library to.
  3. Select "Add", then "Object Library".
  4. Name the Object Library and press the "Execute" button to create it.
  5. Click on the Object Library's "Scripting" tab.
  6. Click the "Create Script Project" button
    • If you have not used the localhost URL (http://localhost/Grooper), this button will be greyed out.
  7. Select the programing language ("C#" for this tutorial).
  8. This creates the Object Library's Visual Studio solution and project files.
    • These files are stored in the Grooper Repository, not your local machine. If you were to go to this node's "Advanced" tab, you would see this same list of files in the "Files" window.
  9. Click the "Download Script" button.
  10. This brings up the "Working Directory" window. This will be your working directory for Grooper scripts going forward. The "Base Directory" defaults to C:\GrooperScripts.
    • Grooper will create this directory if it does not exist.
    • You may change the "Base Directory" path if you wish. Grooper will remember last used path for each Grooper Repository.
  11. Click "OK" to download the solution.
  12. Grooper will inform you the solution has been downloaded to the path entered in step 10. A folder will be created named after the Object Library's name. Click "OK" to continue.
  13. You have now downloaded the Visual Studio solution and project files to your local machine.
    • They are now ready to be edited in Visual Studio.
    • If you wish, you can verify the files have been copied from the Grooper Repository to your local machine. Just open Windows File Explorer and browse to your local working directory for Grooper scripts.

Edit the script in Visual Studio

Now that we have a script solution, we can add a class for our custom object command.

See below for a copy of the code we're going to use.

  • This will create a custom command called "Set Description"
  • After editing and compiling our solution, this command will show up in the Design page for any node that has a "Description" property.
  • Right clicking the node will open an editor to quickly set the node's "Description" value.
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, IconName("info"), DisplayName("Set Description")]
    public class ObjectCommand : ObjectCommand<GrooperNode>
    {
        [DataMember, Viewable, Required]
        public string Description { get; set; }

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

To edit a Grooper script solution in Visual Studio:

Click here for an interactive walkthrough.

  1. Open Visual Studio (as an admin).
  2. Select "Open a project or solution".
  3. Use the File Explorer to navigate to where your solution is (C:\GrooperScripts is the default location).
  4. Select the solution and open it.
  5. In Visual Studio, select the Solution Explorer tab.
  6. Right click the solution, and select "Add" then "New Item..."
  7. (If present) click "Show All Templates".
    • The templates screen will give you multiple script templates for commonly created objects, such as:
      • "Custom Code Activity" to create custom Grooper activities you can add to a Batch Process.
      • "Object Command" to create custom commands that can be applied from the Design page or by users in the Review interface.
      • "Timer Service" to create custom services that run at regularly scheduled intervals (Both Import Watcher and System Maintenance Service inherit from Timer Service).
      • "Custom Web Service" to create custom services that use web calls (The Grooper Licensing service inherits from Timer Service).
  8. Select "Class" to add a new class.
  9. Name the class appropriately and select "Add"
  10. Now you can start editing your script.
    • If you're following along with our example, delete the boilerplate code, copy the code block from above and paste it into the editor.
  11. When finished, save your class/solution.
    • BE AWARE! Saving the script solution in Visual Studio only saves the local files in your working directory. Grooper has not been affected yet. You will need to use the Grooper SDK's "Save" or "Save and Compile" commands to save changes to the Grooper Repository. See the #Saving to Grooper and compiling the script section for more info.
Bonus: How to set a Command/Activity's icon

A Grooper Command or Activity's icon is set by its IconName attribute. You can add/edit this attribute in the attribute list.

Click here for an interactive walkthrough.

  1. Go to the class's attribute list.
  2. To add a new icon, enter IconName("name") into the attribute list.
  3. Replace name with the name of the icon you want to use.
    • Be sure to use the icon's "icon name". Sometimes this can differ from the display name on Google.
    • You can find the icon name on the Google Material Symbols & Icons website. Just search for an icon, click on it, then scroll to the bottom of the information panel. It will be listed under "Icon name".
    • BE AWARE! Grooper uses a font file to generate these icons. This is a hard copy of the material symbols font file up to a certain date in time. Newer material symbol icons may (1) not show up at all or (2) show up differently when used as an IconName attribute.

Bonus bonus! You can add overlays to icons too

We have created several "overlay" classes for Grooper's icons internally. When you see icons with a smaller icon in the corner, often it's because we are overlaying another icon on top of them.

  • Example: The CMIS Connection (cloud) and Data Connection (database) icons have a "connect" overlay.
  • Example: The Field Class (input) icon has a "lightning" overlay.

You can use any of the overlays we've created in your IconName attribute using the following syntax: 

IconName("name", IconName.Overlay.overlayName)
  • Replace name with the material symbol's icon name (as described above).
  • Replace overlayName with one of the following overlays:
    • add_circle @add
    • arrow_upward_alt arrowup
    • arrow_downward_alt arrowdown
    • check check
    • power connect
    • circle circlegreen
    • circle circlered
    • remove_circle delete
    • arrow_right_alt go
    • bolt lightning
    • attach_file paperclip
    • undo reset
    • account_tree tree
Bonus: How to add the in-app help for a custom object

Debug the script in a browser

Grooper SDK enables debugging of Grooper scripts using the Grooper web client. It launches Grooper in a browser window when a debug session starts, and closes the browser window when the debug session ends. The browser window and debug session are synchronized. If the browser window is closed during a debug session, the debug session will be terminated. This creates a developer experience similar to standard web application debugging in Visual Studio.

To debug the script:

Click here for an interactive walkthrough.

  1. Press the "Start" button to start a debug session.
  2. Visual Studio will first build the solution. You will be warned if the build fails.
  3. Grooper SDK launches IIS Express to open a local Grooper session.
  4. Grooper SDK opens the Grooper web app using a localhost URL.
    • The Grooper Home page is launched by default (unless you changed the Grooper SDK Start Page).
    • Your machine's default browser is used.
    • Your default browser must be compatible with Grooper (Google Chrome or Microsoft Edge).
  5. Test your script in Grooper.
    • If you are testing using the "Set Description" code we provided do the following:
      1. Right click any node with a "Description" property.
      2. You will see the custom command called "Set Description".
      3. Enter a description and hit "Execute".
      4. You should then see the node's Description property set to the description you set.
  6. Either close the browser or press the "Stop" button in Visual Studio to end the debug session.
    • Grooper SDK makes it possible to perform a debug session just as you would using any other target. This includes setting break points in your code.

Saving to Grooper and compiling the script (The Grooper SDK Commands)

Before your custom script is usable in Grooper, you must do two things: (1) Save the script to Grooper. (2) Compile the script in Grooper.

The Grooper SDK extension has three commands that help you facilitate this from Visual Studio:

  • Save - Saves the script to Grooper.
    • This command takes the local solution files and "pushes" them to the original node in the Grooper Repository.
    • This overwrites all scripting files saved on the node in Grooper.
    • This does not compile the script in Grooper. You will need to go to the node in Grooper and run the compile command if you use this option.
    • After compiling in Grooper, you will need to recycle the Grooper App Pool on the web server before changes take effect.
  • Save and Compile - Saves the script to Grooper and compiles it in Grooper.
    • This command does exactly what "Save" does but also compiles the script in Grooper.
    • After executing this command, you will need to recycle the Grooper App Pool on the web server before changes take effect.
  • Get Latest - Syncs your local solution files with those in Grooper.
    • This command is for scenarios where multiple developers are working in the same Grooper Repository on the same scripts.
    • This command syncs your local solution with the solution files saved in the Grooper Repository. It gets the latest code from the node in the Grooper Repository.

Using the "Save and Compile" command

This is generally regarded as the easiest way to publish changes to a script to Grooper and make it ready to use in the Grooper Repository.

Click here for an interactive walkthrough.

  1. Open the "Extensions" menu in Visual Studio.
  2. Select "Grooper", then "Save and Compile"
  3. Click "Yes" to continue. This will overwrite the script saved in the Grooper Repository.
  4. Visual Studio will notify you when the script has finished compiling in Grooper. This may take a moment.
  5. Press "OK" to confirm.
    • Compiling the script in Grooper creates the release DLL necessary to execute your script. After compiling, if you go to the node's "Scripting" tab, you will see two new files: the compiled DLL and an XML descriptor file
  6. Go to the webserver host machine and recycle the Grooper App Pool in IIS.
    • Changes will not take effect until the Grooper App Pool is recycled.
    • Recycling the app pool is necessary for the application to "see" the new DLL.
  7. If the script is executed by a Grooper service, services will need to be restarted as well. This will ensure the services register the newly compiled DLLs.
    • Example: An Object Library scripts a custom Activity. Activity Processing services will need to be restarted before they can execute the custom Activity's tasks.
    • Example: An Object Library scripts a custom CMIS Connection type. Import Watcher services will need to be restarted before they can import content using the custom CMIS Connection type. Activity Processing services will need to be restarted before executing Export tasks utilizing the custom CMIS Connection type.
  8. Your script is now active in Grooper. Test from the normal application URL (https://hostname/Grooper) to verify.

Using the "Save" command

This is an adequate way to publish changes to a script to Grooper. But there is additional step in Grooper that must occur to make it ready to use in the Grooper Repository. You must compile the script from Grooper if you use the "Save" command.

Click here for an interactive walkthrough.

  1. Open the "Extensions" menu in Visual Studio.
  2. Select "Grooper", then "Save and Compile"
  3. Click "Yes" to continue. This will overwrite the script saved in the Grooper Repository.
  4. Visual Studio will notify you when the script is saved successfully. Press "OK" to confirm.
  5. Open Grooper in a browser and go to the script's node.
    • An easy way to do this is from the Grooper Root's "Scripts" tab. From the Design page, select the Grooper Root node. Then, select the Scripts tab. This lists all scripted nodes in the Grooper Repository, both compiled and uncompiled. Find the node you're looking for and double click it. This will take you directly to that node.
  6. Go to the node's "Scripting" tab.
  7. Press the "Compile" button.
  8. Grooper will notify you when the compile is successful or has failed.
    • This is the main reason to use the "Save" command over the "Save and Compile" command. The "Save and Compile" command in Visual Studio is convenient. However, compiling in Grooper will give you additional error messages that may help you diagnose why a compile operation failed.
  9. Click "OK" to continue.
    • Compiling the script in Grooper creates the release DLL necessary to execute your script. After compiling, you will see two new files: the compiled DLL and an XML descriptor file
  10. Go to the webserver host machine and recycle the Grooper App Pool in IIS.
    • Changes will not take effect until the Grooper App Pool is recycled.
    • Recycling the app pool is necessary for the application to "see" the new DLL.
  11. If the script is executed by a Grooper service, services will need to be restarted as well. This will ensure the services register the newly compiled DLLs.
    • Example: An Object Library scripts a custom Activity. Activity Processing services will need to be restarted before they can execute the custom Activity's tasks.
    • Example: An Object Library scripts a custom CMIS Connection type. Import Watcher services will need to be restarted before they can import content using the custom CMIS Connection type. Activity Processing services will need to be restarted before executing Export tasks utilizing the custom CMIS Connection type.
  12. Your script is now active in Grooper. Test from the normal application URL (https://hostname/Grooper) to verify.

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