Template Scripting allows you to make sweeping changes across your account very quickly by leveraging the ClearPoint API. Template 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. This is a feature of the Enterprise Plan only.
Why use Template Scripting
Template Scripting is an extremely helpful feature for automating repetitive actions within your account. It’s designed to save you lots of time for 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.
Template Scripting 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 and start drawing value from Template Scripting. We strongly recommend starting with one of our developed scripts since they are easy to use. Here is the Template Scripting Library, which covers a variety of different functions. This library will continuously be updated.
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 Template Library. If you want to create a template 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 template 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 template 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 Template Scripting 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 template script on deleting measures in the Template Scripting Library to learn more about filter functionality.
Running a script
1) Click on the Run icon.
2) Enter the parameter values.
3) Click to preview the script.
4) Review the script
5) Click to run. A new window will appear.
6) Confirm the run.
Here are some common errors that you may encounter when you run Template 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.