Soracom Lagoon

Using Variables to Switch Data Displayed in the Panel

Overview

By default, a panel can display data from only one device. Creating separate panels for each device can quickly consume screen space and require significant effort. To address this, variables allow dynamic data visualization.

With Variables, you can achieve:

• Switching devices or series displayed in a panel.
• Repeatedly displaying series in the same format within a panel.
• Repeatedly displaying panels in the same format within a dashboard.
• Repeatedly displaying rows in the same format within a dashboard.

Default Variables

Soracom Lagoon inserts the following default variables into newly created dashboards:

• $resource_types: Select the resource type to display.
• $groups: Select the group to display.
• $resources: Select the resource to display.
• $properties: Select the property to display.

Global Variables

Soracom Lagoon also supports the global variables provided by Grafana. For more information, refer to the Grafana documentation on Global Variables.

Variables Settings

In Dashboard settings > Variables, you can add, duplicate, or delete variables.

There are several variable types, but in Soracom Lagoon, three types are commonly used:

• Query
• Custom
• Text box

Common Parameters

General

• Name: The name of the variable. (Max. 50 characters)
• Label: Optional display name.
• Description: Displays when hovering over the label above the dashboard.
• Show on dashboard: Choose from Label and value, Value, or Nothing.

Selection options

• Multi-value: Enables selecting multiple values simultaneously.
• Include All option: Adds an All option to include all variable values.

Query

The Query variable type lets you create a variable representing a resource ID or name using a regular expression. For example, you can create variables that include the names of all IoT SIMs owned by an operator.

Query options

• Data source: In Soracom Lagoon, only "Harvest" is supported as a data source.

• Query: The type of values returned is controlled by the query. Currently there are four main queries supported by Soracom Lagoon:

  1. Resource types - by using the query resource_types the variable will return the available resource types.
     • Air, Sigfox, Device, Demo
  2. Groups - by using the query groups the variable will return the available groups.
     • An All Groups option is automatically included.

  3. Resources - by specifying one of the resource types, the variable will return the available resources of that type.

     • For example, demo will return Device-1, Device-2, etc. subscribers will return the available SIMs.
     • The available resource type queries are listed below:

     • Resource Type	Query String
       Air	subscribers
       Sigfox	sigfox_devices
       Inventory Device	devices
       Demo	demo

     • The resources turned by the query can be restricted to a group by providing the group ID as a query parameter. For example, devices?group=deadbeef-ffff-ffff-ffff-ffffffffffff.
  4. Properties - by specifying a resource type and a resource ID seperated by || the variable will return the available properties of that resource.
     • For example, demo||Device-1 will return temperature, humidity, etc.
     • For most Soracom resources, the resource name and ID are not the same. For example, the resource name for a SIM is the IMSI, but the resource ID is the SIM ID. To get the properties of a SIM, you must use the SIM ID as the resource ID. e.g. subscribers||123451234512345
     • An -All- option is automatically included.

       As variables resolve to the ID of the selected value, it is possible to chain variables together, referencing another variable in the query. For example, to get the properties of a specific device, you can use the query devices||$devices, where $devices is another variable that contains a device ID. The built-in variables make extensive use of variable chaining.

       https://g-v3.lagoon.soracom.io

       

• Regex: Use regular expressions to specify or extract target resources for the variable. For example:
  • To filter SIMs with IMSIs starting with 99999, enter /^99999/.
  • To filter resources with names starting with Device-, enter name/Device-/.
• Sort: Specify sorting for variable values: Disabled, Alphabetical (asc/desc), Numerical (asc/desc), or Alphabetical (case-insensitive, asc/desc).
• Refresh: Choose when to refresh variable values (On dashboard load or On time range change).

Variable values can be previewed in the Preview of values section.

Custom

With the "Custom" variable type, you can create variables with arbitrary strings.

Custom options

• Values separated by comma: Enter the strings to be used as variable values, separated by commas (,). For example, Device-1,Device-2,Device-3,Device-4,Device-5.

Preview variable values in the Preview of values section.

Text box

