Working with CMS Scripts

CMS Scripts gives you a workspace in the CMS tool for running custom administrative scripts, with a full audit trail of every execution. It sits between the code playground and a full job pipeline: quicker to use than building a dedicated job for a one-off task, but with the retry handling and history that the code playground does not provide.

note

CMS Scripts is built on the job execution flow described in Technical reference. Each script run is recorded as a job.

Enabling the Scripts tool

Before any script can run, an administrator must enable script execution and provide a task host.

To enable the Scripts tool:

1. Go to Sites & Settings > Legacy Settings > Brightspot Scripts.
2. Toggle on the Enabled setting.
3. In the Task Host field, type the hostname or IP address that is allowed to run script jobs.

Using the following table as a reference, complete the remaining fields as needed.

Field	Description
Maximum Number Of Retries	The number of times a script job retries after a retryable failure before it is treated as having exceeded the maximum retries. Defaults to 20.
Minimum Number Of Seconds Between Retries	The minimum delay between retry attempts. Defaults to 3 seconds.
Minimum Number Of Seconds Between Polls	The minimum delay between polling attempts for a script job that is waiting on an external result. Defaults to 3 seconds.

Running a script

Once the Scripts tool is enabled, every script implementation available on the site appears as its own form in the Scripts area.

To run a script:

1. In the header, click .
2. Expand Developer, and select Scripts.

3. Complete the fields for the script you want to run.
4. Click Execute.

The script is queued as a job and runs asynchronously, so the browser is not blocked while it runs.

note

Click a script's heading to collapse or expand its form. The collapsed state is saved in the browser and persists across page reloads.

Viewing script jobs

Every script run is recorded as a job, including its status, duration, and the user who ran it.

To view script jobs:

1. In the Scripts area, click View All Jobs.

An overlay opens showing a paginated list of every script job.

2. Click a job's status to open the full job on its own page.

Running scripts in batch

A batch scripts profile groups one or more scripts so they can be run together in a single job.

To run a batch scripts profile:

1. Go to the Batch Scripts search page, in the Developer cluster in the hamburger menu.
2. Open the batch scripts profile you want to run.
3. In the Execute widget, click Execute.

A message confirms the number of scripts queued. Click View All Jobs in the same widget to view the resulting jobs.

Getting notified about script jobs

You can subscribe to be notified when a script job reaches a particular outcome, instead of checking the Scripts area for results.

To subscribe to script job notifications:

1. Go to your notification subscriptions in the CMS tool.
2. Add a Script Job subscription.

Using the following table as a reference, complete the fields as needed.

Field	Description
States	The script outcomes to be notified about, such as Success, Max Retries, or Permanent Failure. Leave blank to be notified about every possible outcome.
Scripts	The specific scripts to be notified about. Leave blank to be notified about every script.

The notification includes the script, its status, the queue date, the duration, and the user who ran it, along with a link to the full job.

Controlling who can run scripts

A CMS Scripts permission on a user's role controls which scripts that role can access.

To configure the CMS Scripts permission for a role:

1. Go to the user role's permissions.
2. Under CMS Scripts, select one of the following options.

Option	Effect
All	The role can run every script. This is the default.
None	The role cannot run any script.
Only	The role can run only the selected scripts.
All Except	The role can run every script except the selected ones.