Object Library (Node Type)

This article is about the current version of Grooper.

Note that some content may still need to be updated.

2025

2023

extension Object Library nodes are .NET libraries that contain code files for customizing the Grooper's functionality. These libraries are used for a range of customization and integration tasks, allowing users to extend Grooper's capabilities.
Examples include:
Adding custom Activities that execute within Batch Processes

Creating custom commands available during the Review activity and in the Design page.

Defining custom methods that can be called from code expressions on Data Field and Batch Process Step objects.

Creating custom Connection Types for CMIS Connections for import/export operations from/to CMS systems.

Establish custom Grooper Services that perform automated background tasks at regular intervals

Object Libraries are used to customize Grooper with scripting. They can be used to create a variety of new tools, including custom Activities, custom object commands, custom CMIS Connection types and more.

Be sure to check out the Scripting Setup article for more information on how to set up a Grooper scripting environment.

How To: Upload and compile an Object Library

This tutorial is for users who are attempting to import an Object Library developed by BIS or another Grooper user into their own environment. This will explain how to upload an Object Library to a Project in your environment and compile it.

Upload the Grooper ZIP

Go to the Grooper Design page.
Select the Project where you want to import the Object Library.
- Note: If the Grooper ZIP is itself a Project that contains the Object Library, you will need to import from the Projects folder node.
Press the "Upload" button in the top navigation bar.
Press the "Choose File" button. Use the File Explorer to select the Grooper ZIP.
Press the "Upload" button.
The Object Library will be imported into the selected Project

Compile the Object Library

In order for the Object Library to work, its code must first be compiled.

Select the Object Library you wish to compile.
Navigate to the "Scripting" tab.
Press the "Compile" button.
Grooper will notify you when the compile is successful or has failed. 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
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. You should test the script in Grooper at this point.

Example from the Scripting Setup article

This example is transcluded from a larger article. Visit the Scripting Setup article for more information

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: 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.
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
- If you have not used the localhost URL (http://localhost/Grooper), 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.
- 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 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.
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.

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:

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

Go to the class's attribute list.
To add a new icon, enter IconName("name") into the attribute list.
- We use Google's "material symbols" for our icons. You can find these at the Google Material Symbols & Icons website.
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

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.

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 connections setDefault 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.
- 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:
  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.
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.

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

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.
- 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.
- 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.
- 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 (https://hostname/Grooper) to verify.

How To: Manually install the compile tool

In rare cases the Grooper compile tool (MSBuild) does not install correctly, preventing users from compiling scripts (The "Compile" button will be greyed out). In this case, you can manually install the compile tool.

Download "MSBuild.zip" from https://grooper.bisok.com/Downloads/MSBuild/MSBuild.zip
Extract the ZIP contents.
Copy the "MSBuild" folder to the "Script Templates" folder in your Grooper install directory.
- By default this location will be C:\Program Files\BIS\Grooper\Script Templates
If Design Studio is open, close it and re-open it. You should now be able to compile scripts.