Access the API - Custom Scripts

Start by logging into ClearPoint Strategy at [app.clearpointstrategy.com/#/home](http://app.clearpointstrategy.com/#/home)

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](https://support.clearpointstrategy.com/en/articles/8754378-automation-integration-bulk-changes).

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.

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](https://www.w3schools.com/js/js_json_syntax.asp).

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](https://support.clearpointstrategy.com/en/articles/8650000-automation-integration-access-the-api-getting-and-using-clearpoint-api-keys). **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.

This example will walk through running a script that help you change notification email options.