Configure Custom Scripts
Custom Scripts allow collecting specified data from Metric Insights and distributing it via bursts and alerts on various Notification Schedules.
- For details on writing Custom Scripts, see Basic Practices for Custom Scripts Developers and Slack Burst Example section of this article
1. Create New Custom Script
Access Admin > System > Custom Scripts
The list page containing all Custom Scripts available in the system opens.
- Below the grid, click [+ Custom Script]
- Choose External Application
- Select a User
- [Save]
2. Add Parameters
Access the Info tab
Parameters are Custom Scripts' variables that can be assigned different values. To add a Parameter:
- [+ Add Parameter]
- Enter a Parameter Name
- Choose a Parameter Type
- Optionally, provide a Default Value
- Optionally, constrain Available Values
- Specify whether or not the Parameter is Required
- [Save]
3. Add a Parameter Set
Parameter Sets are especially useful when a Custom Script needs to be executed with different Parameter values. They represent sets of values assigned to Custom Script's parameters. To add a Parameter Set:
- [+ Add Parameter Set]
- Enter a Parameter Set Name
- Enter values for the Parameters
- Specify whether or not this Parameter Set is Default
- [Save]
4. Enter Custom Script
Access the Editor tab
- Enter your script's code
- Access Script Parameters using dot notation:
customScript.parameters.<parameter name>
- Access Script Parameters using dot notation:
- Choose a Parameter Set
- [Run Script]
For details on writing Custom Scripts, see Basic Practices for Custom Scripts Developers.
5. Set a Schedule
Access Admin > Distribution > Notification Schedules, select a Notification Schedule, access the Run Scripts tab
To run your Custom Script on a specified schedule:
- [+ Add Script]
- Script name: choose a Custom Script
- Choose a Parameter set
- [Save]
- The schedules on which the Custom Script will be executed are displayed on the Associated Schedules tab of the Custom Script
Let's consider a more complex use case on the built-in Slack Burst example, where the Dataset's data is sent to a Slack channel via the Custom Script.
Actions performed by the Custom Script to burst to a Slack channel:
- Send a request to the Dataset API to obtain a list of available Dataset
- Iterate over the Datasets list to find the needed Dataset by name
- Iterate over the Dataset's instances to find the instance, whose date is equal to yesterday
- Send the Dataset instance's data to a Slack channel
To be able to reproduce this use case, connect your Slack account to MI:
This example demonstrates the usage of Custom Scripts; however, if you want to create a Burst to a Slack channel, a simple approach exists for MI v5.5+:
- See Bursting to a Slack Channel for details
1. Open Slack Burst Custom Script
Access Admin > System > Custom Scripts
Find the Slack Burst Custom Script and open it
2. See Parameters and Parameter Sets
- The Parameters that are used in the Slack Burst Custom Script:
- burstDescription: a text message that is sent to a specified Slack channel
- burstName: a "header" of the message that is sent to a Slack channel
- channel: a Slack channel where the message is sent to (to see the list of available channels, access Admin > Distribution > Slack Integration > Channel tab)
- datasetName: a Dataset that contains information about the Elements, whose info is sent to a Slack channel
- The provided values for Parameters are displayed upon Parameter Sets
3. See Custom Script Code
For more details on MI Dataset API, see Dataset API.
- Validation of the datasetName and channel parameters
- Functions that send information to a slack channel:
-
sendMessagetoSlack
: sends a request to<hostname>/api/get_image?element=<element ID>&dimension_value=<dimension ID>&share=Y&slack=Y&channel=<encodeURIComponent(Slack channel name)>
, which triggers a message to a Slack channel with element's information -
sendBurstHeader
: usessendSlackMessage
function to send the burst name and description in a text format (the values of burstName and burstDescription) to a Slack channel -
sendSlackMessage
: sends a text message to a Slack channel (a POST request to MI API)
-
-
formatDate
function returns Dataset's date in a human readable format and is used to display an error message if no data is found for a Dataset
3.2. Finding the Dataset and Instance by Name and Date
- Sending a GET request to the Dataset API (
<MI hostname>/api/dataset
) and perform actions on the received response data. All the next commands are executed within this function's body- The
dataset
object encapsulates all the obtained Datasets - The
instance
variable represents a single Dataset
- The
- Iterating through the obtained Datasets until a Dataset,
- When a Dataset whose name corresponds to a name from the datasetName parameter is found, its value is assigned to the
dataset
object
- When a Dataset whose name corresponds to a name from the datasetName parameter is found, its value is assigned to the
- Sending a GET request to
<hostname>/api/dataset_data?dataset=<Dataset ID>
to obtain an object encapsulating Dataset's instances
3.3. Sending Dataset Data to Slack
- Sending GET request to
<hostname>/api/dataset_data?dataset=<Dataset ID>
to obtain Dataset instance data, then:- Assigning instance data to the
data
object - Sending burst text to a Slack channel by calling
sendBurstHeader
- Iterating over collected instance data and sending it to a Slack channel
- Assigning instance data to the
- End Script execution
- Log error message if no Dataset was found