Welcome to Tips and Tricks for Using Dashboard Designer Add On¶

While easy to use, Dashboard Designer Add On has many techniques for creating more advanced visualizations and user interactions. This section's topics show some of these advanced techniques.

Since Dashboard Designer Add On is built using a variety of commonly-used open-source applications, you can find many answers on the Internet by searching with the keyword "grafana".

Optimizing Dashboard Performance¶

When using data sources, dashboard performance usually depends on how the data is structured and how you are retrieving it. This section presents many tips for optimizing your dashboard's performance.

It is important to plan ahead during the design phase to maximize the performance of your dashboards. Considering the points below will help ensure the best performance.

For IoT data sources, ensure the aspect's variables have similar sampling rates¶

Let's consider, for example, an asset type with this aspect: - Aspect 1 Sampling rate - Batch_ID 1 Hour - Material_ID 1 Hour - Energy_Usage 15 Seconds - Motor_Speed 15 Seconds

If you try to retrieve the raw timeseries data of 'Batch_ID' in the past 24 hours, the query request will have to filter through and ignore all the variables that have a 15 seconds sampling rate in the past 24 hours--resulting in a slower response due to the nature of the timeseries API.

Best practice: group variables with similar sampling rates to make the API requests more efficient. For example: - Aspect 1 Sampling rate - Batch_ID 1 Hour - Material_ID 1 Hour - Aspect 2 Sampling rate - Energy_Usage 15 Seconds - Motor_Speed 15 Seconds

Use the correct functions¶

By default, all data requests are aggregated. If your visualisation only shows 1 data point (e.g. singlestat, gauge, bar gauge), consider using this function: 'MSmostRecentValueWithinTimeRange'.

For example: - 'MSmostRecentValueWithinTimeRange' runs faster than 'MSmostRecentValueWithin90Days' - 'MSrawTimeseries' function can have a payload of maximum 4000 data points; if your visualization uses less data points, you should set a limit via the Max Data Points setting.

Consider a longer auto-refresh time setting¶

A short auto-refresh cycle slows dashboard performance. Also note that a refresh will also run when the response time is longer than the auto-refresh cycle.

Events as annotations¶

Use annotations to integrate event data into your graphs. Annotations are visualized as vertical lines and icons on all graph panels. Hover over an annotation icon to see the description & severity for an event.

To add events to your dashboard, navigate to:

Dashboard Settings > Annotations > Add Annotation Query and follow these steps:

1. Select a repsository from the Data Source drop-down list.
2. Enter an asset name to retrieve its events. Optionally filter for events of a particular severity by adding a severity field after the asset name.

Using variables to create a template dashboard¶

Variables allow you to create more interactive and dynamic dashboards by replacing hard-coded elements such as assets and aspects in your metric queries with variables.

A variable is a placeholder for a value that you can use in: - metric queries - panel titles

If you have multiple assets that share the same asset type, it is useful to create a reusable dashboard. This makes it possible to quickly browse through all of the assets/aspects by using variables.

When you change a value by selecting from the drop-down list at the top of the dashboard, the panel’s metric queries change accordingly.

How to add an asset variable¶

To add an asset variable, navigate to Dashboard Settings > Variables > Add Variables and follow these steps:

1. Enter a name for the variable (e.g. 'Asset'), followed by the repository name in the Query Options field under Data Sources.
2. Enter the * symbol in the Query field in Query Options.
3. Add a regex filter to the query options to refine the filter. For example, if you have multiple pump assets named 'pump_1', 'pump_2', 'pump_3' ... You can filter for all the pump assets by entering “pump.*”. This filters for all asset names beginning with “pump”. View the preview of values to be sure your variable are correct.
4. Optionally check the potential values for your variable are correct under “Preview of values”.
5. When finished, click “Add” on the bottom of the screen to add the variable. The variable displays in your dashboard “Asset” drop-down list.
6. To use the variable enter '$variableName' when you create a new data query--in this example, '$Asset'. Enter the aspect and variable of the query as you normally do.