With the "Text box" variable type, you can input variable values directly at the top of the dashboard.

Text options

• Default value: Specify a default value if applicable.

Query Settings

In the panel editor, you can configure queries to use variables. To learn more, refer to Using Query to Display Data on the Panel.

Panel Settings

In the panel editor, you can configure Soracom Lagoon to dynamically add panels to a dashboard based on variable values. Variables dynamically change queries across all panels in a dashboard. To configure repeating panels:

1. Open the dashboard containing the panel you want to edit.
2. Click the panel title and select Edit.
3. In the display options pane, click Panel options > Repeat options.
4. Select a direction:
   • Choose horizontal to arrange panels side-by-side. Soracom Lagoon adjusts the width of repeated panels. You cannot mix other panels in the same row with a repeated panel.
   • Choose vertical to arrange panels in a column. Repeated panels will have the same width as the original panel.
5. Reload the dashboard to propagate changes to all panels.

You can also use variables in the panel title or description by setting the Title or Description fields.

Row Settings

Soracom Lagoon supports dynamically adding rows to a dashboard based on variable values. To configure repeating rows:

1. Open the dashboard containing the panel you want to edit.
2. In the Add a panel dialog box, click Add a new row.
3. Hover over the row title and click the cog icon.
4. In the Row Options dialog box, set a title for the row and select the variable for which you want to add repeating rows.
5. Save your changes.

Example Usage

In this example, you will create repeated panels and rows using variables in Soracom Lagoon. The Demo sample data has the following structure:

• Resource Type: demo
• Resources: Device-1, Device-2, Device-3, Device-4, Device-5
• Properties: Each resource contains temperature and humidity.

Create a New Dashboard

1. Log in to the Soracom Lagoon console.
2. From the sidebar, click the Dashboard icon.
3. Click the New dropdown button.
4. Select New Dashboard.

Delete the Built-in Variables

In order to practice configuring the variables, we will first delete the built-in variables.

1. Navigate to Dashboard settings > Variables and click the Delete icon next to each of the following variables:
   • $resource_types
   • $groups
   • $resources
   • $properties

Create a Query Variable for Devices

1. Navigate to Dashboard settings > Variables and click Add variable.
2. Select Query as the variable type.
3. Configure the following options:
   • Name: devices
   • Data source: Harvest
   • Query: demo
   • Regex: name/Device-/
4. Check the Multi-value option.
5. Click Apply.

Create a Custom Variable for Properties

1. Navigate to Dashboard settings > Variables and click Add variable.
2. Select Query as the variable type.
3. Configure the following options:
   • Name: properties
   • Data source: Harvest
   • Query: demo||$devices
   • Regex: name/humidity|temperature|-All-/
4. Check the Multi-value option.
5. Click Apply.

Configure Queries Using Variables

1. If you are on the Variables page, click "←" (Go back) or press the Esc key to return to the Dashboard editor.
2. Click Add panel and select Add a new panel.
3. In the Query tab, set the following:
   • For Resource Type, select Demo.
   • For Group, select All Groups.
   • For Resources, select $devices.
   • For Property, select $properties.

Enable Repeated Panels

1. In the panel editor, navigate to Panel options > Repeat options.
2. Configure the following options:
   • Title: Set to $devices $properties.
   • Repeat by variable: Select properties.
   • Repeat direction: Choose Horizontal.
3. Click Apply to save the panel settings.

Create a Repeated Row for Devices

1. Add a new row to the dashboard by clicking Add panel and selecting Add a new row.
2. Hover over the row title and click the cog icon to open Row options.
3. Configure the following options:
   • Title: Set to $devices.
   • Repeat for: Select devices.
4. Click Update to apply the settings.

See the Result

After completing these steps, the dashboard will dynamically create:

• Repeated panels for each metric (temperature and humidity) within each row.
• Repeated rows for each device (Device-1, Device-2, Device-3, Device-4, and Device-5).

You can control your dashboard by selecting values in the devices and properties variables.

This setup ensures a flexible and scalable visualization of your data with minimal manual configuration.