Custom Scripts allows you to make sweeping changes across your account very quickly by leveraging the custom scripting engine based on the ClearPoint API. Custom Scripts can be used to modify elements, summary reports, users, and more.
This feature is very powerful so we strongly recommend reaching out to [email protected] before running your scripts. The team will be able to advise you on your script and help you avoid potential pitfalls.
Why use Custom Scripting
Custom Scripting is an extremely helpful feature for automating repetitive actions within your account. It’s designed to save you lots of time on repeatable steps so that you can focus on your other responsibilities. It is intended for admins who perform a lot of account management and need to make widespread changes throughout their account. Bulk Changes, the evolution of Custom Scripts, should comprise the vast majority of your scripting needs. Custom Scripts are best for filling in the small gaps that Bulk Changes do not cover.
Learn more about Bulk Changes here.
Custom Script Library
While you can create your own scripts, we have ready-to-go scripts that you can use in your account. These scripts work right out of the box so they are a great way to become familiar with and start drawing value from Custom Scripts.
We strongly recommend starting with one of our developed scripts since they are easy to use. Here is the Custom Script Library, which covers a variety of different functions. This library will continuously be updated.
We recommend approaching Bulk Changes first, then move on to Custom Script Library and when you feel comfortable enough, create your own script.
Considerations before creating a script
We only encourage the most advanced users to create a script.
It is much easier to use one of the finished scripts from the Custom Script Library, and it is even easier to use Bulk Changes. If you want to create a Custom Script, it must be written in correct JSON formatting.
Guidelines for this formatting can be found here.
Parameters
Parameters are one of the two main components of a custom script. They are the variables that make it easier to interact with the script, select preferences, and more. Although they are very common in scripts, they are optional.
name: This is a required property. Parameters always start with the dollar sign symbol, e.g. $newObjectiveName.
label: This is a required property. It is what the user running the script will see for the parameter name, e.g. New Objective Name.
description: This will be the text displayed underneath the label that provides additional information to the user, e.g. Type the name of the objective here.
type: This is a required property. It determines what the user can put into the parameter field.
text: You can type text into this field
select: You can select one object.
multiselect: You can select multiple objects
checkbox: A box where you can mark a value as true or false
object: This is a required property for the select and multiselect type. It is used to reference objects in ClearPoint. Examples of objects include ‘measure’ and ‘periodGroup’. More examples of objects can be found on the ClearPoint API documentation.
default: This is an optional property. It can be used to preset a value in the parameter field.
Steps
Steps are the second main component of a custom script. They are the action steps that the script performs. Steps leverage the parameters described above and the ClearPoint API to make widespread changes.
name: This is a required property. We recommend naming it something descriptive.
repeat: This is required for steps that repeat over a list, e.g. the list of scorecards to which you want to add each objective.
index: This property complements the repeat portion of the step.
endPoint: This is a required property. This instructs the script on where to interact with the ClearPoint server. A list of endpoints can be found through the ClearPoint API documentation.
method: This is a required property. This is the type of action the step will perform. There are five commonly used actions:
GET: Retrieve a list of objects
POST: Create a new object
PUT: Update an existing object
DELETE: Remove an existing object
JOIN: Combines two results as one. Learn more about what you can JOIN through our bulk copy forward script in the Custom Script library.
payload: For certain methods, such as POST and PUT, the payload will pull in the values you want added to the object.
result: This is the product of your step. In this example, it is the list of objectives added to the selected scorecards.
filter: This is available and optional for GET requests. It allows you to refine the list of objects that are retrieved. Three components are required for a filter:
fieldName: The part of the object for which you’re filtering e.g. Name
value: The target criteria of the filter. Often, it is the value inputted into the parameter.
comparator: How the part of the object you’re filtering for relates to your value. These are the options:
eq: filters for exact matching value
neq: filters out all matching value
gt: filters for results greater than value
lt: filters for results less than value
gte: filters for results greater than or equal to value
lte: filters for results less than or equal to value
lk: filters for results that contain value
nlk: filters out results that contain value
We recommend reviewing the custom script on deleting measures in the Custom Script Library to learn more about filter functionality.
Create a script
This example will walk through running a script that help you change notification email options.
Click on Automation from the Control Panel
Select Scripting under Scripting & Bulk Changes
Click on the Plus icon
Under Name, enter the name of the script, in this example, ‘Change notification email options’.
We suggest you enter a detailed Description so anyone who has access to Scripts can understand what this Script is meant to be used for.
Under Script, enter the JSON script you are going to use
We are going to use the following example from the Custom Script Library.
Navigate to the Parameter Preview tab
Select which Users to update permissions
Choose how the users will receive Notifications, in this example, we are going to enter “Email”
Navigate to the Step Preview tab
Click Save
Run a Script
Click on Automation from the Control Panel
Select Scripting under Scripting & Bulk Changes
Locate the Script you want to run, in this example, ‘Change notification email options’.
Click on Run Script
Select which Users to update permissions
Choose how the users will receive Notifications, in this example, we are going to enter “Email”
Click on Preview
You can click on the Expand icon to see more details
Once you are done with your changes, click Run
Confirm you wish to proceed by clicking the Run button
Troubleshooting
Here are some common errors that you may encounter when you run Custom Scripts.
The JSON above is invalid: There is a typo somewhere in your script. Common culprits tend to be missing commas, brackets, and quotation marks.
Invalid repeat variable: One of the steps is repeating over a list that isn’t actually a list. It may just be text or a single object. Check your parameters.
Parameters do not display: A parameter is being used in an incorrect way. Check your parameters and how they are leveraged during the steps.
Note: Custom Scripts have a limit of 2,500 changes per template.