View source for Scripting Setup

{{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. There are five "scriptable" Grooper node types. Custom scripts can be created for all these node types from their "Scripting" tab. These scriptable Grooper nodes are:
* {{ObjectLibraryIcon}} '''[[Object Library]]'''
* {{DataModelIcon}} '''[[Data Model]]'''
* {{DataTableIcon}} '''[[Data Table]]'''
* {{DataTypeIcon}} '''[[Data Type]]'''
* {{BatchProcessIcon}} '''[[Batch Process]]'''


With scripts you can:
* Create a Grooper Object Library to create custom Activities, Commands, Services, CMIS Connection Bindings, and other Grooper objects.
* Create Batch Process scripts to alter how Batch Process Steps are executed. 
*:*<li class="fyi-bullet"> This functionality has largely been replaced by the "Should Submit" and "Next Step" expressions in a '''Batch Process'''.
* Create Data Model scripts to perform custom validation events or data normalization logic. 
*:*<li class="fyi-bullet"> This functionality has largely been replaced by Grooper's Data Rules.
* Create Data Table scripts to perform custom lookups. 
*:*<li class="fyi-bullet"> This functionality has largely been replaced by Object Libraries, which can be used to create custom "Lookup Specifications".
* Create Data Type scripts to perform custom extraction validation and manipulation.
*:*<li class="fyi-bullet"> 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:
# 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.
# 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.
# 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.
**<li class="attn-bullet"> '''BE AWARE:''' When debugging, Visual Studio will always open a browser connected to the default Grooper Repository. If necessary, you can change the default Grooper Repository with the <code>connections setDefault</code> command in GCC.

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

<big>Install Visual Studio 2022</big>

# [https://learn.microsoft.com/en-us/visualstudio/install/install-visual-studio?view=vs-2022 Install Visual Studio 2022] on your machine if you have not done so already.
# Be sure your Visual Studio install includes the "ASP.NET and web development" workload. Install it if it does not.
#:[[image:2023_Remote-Scripting-Setup_01_About_04.png|800px]]


<big>Install the Grooper SDK extension</big>

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.

# Launch Visual Studio (as an administrator).
# Continue to the application. 
#:*<li class="fyi-bullet"> Under "Get Started" you can choose "Continue without code".
# Open the "Extensions" menu.
# Choose "Manage Extensions".
# Search for "Grooper"
# Select "GrooperSDK" and click "Download"
# Visual Studio will inform you the changes have been scheduled. Close Visual Studio to finish installing Grooper SDK.
# After closing Visual Studio, the VSIX installer launches. Click "Modify" to install the Grooper SDK extension.
# After installation is finished, click "Close".
# Re-launch Visual Studio (as an administrator).
# After Grooper SDK is installed, you'll see "Grooper" in the Extensions menu.
#:*<li class="fyi-bullet"> 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. 

<div style="position: relative; box-sizing: content-box; max-height: 80vh; max-height: 80svh; width: 100%; aspect-ratio: 1.7777777777777777; padding: 40px 0 40px 0;"><iframe src="https://app.supademo.com/embed/cma6zm9ih003qv90ixox7gn2n?embed_v=2&utm_source=embed" loading="lazy" title="2025Wiki - Scripting Setup - 01 Installing Grooper SDK" allow="clipboard-write" frameborder="0" webkitallowfullscreen="true" mozallowfullscreen="true" allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>

<big>Set the debug start page (Optional)</big>

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

# In Visual Studio, click the "Tools" menu.
# Choose "Options".
# In the Options menu, search for and select "Grooper".
# Select "Debugging".
# 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.

<div style="position: relative; box-sizing: content-box; max-height: 80vh; max-height: 80svh; width: 100%; aspect-ratio: 1.7777777777777777; padding: 40px 0 40px 0;"><iframe src="https://app.supademo.com/embed/cma72lhvs0009zy0jncmmoi1h?embed_v=2&utm_source=embed" loading="lazy" title="2025Wiki - Scripting Setup - 02 Set the debug start page" allow="clipboard-write" frameborder="0" webkitallowfullscreen="true" mozallowfullscreen="true" allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>

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:
# 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.
# 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.
#*<li class="fyi-bullet"> 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.
# 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 [[Install_and_Setup#Connecting_to_an_existing_Grooper_Repository|Connecting to an existing Grooper Repository]] section of the Install and Setup article.
#*<li class="attn-bullet"> '''BE AWARE:''' When debugging, Visual Studio will always open a browser connected to the default Grooper Repository. If necessary, you can change the default Grooper Repository with the <code>connections setDefault</code> command in GCC.
# 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 [[Install_and_Setup#Setup:_Installing_Internet_Information_Services_(IIS)|Installing IIS]] section of the Install and Setup article.
# 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 [[Install_and_Setup#Installing_Grooper_Web_Client|Installing the Grooper Web Client]] section of the Install and Setup article.

== Creating and debugging Grooper scripts ==
<section begin="Object Library" />
=== Example Object Library for a simple Command ===

There are five "scriptable" Grooper node types. Custom scripts can be created for all these node types from their "Scripting" tab. These scriptable Grooper nodes are:
* '''Object Library'''
* '''Data Model'''
* '''Data Table'''
* '''Data Type'''
* '''Batch Process'''

Data Model, Data Table, Data Type and Data Table scripts operate primarily by responding to events on the object they're attached to. These are less common in new versions of Grooper as functionality has been improved to largely replace their utility (For example: Should Submit and Next Step Expressions have largely replaced Batch Process scripting).

'''Object Library''' scripting is more. '''Object Library''' scripts are used to customize the way that Grooper works.  This can be done by extending a Grooper class through inheritance or by creating methods that can be called from within Grooper. 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.

# On your scripting machine, open this URL in a browser: <code><nowiki>http://localhost/Grooper</nowiki></code>
#* This opens Grooper in "dev mode" and enables various scripting related commands.
#*<li class="attn-bullet"> You '''must''' do this on your scripting machine where Visual Studio and all other necessary components are installed.
#*<li class="attn-bullet"> 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.
# From the Design page, right-click the '''Project''' you want to add the '''Object Library''' to.
# Select "Add", then "Object Library".
# Name the '''Object Library''' and press the "Execute" button to create it.
# Click on the '''Object Library's''' "Scripting" tab.
# Click the "Create Script Project" button
#*<li class="attn-bullet"> If you have not used the localhost URL (<code><nowiki>http://localhost/Grooper</nowiki></code>), this button will be greyed out.
# Select the programing language ("C#" for this tutorial).
# This creates the '''Object Library's''' Visual Studio solution and project files.
#:*<li class="fyi-bullet"> 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.
# Click the "Download Script" button.
# This brings up the "Working Directory" window. This will be your working directory for Grooper scripts going forward. The "Base Directory" defaults to <code>C:\GrooperScripts</code>. 
#:*<li class="fyi-bullet"> Grooper will create this directory if it does not exist.
#:*<li class="fyi-bullet"> You may change the "Base Directory" path if you wish. Grooper will remember last used path for each Grooper Repository.
# Click "OK" to download the solution.
# 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.
# 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.

<div style="position: relative; box-sizing: content-box; max-height: 80vh; max-height: 80svh; width: 100%; aspect-ratio: 1.7777777777777777; padding: 40px 0 40px 0;"><iframe src="https://app.supademo.com/embed/cma794sat00cmw70i9nt6gms8?embed_v=2&utm_source=embed" loading="lazy" title="2025Wiki - Scripting Setup - 03 Create an Object Library and download its solution files" allow="clipboard-write" frameborder="0" webkitallowfullscreen="true" mozallowfullscreen="true" allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>

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

<pre>
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;
        }
    }
}
</pre>

