Configure Custom Scripts

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

Table of contents:

  1. Create New Custom Script
  2. Add Parameters
  3. Add a Parameter Set
  4. Enter Custom Script Code
  5. Set a Schedule
  6. Slack Burst Example
    1. Open Slack Burst Custom Script
    2. View Parameters and Parameter Sets
    3. View Custom Script Code
      1. Validation and Main Functions
      2. Finding the Dataset and Instance by Name and Date
      3. Sending Dataset Data to Slack
    4. Run Script

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 [+ New Custom Script]
  2. Name: Enter a name for the Custom Script
  3. External Application Name: Choose an External Application to automatically generate an API token for the Custom Script
  4. Authentication User: Choose a User on whose on behalf the Custom Script will act
  5. [Save]

NOTES:

  • The API token is generated automatically on the background using the External Application's credentials and the Authentication User's username, and is required for the Custom Script to perform any actions in Metric Insights.
  • The External Application settings control the Custom Script's access to the User API calls and to all API calls from external websites.
  • The Custom Script will act on behalf of the Authentication User; e.g., if the Custom Script creates a new element, it will be displayed as created by the Authentication User.

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. Name: Enter a name for the Parameter
  3. Type: Choose a value type for the Parameter
  4. Default Value (optional): Enter a default value for the Parameter
  5. Available Values (optional): Enter a comma-separated list of available values
  6. Required: Activate the checkbox to make the Parameter 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. Parameter Set Name: Enter a name for the Parameter Set
  3. Enter values for the Parameters
  4. Specify whether or not this Parameter Set is Default
  5. [Save]

4. Enter Custom Script Code

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. [Save and Enable]
  4. [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 that will run on the Notification Schedule
  3. Parameter Set: Choose a Parameter Set with which the Custom Script will run
  4. [Save]
  5. The schedules on which the Custom Script will be executed are displayed on the Associated Schedules tab of the Custom Script

6. 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 Datasets
  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:

6.1. Open Slack Burst Custom Script

Access Admin > System > Custom Scripts

Find the Slack Burst Custom Script and open it.

6.2. View Parameters and Parameter Sets

  1. The Parameters that are used in the Slack Burst Custom Script:
    • burstDescription: A text message that is sent to the specified Slack channel
    • burstName: A "header" of the message that is sent to a Slack channel
    • channel: The Slack channel where the message is sent to (to see the list of available channels, access Admin > Distribution > Slack Integration > Channel tab)
    • datasetName: The 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

6.3. View Custom Script Code

For more details on MI Dataset API, see Dataset API.

6.3.1. Validation and Main Functions

Access the Editor tab

  1. Validation of the datasetName and channel parameters
  2. Functions that send information to the Slack channel:
    • sendMessagetoSlack(): Sends a request to  <hostname>/api/get_image?element=<element ID>&dimension_value=<dimension ID>&share=Y&slack=Y&channel=<slack_channel_name>, which triggers a message to the Slack channel with the 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 the MI API)
  3. formatDate(): 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

6.3.2. Finding the Dataset and Instance by Name and Date

  1. Sending a GET request to /api/dataset and performing 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 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 /api/dataset_data?dataset=<Dataset ID> to obtain an object encapsulating the Dataset's instances

6.3.3. Sending Dataset Data to Slack

  1. Sending GET request to /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

6.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