Configure Custom Scripts

Custom Scripts allow collecting specified data from Metric Insights and distributing it via bursts and alerts on various Notification Schedules.  

1. Create New Custom Script

Access Admin > System > Custom Scripts

The list page containing all Custom Scripts available in the system opens.

  1. Below the grid, click [+ Custom Script]
  2. Choose External Application
  3. Select a User
  4. [Save]

2. Add Parameters

Access the Info tab

Parameters are Custom Scripts' variables that can be assigned different values. To add a Parameter:

  1. [+ Add Parameter]
  2. Enter a Parameter Name
  3. Choose a Parameter Type
  4. Optionally, provide a Default Value
  5. Optionally, constrain Available Values
  6. Specify whether or not the Parameter is Required
  7. [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:

  1. [+ Add Parameter Set]
  2. Enter a Parameter Set Name
  3. Enter values for the Parameters
  4. Specify whether or not this Parameter Set is Default
  5. [Save]

4. Enter Custom Script

Access the Editor tab

  1. Enter your script's code
    • Access Script Parameters using dot notation: customScript.parameters.<parameter name>
  2. Choose a Parameter Set
  3. [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:

  1. [+ Add Script]
  2. Script name: choose a Custom Script
  3. Choose a Parameter set
  4. [Save]
  5. The schedules on which the Custom Script will be executed are displayed on the Associated Schedules tab of the Custom Script
Slack Burst Example

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:

  1. Send a request to the Dataset API to obtain a list of available Dataset
  2. Iterate over the Datasets list to find the needed Dataset by name
  3. Iterate over the Dataset's instances to find the instance, whose date is equal to yesterday
  4. Send the Dataset instance's data to a Slack channel

To be able to reproduce this use case, connect your Slack account to MI:

  1. Set Slack integration in the MI application
  2. Configure access to the MI data

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+:

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

  1. 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
  2. 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.

3.1. Validation and Main Functions

Access the Editor tab

  1. Validation of the datasetName and channel parameters
  2. 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: uses sendSlackMessage 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)
  3. 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

  1. 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
  2. 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
  3. 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

  1. 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
  2. End Script execution
  3. Log error message if no Dataset was found

4. Run Script

  1. Choose a Parameters Set
  2. [Run Script]
  3. Sends the Burst to the Slack channel
  4. Burst Name
  5. Burst Description
  6. Tile Name
  7. Last Measurement Value and Time (for Metrics)
  8. Tile Description
  9. Preview Image