To edit a Grooper script solution in Visual Studio:

# Open Visual Studio (as an admin).
# Select "Open a project or solution".
# Use the File Explorer to navigate to where your solution is (C:\GrooperScripts is the default location).
# Select the solution and open it.
# In Visual Studio, select the Solution Explorer tab.
# Right click the solution, and select "Add" then "New Item..."
# (If present) click "Show All Templates".
#:*<li class="fyi-bullet"> 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).
# Select "Class" to add a new class.
# Name the class appropriately and select "Add"
# 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.
# When finished, save your class/solution.
#*<li class="attn-bullet"> 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.

<div style="position: relative; box-sizing: content-box; max-height: 80vh; max-height: 80svh; width: 100%; aspect-ratio: 1.7777777777777777; padding: 40px 0 40px 0;"><iframe src="https://app.supademo.com/embed/cmabbu5gy008c1s0hj2t1rxls?embed_v=2&utm_source=embed" loading="lazy" title="2025Wiki - Scripting Setup - 04 Editing the script in Visual Studio" allow="clipboard-write" frameborder="0" webkitallowfullscreen="true" mozallowfullscreen="true" allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>

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

# Go to the class's attribute list.
# To add a new icon, enter <code>IconName("name")</code> into the attribute list.
#* We use Google's "material symbols" for our icons. You can find these at the [https://fonts.google.com/icons Google Material Symbols & Icons] website.
# Replace <code>name</code> 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.
#*: [[File:2025-ScriptingSetup-icon-name-info-01.png|class=simpleborder]]
#* 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".
#*<li class="attn-bullet"> 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.