When you finish your query, you can change the assets on the panel.

How to add an aspect variable¶

To add an aspect variable, navigate to Dashboard Settings > Variables > Add Variables (if you already created a variable, select "New") and follow these steps: 1. Enter a name for the variable (e.g. 'Aspect'). 2. Enter assetName.* in the query. This queries for all the aspects of the asset you specified. 3. Add a regex filter to the query options to refine the filter for the aspect's variables. 5. Optionally check that the values for the variable are correct under “Preview of values”. 6. When finished, click “Add” on the bottom of the screen to add the variable. When you have created the variable, you should now see the 'Asset' dropdown on your dashboard, allowing you to change between the assets.

How to use the aspect variable¶

To use the variable, enter '$variableName' when you create a new query; in this example, '$Asset' in the asset metric and '$Aspect' in the aspect metric. Enter the variable of the query as you normally do.

Once you set your query, you can make changes to the aspects on the panel.

User interactions with drill-downs and dashboard links¶

When creating dashboards, it is important to consider your users and that they have different needs.

Some users want their dashboard to quickly answer questions like, 'Is there an emergency alarm?', or 'Has my machine stopped?', or 'How are today's KPIs tracking?'

Some users want to drill down to find any issues or trends.

Some users want both quick Q&A and drill-downs on the same dashboard, however, too many questions answered on a single dashboard makes it messy and complex.

Best practice: create multiple dashboards and allow users to navigate between them.

Understanding dashboard URLs¶

Every dashboard in Dashboard Designer Add On has a unique UID and unique URL. Look at the current URL of this tutorial page; it can be broken down into sections:

baseURL /Dashboard Designer Add On /d /{dashboardUID} /{dashboardName}

For example:

tenant-Dashboard Designer Add On-silopsms.eu1.mindsphere.op/Dashboard Designer Add On/d/TzRQFzkGz/factory-dashboard

Depending on your dashboard, the URL can have other parameters such as date time and variables:

... ?orgid ={organisation(subtenant) ID} &from ={timeFrom} &to ={timeTo} &var- {variableName} ={variable}

For example:

tenant-Dashboard Designer Add On-silopsms.eu1.mindsphere.op/Dashboard Designer Add On/d/G2JVBTwEk/factory-dashboard?orgID=1&from=1586318878357&to=now&var-Asset=Motor_A

How to create a drilldown link on a dashboard panel to another dashboard¶

Navigate to the Panel Edit page for any dashboard and go to the General tab. Follow these steps to create a drill down link to another Dashboard Designer Add On dashboard:

1. Select Absolute from the Type drop-down list in the Drilldown Links section.
2. Enter the dashboard URL in the URL field beneath the Type field. The base URL is already included, so subtenant (organization) and dashboard names are not required.
3. Change or skip the 'time' and 'variable' fields depending on whether you want to carry over your current dashboard settings.

4. To customize time and variable settings, turn off Include time range > Include variables, and manually enter them in the URL params field; for example:

   &var-Asset=Pump_05&from=now-90d&to=now or include them in the absolute URL.

Creating dashboard navigation using dashboard links¶

Dashboard links appear in the top right corner of your dashboard and act as links to either dashboards or external links. You can add tags to dashboards under Dashboard Settings > General > Tags.

How to create a dashboard link¶

Follow these steps to create a dashbord link:

1. Navigate to Dashboard Settings > Links > Add Dashboard Link.
2. Select links from the Type drop-down list.
3. Select the dashboard you want to link to. 4. To link to all dashboards, select dashboards from the Type drop-down list.

Creating a “batch list” or “shift list” with tables¶

Selecting a link on a dashboard allows you to navigate from your dashboard to any link, internal, another dashboard with a specific URL, or external, for example a customer support website.

