Custom Scripts allows you to make sweeping changes across your account very quickly by leveraging the a 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 firstname.lastname@example.org before running your scripts. The team will be able to advise you on your script and help you avoid potential pitfalls.
In This Article
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. To recap, the recommended approach for making widespread changes to your account is Bulk Changes > Custom Script Library > Creating your own script.
Creating a script
We only encourage that the most advanced users 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 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 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.
Running a script
This example will walk through running a script that adds objectives to selected scorecards across an account. The custom script is already in the account, so we will start by clicking on the run icon.
Enter the parameter values. In this case, the parameter values are the new objective name, scorecards, and period group.
Click on Preview to preview the script.
On the Preview tab, make sure to review the script. Click on the arrow to view your changes. When you are ready, click Run. Confirm the run in the pop-up window.
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.