<div style="position: relative; box-sizing: content-box; max-height: 80vh; max-height: 80svh; width: 100%; aspect-ratio: 1.7777777777777777; padding: 40px 0 40px 0;"><iframe src="https://app.supademo.com/embed/cmabfo7sq001b0u0juyem7dwr?embed_v=2&utm_source=embed" loading="lazy" title="2025Wiki - Scripting Setup - 05 How to set a Command/Activity's icon" allow="clipboard-write" frameborder="0" webkitallowfullscreen="true" mozallowfullscreen="true" allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>

<big>Bonus bonus! You can add overlays to icons too</big>

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 ({{CMISConnectionIcon}}) and Data Connection ({{DataConnectionIcon}}) icons have a "connect" overlay.
* Example: The Field Class ({{FieldClassIcon}}) icon has a "lightning" overlay.

You can use any of the overlays we've created in your IconName attribute using the following syntax:
:<pre>IconName("name", IconName.Overlay.overlayName)</pre>
:* Replace <code>name</code> with the material symbol's icon name (as described above).
:* Replace <code>overlayName</code> with one of the following overlays:
:** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1;">add_circle</i> @add 
:** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1;">arrow_upward_alt</i> arrowup 
:** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1;">arrow_downward_alt</i> arrowdown 
:** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1;">check</i> check 
:** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1;">power</i> connect 
:** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1; color: #36b0a7">circle</i> circlegreen 
:** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1; color: #ed2330">circle</i> circlered 
:** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1;">remove_circle</i> delete 
:** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1;">arrow_right_alt</i> go 
:** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1;">bolt</i> lightning 
:** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1;">attach_file</i> paperclip 
:** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1;">undo</i> reset 
:** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1;">account_tree</i> tree

===== Bonus: How to add the in-app help for a custom object =====

'''''COMING SOON'''''

==== 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.
*<li class="attn-bullet"> '''BE AWARE:''' When debugging, Visual Studio will always open a browser connected to the default Grooper Repository. If necessary, you can change the default Grooper Repository with the <code>connections setDefault</code> command in GCC.

To debug the script:

# Press the "Start" button to start a debug session.
# Visual Studio will first build the solution. You will be warned if the build fails.
# Grooper SDK launches IIS Express to open a local Grooper session.
# 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.
#*<li class="attn-bullet"> Your default browser must be compatible with Grooper (Google Chrome or Microsoft Edge).
# Test your script in Grooper.
#* If you are testing using the "Set Description" code we provided do the following:
#*# Right click any node with a "Description" property. 
#*# You will see the custom command called "Set Description". 
#*# Enter a description and hit "Execute". 
#*# You should then see the node's Description property set to the description you set.
# Either close the browser or press the "Stop" button in Visual Studio to end the debug session.
#:*<li class="fyi-bullet"> 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.

<div style="position: relative; box-sizing: content-box; max-height: 80vh; max-height: 80svh; width: 100%; aspect-ratio: 1.7777777777777777; padding: 40px 0 40px 0;"><iframe src="https://app.supademo.com/embed/cmabkfp8t0001140i8qjkepfh?embed_v=2&utm_source=embed" loading="lazy" title="2025Wiki - Scripting Setup - 07 Debug the script in a browser" allow="clipboard-write" frameborder="0" webkitallowfullscreen="true" mozallowfullscreen="true" allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>

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

<big>Using the "Save and Compile" command</big>

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.

# Open the "Extensions" menu in Visual Studio.
# Select "Grooper", then "Save and Compile"
# Click "Yes" to continue. This will overwrite the script saved in the Grooper Repository.
# Visual Studio will notify you when the script has finished compiling in Grooper. This may take a moment.
# Press "OK" to confirm.
#:*<li class="fyi-bullet"> 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
# 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.
# 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.
# Your script is now active in Grooper. Test from the normal application URL (<nowiki>https://hostname/Grooper</nowiki>) to verify.

