Custom Scripts Workflow Playbook

This article describes in detail all the steps to take a Custom Script from an empty shell to a scheduled, running automation in Metric Insights. A typical implementation is cross-role: an MI Admin creates and secures the script shell, a Script Developer writes and debugs the code, and Security reviews the privileges of the Authentication User the script acts as. Use this playbook to sequence the existing how-to articles, assign ownership at each phase, and confirm completion before moving on.

PREREQUISITES:

  • The Custom Scripts feature must be enabled in your environment via the CUSTOM_SCRIPT_ENABLED System Variable.
  • System administrator privileges to access, create, edit, and run Custom Scripts.
  • An External Application configured with valid API credentials.

Table of Contents

Target Personas

NOTE: One person can hold multiple roles. The workflow still works as long as each responsibility is explicitly assigned.

  • Metric Insights Admin: Enables the feature, creates the script shell, assigns the External Application and Authentication User, and schedules or runs the script.
  • Script Developer: Writes and debugs the JavaScript code using the customScript object and the Metric Insights API.
  • Security / IAM: Reviews the privileges of the Authentication User, since the script's API calls and actions run with that user's permissions.

Workflow Overview

A Custom Scripts implementation typically follows these phases:

  1. Create the Custom Script shell and assign the External Application and Authentication User.
  2. Define Parameters and Parameter Sets (assign a default Set, use  the password type for secrets; optionally, use CS Helper Custom App).
  3. Write and debug the script code (use the built-in methods, properties, and debug mode; use MI API requests).
  4. Schedule, run, and distribute output (use Notification Schedules).
  5. Advanced usage examples (Tableau User/Group permission sync, secure external APIs, Snowflake OAuth examples).

Pre-Work

Complete the Decision Gates section in Best Practices & First Principles: Custom Scripts before starting Phase 1. That document helps decide whether a Custom Script is the right tool for the goal, since some outcomes have a simpler built-in path.

Tip: If the only goal is to send content to a Slack channel, a Custom Script is usually unnecessary. Use the built-in bursting feature instead. See Bursting to a Slack Channel.

Phase 1: Create the Custom Script Shell

NOTE: Only Admin Users can access Custom Scripts, and the feature must be enabled via the CUSTOM_SCRIPT_ENABLED System Variable.

Who: Metric Insights Admin (with Security review of the Authentication User).

Create the script and make the two security decisions that govern everything the script can do: which External Application generates the API token, and which Authentication User the script acts as. The script inherits that user's privileges, so choose an account scoped to only the operations the script needs.

References:

  • Create new Custom Script (create the script with a Name, select an External Application, and assign an Authentication User).
  • Set up API Access (create the External Application first if one does not exist).

Warning: The script's API calls and actions run with the full privileges of the Authentication User. Have Security review that account before the script is enabled.

Tip: Checklist for Phase 1 completion:

  • The script appears in Admin > Custom Scripts with a Name.
  • An External Application and an Authentication User are assigned.
  • Security has confirmed the Authentication User's privilege scope.

Phase 2: Define Parameters and Parameter Sets

Who: Metric Insights Admin and Script Developer.

Define the inputs the script needs as Parameters, then save reusable value combinations as Parameter Sets. Each parameter has a Type (string, number, password, or boolean); use the password type for secrets so the value is masked in logs. Mark one Parameter Set as the default so it is used when the script runs on a schedule.

Reference: Add Parameters and create Parameter Sets for the Custom Script.

NOTE: The optional Setup CS Helper Custom App can auto-populate Parameters, migrate Parameter Sets between scripts, and compare or troubleshoot Parameter configuration. It requires the setup-cs.zip assets from [email protected] and an External Application with Application Can Manage Users.

Tip: Checklist for Phase 2 completion:

  • Every input the script reads exists as a Parameter with the correct Type.
  • Secrets use the password type.
  • At least one Parameter Set is marked as the default.

Phase 3: Write and Debug the Script Code

Who: Script Developer.

Write the JavaScript in the Editor tab using the customScript object: call runApiRequest to reach the Metric Insights API with the generated token, read inputs from parameters, write to the run output with log and error, and always finish with close. Test iteratively in debug mode before enabling the script.

References:

Tip: Checklist for Phase 3 completion:

  • The script runs cleanly in debug mode with the default Parameter Set.
  • Every code path ends by calling close.
  • Errors are surfaced through error rather than failing silently.

Phase 4: Schedule, Run, and Distribute

Who: Metric Insights Admin.

Set Custom Script is to Enabled, then either run the script manually from the editor (selecting a Parameter Set) or attach it to a schedule. Review each execution in the Run Log.

Reference: Enable Custom Script and Set a Schedule.

NOTE: When a script is triggered by a Notification Schedule and no specific set is named, the Parameter Set marked as default is used.

Tip: Checklist for Phase 4 completion:

  • The script is set to Enabled.
  • A manual run completes and the output is visible in the Run Log.
  • The schedule (if used) triggers the script with the intended Parameter Set.

Phase 5: Advanced Usage Examples

Once the basic workflow is in place, apply the same pattern to richer integrations. A common worked example is generating and delivering content to Slack from a script.

Basic references:

Proven use cases to model richer integrations on:

  • Sync Tableau User/Group Permissions: Synchronize content access between Tableau and Metric Insights, so Users and Groups with access to Tableau content receive the same access in MI once the content has been recreated in the system.
  • Configure Snowflake OAuth: Securely manage Snowflake OAuth authentication within an App — users authenticate with Snowflake, retrieve tokens, and store them as App Entities in Metric Insights.
  • Secure External API Integration: Integrate with external APIs that require authentication, such as retrieving data from Azure Data Lake Store (ADLS), and pass the API response securely to an App so users can view external data in Metric Insights.

Tip: Final security checklist:

  • Secrets are stored as password parameters, never hardcoded in the script body.
  • The Authentication User's privileges match only what the script requires.
  • Run Log output does not expose sensitive values.