Even though Dashboard Designer Add On has a comprehensive time picker, industrial use cases often require that dashboard data be segregated by shifts or batches. You can achieve this with a table panel. Depending on the available raw data, there are multiple ways to create the table. Here are some examples.

Best practice: data structure with start and end time available in "Unix timestamp" format. If possible, record the batch or shift start and end time in Unix format, this allows the datapoint to be directly used in Dashboard Designer Add On's URLs without any transformation. Here is an example of this data structure:

Variable Data Type Example Data Explanation

Batch_ID STRING/INT/DOUBLE B1001 A batch or shift number Start_Time STRING/INT 1577845800000 2020-01-01 13:30:00 in Unix format (UTC) End_Time STRING/INT 1577856600000 2020-01-01 16:30:00 in Unix format (UTC)

By default, UTC time is converted to your local time. If your time is not stored in UTC, use can also use math functions to convert it.

How to create the batch table¶

Follow these steps to create a batch table: 1. Create a panel using the Table plugin. 2. Query for the required data points. Strings can only be retrieved using the MSrawTimeseries function. This example queries the entire 'batch_info' aspect via a * wild card. This applies the alias function to our results. 3. Navigate to Column Style > Add column style in the Visualization tab of the table panel. 4. Enter the name of the column for your batch/shift data, and enable 'Render value as link'. 5. Enter the target dashboard URL in this format:

/Dashboard Designer Add On  /d  /{dashboardUID} &from   ={timeFrom} &to ={timeTo}

Formatting the URL to connect to a specific time period¶

Use a dynamic {timeFrom} and {timeTo} in the link URL by using values from the 'Start Time' and 'End Time' columns.

You can use special variables to specify cell values in the URL --- ${__cell} refers to current cell value. ${__cell_n} refers to Nth column value in the current row. Column indexe start at 0. For example, ${__cell_1} refers to second column's value.

The variable '{timeFrom}' time is the 'Start Time' variable, from the 3^rd column, and you can reference it using ${__cell_2} and the '{timeTo}'. Time is the 'End Time' variable, from the 2^nd column. Reference it using ${__cell_1}.

You can hide unneeded columns in the bathch/shfit table by selecting Hidden from the Type drop-down. This preserves the column positions in the table so the URL variables will still work.

If you only have start and end events¶

You can retrieve the Unix timestamp of an event using the timeOf function.

If you do not have end times available¶

If you are only recording a batch/shift ID you can still use the timestamp of your batch/shift datapoint to segregate data. Variable Data Type Example Data Explanation Batch_ID STRING/INT/DOUBLE B1001 A batch or shift number