<div style="position: relative; box-sizing: content-box; max-height: 80vh; max-height: 80svh; width: 100%; aspect-ratio: 1.7777777777777777; padding: 40px 0 40px 0;"><iframe src="https://app.supademo.com/embed/cmacuy59q00j8wk0iqnmjmcld?embed_v=2&utm_source=embed" loading="lazy" title="2025Wiki - Scripting Setup - 08 Saving to Grooper and compiling (with "Save and Compile")" allow="clipboard-write" frameborder="0" webkitallowfullscreen="true" mozallowfullscreen="true" allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>

<big>Using the "Save" command</big>

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.

# Open the "Extensions" menu in Visual Studio.
# Select "Grooper", then "Save and Compile"
# Click "Yes" to continue. This will overwrite the script saved in the Grooper Repository.
# Visual Studio will notify you when the script is saved successfully. Press "OK" to confirm.
# Open Grooper in a browser and go to the script's node.
#:*<li class="fyi-bullet"> 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.
# Go to the node's "Scripting" tab.
# Press the "Compile" button.
# Grooper will notify you when the compile is successful or has failed. 
#:*<li class="fyi-bullet"> 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.
# Click "OK" to continue.
#:*<li class="fyi-bullet"> 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
# 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.
# 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.
# Your script is now active in Grooper. Test from the normal application URL (<nowiki>https://hostname/Grooper</nowiki>) to verify.

<div style="position: relative; box-sizing: content-box; max-height: 80vh; max-height: 80svh; width: 100%; aspect-ratio: 1.7777777777777777; padding: 40px 0 40px 0;"><iframe src="https://app.supademo.com/embed/cmacxocc402bz0e0i4mp7l9jw?embed_v=2&utm_source=embed" loading="lazy" title="2025Wiki - Scripting Setup - 09 Saving to Grooper and compiling (with "Save")" allow="clipboard-write" frameborder="0" webkitallowfullscreen="true" mozallowfullscreen="true" allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>
<section end="Object Library" />

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

== More on Scripting ==

=== Grooper Object inheritance ===

Nearly everything in Grooper inherits from "Grooper Object". Check out the [[Grooper Object]] and [[List of Grooper Objects]] pages for a full list of all objects that inherit from Grooper Object.

=== Scripting templates ===
[[File:2025-templates.png|thumb|600px|right|When creating a new item, press "Show All Templates" to see the Grooper templates.]]
When you create a new Grooper scripting project in Visual Studio, there are several templates that can help get you started creating Object Libraries.

When adding a new item to your solution, press the "Show All Templates" button to see the Grooper templates. You will see 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).
<br clear=all>

