Tile Data Scripts

Most of the time, you'll be able to use the data streams provided by a plugin to visualize the data how you want. However, there may be circumstances where you want to fetch data that isn't provided by the available data streams. In cases such as these, you can instead use a tile script.

These scripts scripts allow you to write your own logic to query the map and data streams in any way you want, and give you the ability to manipulate data in ways that data streams can't. For example, you can create tile scripts to:

• Combine multiple graph queries.
• Combine multiple data streams.
• Make data streams dependent on the results of a graph query (and vice versa).
• Filter graph data and data streams in ways you normally can’t.
• Further manipulate your data before visualizing it.

Script syntax

Tile scripts are written in JavaScript, and as such provide the unlimited flexibility to manipulate any data in any way. The following information tells you how to define a script and details the available parameters.

Function definition

Tile scripts simply consist of a single async function with the following signature. The function must be named getData and passed two parameters; params and api:

async function getData(params, api)

Return value

The return value must always be 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. If it is not called, SquaredUp will attempt to convert the data to data stream format, but then metadata will not be specified.

The api.toStreamData function must be passed two arguments; a data object and a meta data object.

For example, the following script contains timeseries data for a line graph with two lines:

async function getData(params, api) {
	const rows = [
		{ t: 1647080000000, s: "a", v: 1 },
		{ t: 1647081000000, s: "a", v: 2 },
		{ t: 1647082000000, s: "a", v: 3 },
		{ t: 1647083000000, s: "a", v: 2 },
		{ t: 1647084000000, s: "a", v: 1 },
		{ t: 1647085000000, s: "a", v: 0 },
		{ t: 1647080000000, s: "b", v: 0 },
		{ t: 1647081000000, s: "b", v: 3 },
		{ t: 1647082000000, s: "b", v: 1 },
		{ t: 1647083000000, s: "b", v: 4 },
		{ t: 1647084000000, s: "b", v: 3 },
		{ t: 1647085000000, s: "b", v: 2 }
	];
	const metadata = [
		{ "name": "t", "displayName": "Timestamp", "shape": "date", "role": "timestamp"},
		{ "name": "s", "displayName": "Series", "shape": "string", "role": "label"},
		{ "name": "v", "displayName": "Value", "shape": "number", "role": "value"}
	];
    return api.toStreamData(rows, { rowPath: [], metadata } );
}

Parameters

The params and api parameters are sued to interact with the tile data the contain the following properties and functions.

params

{
“tenant“: “ten-XirV62mDaTpw2KmrvCiH“, # the tenant id (mandatory)
“dashboard“: “dash-dHD9A4q3Hv8xOsKtJtQ8“, # the dashboard id (optional)
“workspace“: “space-rjd73f8s9f204azocm9d“ # the workspace id (optional)
“editing”: false # whether the tile is being edited (optional)
}

api

Adding a tile data script

1. Navigate to Settings > Advanced > Scripts.
2. Click Add script.
3. Complete the following in the Add script window:
   1. Display name:
      Enter a name for your script. This helps you to identify this script in the list of your scripts.
   2. Script type:
      Select Tile Data (JavaScript).
   3. 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.

4. Click Save. The script is created and added to the table.

Using a tile data script

1. Add or Edit a dashboard and go into the configuration of a tile.
2. Select the Data Stream tab and do the following:
   1. Depending on your script, select either the scoped or unscoped Run Script data stream from the SquaredUp data source (the scoped version displays the objects tab when selected).

   2. Click Next.
3. If you selected the scoped data stream, do the following on the Objects tab:
   1. Select the objects you want to scope to on the Objects tab. The script's params.targetNodes array argument will contain the target object(s) you select.
   2. Click Next.
4. Complete the following on the Parameters tab:
   1. Display Name:
      Enter a name for the new data stream.
   2. Script:
      Select the script that you want to use from the dropdown.
   3. 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.
5. Click Save.

Examples

The following examples illustrate various use cases for creating and using tile scripts.

Average CPU Performance

The following script queries the SquaredUp sample API to retrieve average CPU performance.

Copy
async function getData(params, api) {
    // Example: get 100 server performance datapoints by making a web request using the '/request' api endpoint
    const requestConfig = { method: 'get', url: 'https://sampleapi.squaredup.com/integrations/v1/server-perf?datapoints=100' };
    const serverPerformance = await api.post('/request', requestConfig);

    // Set row metadata
    const rows = serverPerformance.performance;
    const metadata = [
        { "name": "timestamp", "displayName": "Timestamp", "shape": "date", "role": "timestamp"},
        { "name": "object.name", "displayName": "Series", "shape": "string", "role": "label"},
        { "name": "metrics.cpu.average", "displayName": "Avg CPU", "shape": "number", "role": "value"}
    ];

    // Note: no need to call api.toStreamData when returning data directly from invoking a data stream
    return api.toStreamData(rows, { rowPath: [], metadata } );
}​​​​

When you add select this script in the Parameters for a Tile data data stream, SquaredUp automatically created a Line graph from the data.

Sales Transactions

The following script queries the SquaredUp sample API to retrieve sales transactions data.

async function getData(params, api) {
    // Example: get 100 sales transaction datapoints by making a web request using the '/request' api endpoint
    const requestConfig = {
        method: 'get',
        url: 'https://sampleapi.squaredup.com/integrations/v1/sales-transactions?100'
    };
    const salesTransactions = await api.post('/request', requestConfig);

    // Set column metadata
    const columns = ['closeDate', 'status', 'stageName', 'dealSource', 'account', 'accountManager', 'currency', 'amount'];
    const metadata = columns.map(column => ({
        name: 'transactions.' + column
    }));

    // Note: no need to call api.toStreamData when returning data directly from invoking a data stream
    return api.toStreamData(salesTransactions, {
        rowPath: ['transactions', 'amount'],
        metadata
    });
}

When you add select this script in the Parameters for a Tile data data stream, SquaredUp displays this data in a Table visualization.

Was this article helpful?