When a timestamp of timeseries data is retrieved by Dashboard Designer Add On, it is stored in Unix epoch format by default. The steps to create a batch/shift list from this is very similar. The only difference is when referencing the date & time value in your table URL, you will have to use {_cell_n:raw} to read the Unix epoch value of the timestamp. For example, {Dashboard Deisgner Add On/d/TzjGZFkEp?from=$(_cell_0:raw}

Show assets on a floorplan or map using the Imageit plugin¶

You can use the Imageit plugin to create a map or floorplan of your site and overlay it with data.

The Imageit plugin can show "sensors" which contains a metric value and a position value. You can add a "sensor" to your image by clicking on Add Sensor under the visualisation tab, and:

• In the sensor settings, select your Metric values from a dropdown; this is populated by the your query results which can be renamed using the alias function.
• The X position of the "sensor" is a value between 0 and 100. 0 being the leftmost position on the image, 100 being the rightmost position on the image.
• This value can be the Y-position of the "sensor" is a value between 0 and 100. 0 being the topmost position on the image, 100 being the bottommost.

If your asset's location is static¶

You will have to manually type in the X & Y position of your "sensor" in the sensor options.

If your asset is moving¶

You will need to first convert your asset's position data into an X & Y position format, then scale it to 100. You can use the math function for scaling: X_pos_scaled = X_pos / (X_max - X_min) * 100 Y_pos_scaled = Y_pos / (Y_max - Y_min) * 100

Defining edit/view rights for specific users or teams¶

Further user access control can be managed using the Permissions settings. You can: - Overwrite the default Dashboard Designer Add On roles, delete the editor and viewer role by clicking on the red *. - Give a specific user or team the rights to view, edit or administrate the dashboard, click Add Permission.

How to Import a Dashboard¶

To import a dashboard, follow these steps: 1. Go to JSON Mode. This page shows the raw code behind your current dashboard. 2. If you want to save a local copy of the dashboard, copy the JSON text and save it in a ".json" file. 3. On the sidebar, hover your mouse over the * icon and select Import. 4. Paste the copied JSON model and click Load. 5. If you have an identical dashboard in your current tenant and do not wish to overwrite it, give your dashboard a new name. 6. Click the change button and delete the existing UID so the system generates a Unique identifier (UID) for the dashboard. 7. Click Import.

Copy a panel¶

To copy a panel, click the top of the panel and select Copy from the More menu. and go to More > Copy. Then paste the panel by creating a new panel and select Paste copied panel.

Duplicate a panel¶

To duplicate a panel,select the panel and press p + d, or click on the top of the panel and go to More > Duplicate.

Copying a panel's JSON model¶

To copy a panel's JSON model, click on the top of a panel and go to More > Panel JSON. In the new window, click Copy to clipboard. On a new panel, click on the top of the panel and go to More > Panel JSON, then paste the copied panel in the new window and select Update.

Official IoT TS Aggregates Service documentation: Version 4.x - What's New?¶

10.1 IoT Aggregates v4 changes and limitations¶

• The v3 to v4 upgrade changes have impact to Msaggregation > MsautoAggregation > MsboolAggregation functions only. If no function is selected in the Query configuration, the MsautoAggregation function is applied by default.
• Changes to supported aggregation units:
• second – not supported in V4 (removed)
• minute – supported
• hour – supported
• day – supported
• week – supported (added)
• month – supported (added)
• inute – aggregation unit range limit: 48 hours. If selected date range exceeds 48 hours the user gets an error message.
• hour – aggregation unit renage limit: 30 days. If selected date range exceeds 30 days the user gets an error message.
• day, week, month – aggregate unit range limit: 5 years. If selected date range exceeds 5 years the user gets an error message.

v4 introduces API requests rate limit – the number of allowed requests per minute depends on your subscription.¶

Possible drawbacks and solutions¶

The cases described below can be observed only in conjunction with Msaggregation > MsautoAggregation > MsboolAggregation functions. If no function is selected in the Query configuration, then the function is applied by default.

Minute aggregation unit¶

If the selected date range exceeds 48 hours for the minute aggregation unit then the widget will display an error message:

The problem can be resolved by either of the options: - Select less than 48 hours date range for the dashboard - Use hour aggregation unit instead of minute. - Override widgets date range using Relative time configuration

10.2.2 Hour aggregation unit¶

If the selected date range exceeds 30 days for the hour aggregation unit then the widget will display an error message:

The problem can be resolved by either of the options: - Select less than 30 days date range for the dashboard Use day aggregation unit instead of hour Override widgets date range using Relative time configuration

10.2.3 API rate limit¶

Depending on the dashboard configuration the user may start getting API rate limit exceeded error messages. This can be caused by big amount of aggregation functions used by dashboard configuration or high dashboard refresh rate. If the API rate limit is exeeded the widget will display an error message:

The problem can be resolved by either of the options: - Increase dashboard refresh interval - Decrease amount of aggregation functions on the dashboard - In certain cases (e.g. Gauge, Bar Gauge) it is advised to use MSmostRecentValueWithinTimeRange function instead of aggregation

10.2.4 How to get sub-minute aggregation data¶

As second aggregation unit is not support by v4 the sub-minute data can be visualized by: - Use the MsrawTimeseries function to get raw time series data - Use VFC application to define custom aggregation logic