=== Serialization ===
[[File:2025-datacontract-datamember-01.png|frame|Example "WebServiceProperties" class and its member variables for serialization/]]
Grooper utilizes serialization to efficiently store the properties and settings of Grooper objects.  You can apply the <code>[https://learn.microsoft.com/en-us/dotnet/api/system.runtime.serialization.datacontractattribute DataContract]</code> attribute and <code>[https://learn.microsoft.com/en-us/dotnet/api/system.runtime.serialization.datamemberattribute DataMember]</code> attributes to explicitly control or customize the serialization of types and members.

For more information on Data Contracts and Data Members, see [https://docs.microsoft.com/en-us/dotnet/framework/wcf/feature-details/how-to-create-a-basic-data-contract-for-a-class-or-structure How to: Create a Basic Data Contract for a Class or Structure].

;DataContract
:Specifies that the type defines or implements a data contract and is serializable by a serializer.  In the "WebServiceProperties" example, the <code>DataContract</code> attribute indicates to Grooper that a WebServiceProperties object is being serialized.  

;DataMember
:When applied to the member of a type, specifies that the member is part of a data contract and is serializable.  In the "WebServiceProperties" example, the <code>DataMember</code> attribute indicates that a value should be serialized for each of the specified members (HostName, PortNo, UrlPath, HttpsEnabled, and EnableDebugging).

=== Scripting Object Markup ===

This section is intended to introduce some of the functionality that can be enhanced and modified by marking up scripting objects with attributes and comments.

==== Objects ====

For the purpose of this article, "objects" will be defined as classes and procedures:

;Class
:The formal definition of an object. The class acts as the template from which an instance of an object is created at run time. The class defines the properties of the object and the methods used to control the object's behavior.

;Procedure 
:A named sequence of statements executed as a unit. For example, Function, Property, and Sub are types of procedures.

====Markup====

Markup refers to the use of comments and attributes to affect the display and/or behavior of scripting objects.

==== Attributes ====

Attributes provide a powerful method of associating metadata with code.   Grooper recognizes many attributes that can enhance or change default behavior.  Some of the most important functionality enabled through attribute markup are Serialization, Type Converters and Property Grid Editors.
* [https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/language-specification/attributes Attributes - C#]
* [https://learn.microsoft.com/en-us/dotnet/visual-basic/programming-guide/concepts/attributes/ Attributes - Visual Basic]

Example (taken from our Object Library example [[#Example_Object_Library_for_a_simple_Command|above]]:
<pre>
[DataContract, IconName("info"), DisplayName("Set Description")]
</pre>

<big>Attributes used in Grooper</big>
* <code>DisplayName</code>:  Overrides the default display name of a method or property.  By default, Grooper will use the method or property name as the display name.  (Grooper will insert spaces before capitalized letters.  For example, a property named "FileStore"  would end up with a display name of "File Store".)  Explicitly specifying the display name can be useful in cases where you want to override the default display name:  for example, using the display name attribute to display "SQL Database" instead of "Sql Database".
* <code>DV(''default value'')</code>:  Specifies the default value of a field or property.
* <code>DataContract</code>:  Specifies that the type defines a data contract and is serializable.  See [[#Properties]] for more information.
* <code>DataMember</code>:  Specifies that this is a member of a data contract and is serializable.  See [[#Properties]] for more information.
* <code>EmitDefaultValue</code>:  Specifies whether to serialize the default value for the field or property being serialized.
[[File:2025-attributes-01.png|right|thumb|IconName("database") is used to give our Grooper Root node its icon.]]
* <code>IconName</code>:  Specifies an icon which should be used as the icon for the object. We use Google's material symbols for our icons. You can search for material symbols on the [https://fonts.google.com/icons Google Material Symbols & Icons website]. Use the icon's "icon name" not its display name.
*: Example: <code>[IconName("database")]</code>
**<li class="attn-bullet"> 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.
** <code>IconName.Overlay.overlayName</code>: Optional attribute that can overlay an icon onto the provided icon. You can use any of the following overlays:[[File:2025-attributes-02.png|right|thumb|IconName.Overlay.connect overlays a plug icon on top of the database icon. This is used to give our Data Connection nodes their icon.]]
*** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1;">add_circle</i> @add 
*** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1;">arrow_upward_alt</i> arrowup 
*** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1;">arrow_downward_alt</i> arrowdown 
*** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1;">check</i> check 
*** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1;">power</i> connect 
*** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1; color: #36b0a7">circle</i> circlegreen 
*** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1; color: #ed2330">circle</i> circlered 
*** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1;">remove_circle</i> delete 
*** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1;">arrow_right_alt</i> go 
*** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1;">bolt</i> lightning 
*** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1;">attach_file</i> paperclip 
*** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1;">undo</i> reset 
*** <i class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1;">account_tree</i> tree
**: Example: <code>[IconName("database", IconName.Overlay.connect)]</code>
[[File:2025-attributes-03.png|right|thumb|The 'File Store Information' category groups these two properties in the File Store node's property grid.]]
* <code>Category</code>:  Specifying a category will create titled groups in the property grid.  Any properties with equivalently named categories will be grouped under that category name.
*: Example: <code>[Category("File Store Information"), Viewable]</code>
* <code>TypeConverter</code>:   Provides a way of converting types of values to other types, as well as for accessing standard values and subproperties.  See [[#Property Grid Editors and Type Converters]] for more information.
* <code>UI</code>:  Used to design value editors that can provide a user interface (UI) for representing and editing the values of Grooper objects.  See [[#Property Grid Editors and Type Converters]] for more information.
* <code>AppliesTo</code>:  Class attribute that includes a public Type property, indicating an exclusive type to which the class applies.
* <code>Viewable</code>:  The viewable attribute is required for properties that will be displayed to the user.  Developed to allow for the filtering of object collections, based on type application.
* <code>Required</code>:  The required attribute causes the property to generate a validation error if the property is not set.
* <code>AllowedScopes()</code>: Used to set an Activity's allowable processing scopes. May be one or more of the following:
** <code>GrooperDb.ProcessingScope.Batch</code>
** <code>GrooperDb.ProcessingScope.Folder</code>
** <code>GrooperDb.ProcessingScope.Page</code>
** Multiple scopes may be separated by a comma (e.g. <code>AllowedScopes(GrooperDb.ProcessingScope.Batch, GrooperDb.ProcessingScope.Folder)</code>)

==== XML Documentation Comments ====
You can create documentation for your code by including XML elements in special comment fields (indicated by triple tick marks <code><nowiki>'''</nowiki></code> in VB or triple slashes <code>///</code> in C#) in the source code directly before the code block to which the comments refer.
* The <code><nowiki><summary></nowiki></code> tag should be used to describe a type or a type member. 
* Use a <code><remarks></code> tag to add supplemental information to a type description.  Grooper further utilizes these comments by using them to populate the help section of property grids and displaying tool tips, as applicable, for the objects at run-time.

Example (taken from the Grooper Root node's "Repository Name" property):
[[File:2025-xmlcomments-01.png|thumb|right|500px|These XML comments render the in-app help seen here for the "Repository Name" property.]]
<pre style="width:auto">
/// <summary>The name of this Grooper repository.</summary>
/// <remarks>
/// &lt;b&gt;RepositoryName&lt;/b&gt; provides the human-readable name for the repository, used throughout the Grooper UI, logs, and reports.
/// - This value is typically set during repository creation or via the Grooper Command Console.
/// - Changing the repository name does not affect its unique identity or database location.
/// - Use descriptive names to distinguish between environments (e.g., "Production", "Test", "Archive").
/// </remarks>
</pre>
<br clear=all>

=== Properties ===

Properties are added to a class for numerous reasons. Configurable properties are added to many Grooper objects to define parameters necessary for its function. For example, a Batch Process Step's "Activity" property defines which Grooper Activity is executed.

Properties are declared differently in Visual Basic and C#.
* '''In Visual Basic:'''
** Properties are declared with the <code>Property</code> statement.
** Properties are auto-implemented by declaring <code>Property Name As Type</code>
** Supports attributes with angle brackets: <code><Attribute></code>
** Example:
<pre style="margin-left:60px">
<DataMember, Viewable, Category("File Output"), Required>
Public Property FileExtension As String
</pre>
* '''In C#:'''
** Properties are not declared with a keyword/statement. Accessors (<code>get</code> and <code>set</code>) are used to imply a property 
** You must use <code>{ get; set; }</code> explicitly to auto-implement the property</code>
** Supports attributes with square brackets: <code>[Attribute]</code>
** Example:
<pre style="margin-left:60px">
[DataMember, Viewable, Category("File Output"), Required]
public string FileExtension { get; set; }
</pre>
* '''In both C# and Visual Basic:'''
** Properties are serialized by tying them to the class's <code>DataContract</code> using the <code>DataMember</code> attribute.
** Properties appear in a property grid by adding the <code>Viewable</code> attribute. 
** Properties may be organized with the <code>Category</code> attribute.
** Properties are made required with the <code>Required</code> attribute.
** Default property values are defined with the <code>DV()</code> attribute.

External Documentation:
* [https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties Properties - C#]
* [https://learn.microsoft.com/en-us/dotnet/visual-basic/language-reference/statements/property-statement Property Statement - Visual Basic]

=== Property Grid Editors and Type Converters ===

;Type Converter
: Provides a way of converting types of values to other types, as well as for accessing standard values and subproperties.  
: [https://docs.microsoft.com/en-us/dotnet/api/system.componentmodel.typeconverter Click here for more information].

;Editor
: Used to design value editors that can provide a user interface (UI) for representing and editing the values of Grooper objects.

<big>Type Converter</big>

A Type Converter is a helper class used in Grooper to control how a property behaves in the UI. Type Converters make configuration easier and more user-friendly, especially for properties that depend on external data or context.  They can:
* Provide a list of valid values (like a dropdown).
* Convert between types (e.g., string to object).
* Customize how a property is displayed or edited.


Type Converters are implemented by the <code>TypeConverter</code> attribute.
* In C#: <code>[TypeConverter(typeof(''ConverterName''))]</code>
* In Visual Basic: <code><TypeConverter(GetType(''ConverterName''))></code>


Example: <code>PgCollectionConverter</code>
[[File:2025-typeconverter-02.png|thumb|right|600px|The PgCollectionConverter applied to the "Export Behaviors" property.]]
:This converter changes the a property's basic characteristics in the property grid. When applied to a property which is a collection type, it displays the count of items in the collection.

:The Export Activity's "Export Behaviors" property utilizes the <code>PgCollectionConverter</code>. 

:See how it is implemented in the property's attributes in the bolded text below.
::<code>[DataMember, Viewable, '''TypeConverter(typeof(PgCollectionConverter))''', UI(typeof(ObjectCollectionEditor))]</code>

A full list of type converters in Grooper can be found in the [http://localhost/Grooper/Help?typeName=Grooper.PropertyConverter Property Converter] section of the Grooper Help.

<big>Editor</big>

Property Grid Editors (or just "editors") provide a way to display Grooper objects in an intuitive way to the user via property grids. Editors are often implemented as dropdowns that allow users to select nodes in the Grooper node tree.


Editors are implemented by the <code>UI</code> attribute.
* In C#: <code>[UI(typeof(''EditorName''))]</code>
* In Visual Basic: <code><UI(GetType(''EditorName''))></code>


Example: <code>ContentScopeEditor</code>
[[File:2025-editor-01.png|thumb|right|600px|The PgCollectionConverter applied to the "Export Behaviors" property.]]
: This editor provides users a dropdown to select a Content Model or a Content Category. It can be applied to properties that require users to select a Content Model (or a narrower Content Category scope within the Content Model).
::*<li class="fyi-bullet"> This editor is an implementation of the <code>ContentTypeEditor</code> which provides users a dropdown to select any Content Type.

:The Classify Activity's "Content Model Scope" property utilizes the <code>ContentScopeEditor</code>

: See how it is implemented in the property's attributes in the bolded text below.
:: <code>[Viewable, '''UI(typeof(ContentScopeEditor))''', Required]</code>

A full list of editors in Grooper can be found in the [http://localhost/Grooper/Help?typeName=Grooper.PropertyEditor Property Editor] section of the Grooper Help.

=== Common Overrides ===

These overrides are common to most (if not all) of the classes inherited in scripting.  Each description below describes the default behavior and some of the common reasons they might be overridden.  
* <code>IsPropertyVisible(PropertyName As String)</code> - Defines whether the specified Property Name is currently visible in the property grid.  Override this function to set the visibility of a property based on your own criteria.
* <code>IsPropertyEnabled(PropertyName As String)</code> - Defines whether the specified Property Name is currently enabled in the property grid.  Override this function to enable/disable a property based on your own criteria.
* <code>IsEmpty()</code> - Returns true if all properties with a <code>Viewable</code> attribute are set to their default value.  <code>IsEmpty</code> is frequently used to determine if an object should be saved or serialized.  This may need to be overridden in the case of complex properties or child objects.
* <code>ValidateProperties()</code> - Validates the properties of the object, returning a list of validation errors.   Derived classes may override this method to add validation logic.  Classes which override this message should always call <code>MyBase.ValidateProperties()</code>, add any new error messages to the returned list, and then return the list.
* <code>ToString()</code> - Returns a string value representation of the object.  This may be overridden to return a custom string value that is displayed in the property grid.  For example, an EmbeddedLexicon object overrides <code>ToString</code> to return the number of Lexicons and/or Entries that it represents.

== Debugging a Custom Service in Grooper ==
=== Step-by-Step Workflow ===
<big>Create an Object Library</big>
* Define a new Object Library in Grooper to host your custom service.
<big>Design your custom service</big>
* Implement your service class (e.g., <code>ImportDustin</code>) inheriting from <code>ImportWatcher</code> or <code>ServiceInstance</code>.
<big>Compile the service from the Design page</big>
* Build the project in Debug mode with full symbol generation (.pdb file).
* Ensure the output DLL and PDB are placed in the working directory.
<big>Install the service using Grooper Command Console (GCC)</big>
* Use the full type name (e.g., <code>DustinService.ImportDustin</code>) when installing the service.
<big>Configure the service from the Design page</big>
* Go to the Object Library and configure the service settings (e.g., credentials, parameters).
<big>Run the Design page from your custom service's Visual Studio project</big>
* Run your custom library from Visual Studio to launch the Design page as the debug target.
<big>Start the service from the Machines folder</big>
* Navigate to the Machines folder from the Design page.
* Select the "Services" tab.
* Select your custom service and click Start.
===Expected Result===
If everything is configured correctly, breakpoints in your custom service code will hit during execution.