Scripts

There are currently two types of script you can use in SquaredUp:

  • Tile Data scripts (JavaScript): Used to get data to display on a tile.
  • Monitor Condition scripts (JavaScript): Used to write conditions that determine the monitored state of a tile based on its data.

Tile Data scripts

Tile Data scripts allow you to fetch data and display it on a tile. Tile Data scripts require an async function getData(params, api) entrypoint that returns the tile data, usually in data stream format, either as a result of invoking a data stream or by calling the api.toStreamData function to convert the tile data to data stream format. Data should be formatted as a data stream before it can be used in visualizations in SquaredUp. If possible, the api.toStreamData function should always be called. If it is not called, SquaredUp will attempt to convert the data, but then metadata cannot be specified.

See Data Streams

Adding a Tile Data script

  1. In SquaredUp browse to Settings > Advanced > Scripts.
  2. Click Add script.
  3. Display name:
    Enter a name for your script. This helps you to identify this script in the list of your scripts.
  4. Script type:
    Select Tile Data (JavaScript).
  5. Script editor:
    Enter your script. By default, you will see an example script in the editor. The example will help you to understand how to structure your script.
  6. The params object contains:
    • params.timeframe – the timeframe (object) for which tile data should be read.
    • params.config – the configuration object specified when configuring the +Run Script data stream.
    • params.targetNodes – the tile scope's target nodes (array of node objects or [] if no scope).
    • params.context – the context object containing: 
      {
“tenant“: “ten-XecW75nBaFpw3JnepDuS“,  # the tenant id (mandatory)
“dashboard“: “dash-dHD9A4q3Hv8xOsKtJtQ8“,  # the dashboard id (optional)
“workspace“: “space-rjd73f8s9f204azocm9d“  # the workspace id (optional)
}
  7. The api callback function object contains:
    • async function post(path, body) – the async post callback function can be used to invoke a data stream (/datastreams/requests path), query the graph (/query path), or make a WebApi request (/request path) from within a script. This callback function is unlikely to be called from a Monitor Condition script but is often needed by a Tile Data script.
    • async function toStreamData(data, { rowpath = [], metadata = [] } = {} ) – the async toStreamData callback function can be used to convert non-data stream formatted data into data stream formatted data for use with data stream visualizations. This callback function is unlikely to be called from a Monitor Condition script but is often needed by a Tile Data script.
    • async getColumnData(data, columnName) – the getColumnData callback function can be used to obtain the rows of the specified column of data stream formatted data (i.e. the data parameter must be data stream formatted data). This callback function is very unlikely to be called from a Tile Data script but is often needed by a Monitor Condition script.
  8. When have finished editing your script, click Save.

Using a Tile Data Script

  1. Add or Edit a dashboard and go into the configuration of a tile.
  2. The Run Script data stream appears under SquaredUp in the tile editor scope. Alternatively, you are able to scope to an object and then select the Run Script data stream. If you have scoped to one or more objects, the script's params.targetNodes array argument will contain the target object(s).
  3. Display Name:
    Enter a name for the new data stream.
  4. Script:
    Select the script that you want to use from the dropdown.
  5. Configuration (optional):
    params.config argument to pass the script. You would normally leave this empty, it can be used if you want to parameterize your script.
  6. Click Save.

Monitor Condition scripts

This feature is exclusively available with a PRO plan.

Monitor Condition scripts give you unlimited flexibility and can be written to monitor any data in any way. Monitor Condition scripts require an async function getState(params, api) entrypoint that must return the tile monitor’s state (error, warning, success, or unknown) and may return the monitor’s scalar value that caused the state.

See Monitoring

Adding a Monitor Condition script

  1. In SquaredUp browse to Settings > Advanced > Scripts and select Add new script.
  2. Display name:
    Enter a name for your script. This helps you to identify this script in the list of your scripts.
  3. Script Type:
    Select Monitor Condition (JavaScript).
  4. Script editor:
    Enter your script. By default, you will see an example script in the editor. The example will help you to understand how to structure your script.
  5. The params object contains:
    • params.data – the tile data in data stream format.
    • params.config – the script configuration specified when enabling script monitoring within the tile editor.
  6. The api callback function object contains:
    • async function post(path, body) – the async post callback function can be used to invoke a data stream (/datastreams/requests path), query the graph (/query path), or make a WebApi request (/request path) from within a script. This callback function is unlikely to be called from a Monitor Condition script but is often needed by a Tile Data script.
    • async function toStreamData(data, { rowpath = [], metadata = [] } = {} ) – the async toStreamData callback function can be used to convert non-data stream formatted data into data stream formatted data. This callback function is unlikely to be called from a Monitor Condition script but is often needed by a Tile Data script.
    • async getColumnData(data, columnName) – the getColumnData callback function can be used to obtain the rows of the specified column of data stream formatted data (i.e. the data parameter must be data stream formatted data). This callback function is very unlikely to be called from a Tile Data script but is often needed by a Monitor Condition script.
    • A data stream column always has three properties: raw, value, and formatted. The value property is the one to use in scripts as it contains the column’s value as a JavaScript type.
  7. Return value format:
    An object with a mandatory state property and an optional scalar property. The scalar property value is the value that caused the returned state, e.g. the value that caused the error state.
    Example monitor condition script return values: 
    // state must be one of 'error', 'warning', 'success', or 'unknown'
return { state: 'unknown' };
return { state: 'success', scalar: 36.53 };
return { state: 'error', scalar: 105 };
return { state: 'warning' };

Using a Monitor Condition script

  1. Add or Edit a dashboard and go into the configuration of a tile.
  2. Configure the data that you want to run the script against in the Data editor tab.
  3. Select the Monitoring tab and then switch Monitoring to on.
  4. Monitor type:
    Select script.
  5. Evaluate by:
    When a column is selected, the script will run multiple times for each unique value found in the selected column.
  6. Condition script:
    Select the Monitor Condition script to run from the dropdown.
  7. Script configuration (optional):
    params.config argument to pass the script. For example, you could use configuration to specify thresholds for the script to use. This allows you to reuse the script for multiple tiles with different thresholds (or other configuration), and avoids having to hardcode values that may change within the script.
  8. Frequency:
    How often you want to call the script.
  9. Click Save.

Was this article helpful?

Have more questions or facing an issue?
Submit a ticket