How to use the SQL tile

About the SQL tile

The SQL tile enables you to pull data from external SQL data sources into your dashboards and perspectives.

By default, only Dashboard Server administrators can create and edit SQL queries in the SQL tile (see How to make a user a Dashboard Server Community Edition administrator).

The SQL tile will only work if the SquaredUp server is domain joined. This is because the Dashboard Serverapplication pool account must be given permission to access the SQL database (How to check and modify the application pool identity).

How to configure an SQL tile

Since Dashboard Server version 5.4 you need an SQL provider to use the SQL tile. . If you haven't created an SQL provider yet, you need to create a provider first.

See How to add an SQL provider.

If you created SQL tiles before Dashboard Server version 5.4, they were created with a connection string in the tile instead of a provider.
As soon as you update to v5.4 those connection strings will automatically be converted into providers. If identical connection strings are detected, they'll be merged into one provider.
The new SQL providers will be named in the following format: servername.databasename (if server and database name can't be identified they'll be named SQL provider 1, SQL provider 2, etc.)

Add a new tile to a dashboard or perspective and choose the SQL tile.
Choose the visualization for your SQL tile:
Scalar
A single value such as a number of customers or incidents.
Example:
Grid
A table of data, for example incidents or tickets.
Tip: You can turn the individual rows into links in the settings. For example, if you're displaying tickets in your grid, you can link the rows to the ticket in your external ticket system.
Did you know? Since Dashboard Server 5.4 users can search the grid, and temporarily change the column size and sorting of the grid (by clicking on the column headers) without having to access the settings. They can also expand a row by clicking on the three dots at the end of each row if cells are too small to show their entire content.
Line Graph
Shows data over time, in a graph with an x-axis (time) and a y-axis. You can show several objects, such as servers, in one graph.
Example:
Sparklines
Shows data over time (like line graphs), but each item gets its own graph instead of showing all lines in one graph.
Example:
Bar Graph
Visualizes both a number and the resulting bar width based on the number value.
Example:
Donut
Shows the results in a donut shape.
Example:
Status Icons
Shows the state of items as icons with different colors. You can display just the icons or together with a description. You can also use a background image and drag the icons into position on the image.
Example:
Status Blocks
Shows the state of items as blocks with different colors.
Example:
Connection:
Choose the SQL provider you want to use.
Since Dashboard Server version 5.4 you need an SQL provider to use the SQL tile. . If you haven't created an SQL provider yet, you need to create a provider first.
If you haven't updated to v5.4 yet, you need to enter a connection string.
For more information about adding SQL providers and entering connection strings see How to add an SQL provider.

Query:

By default, only Dashboard Server administrators can create and edit SQL queries in the SQL tile (see How to make a user a Dashboard Server Community Edition administrator).

Note: When an SQL tile uses an ODBC provider, you can't use mustache values for your queries in that tile.

To test the query you want to use, run your query in SQL Server Management Studio, so you can see any errors and amend as necessary. Make sure that the server and database you use in SQL Server Management Studio for this test corresponds with the connection string you used in the Connection panel.

After the test was successful, paste your query into the query string box.

Example: A query string to show the number of alerts

Copy

SELECT COUNT(*) from Alert.vAlert

How to use the page timeframe in your SQL query

You can use page timeframe variables in your SQL query if you want your query to consider the current page timeframe.

If you want to use page timeframe variables, you can copy them from the table below

Dynamic page timeframe formats

When you use page timeframe variables, the dynamic page timeframe will be inserted as a string in your search query, script, field, or wherever you use the variable.

`timeframe.isoDuration`	Use this format when you want to insert the page timeframe according to the ISO standard for time ranges (period of time). Example: When them page timeframe is set to "last 12 hours" the string `PT12H` is inserted.
`timeframe.isoStart`	Use this format to insert a "from" time when you want the starting point to be "now minus page timeframe". The page timeframe will be inserted as a starting time according to the ISO 8601 standard. Example: When the page timeframe is set to "last 12 hours" the starting time is "now minus 12 hours".
`timeframe.isoEnd`	Use this format to insert a "to" time when you need to specify the end time. The end time is always "now". The current time will be inserted according to the ISO 8601 standard.
`timeframe.unixStart`	Use this format to insert a "from" time when you want the starting point to be "now minus page timeframe". The page timeframe will be inserted as a starting time in milliseconds according to the UNIX standard. Example: When the page timeframe is set to "last 12 hours", the starting time is "now minus 12 hours".
`timeframe.unixEnd`	Use this format to insert a "to" time when you need to specify the end time. The end time is always "now". The current time will be inserted in milliseconds according to the Unix standard.
`Math.floor(timeframe.UnixStart / 1000)`	Use this format when you want to use the `unixStart` time but need to convert it from milliseconds to seconds.
`Math.floor(timeframe.UnixEnd / 1000)`	Use this format when you want to use the `unixEnd` time but need to convert it from milliseconds to seconds.

Fixed timeframe formats (without using the dynamic page timeframe)

Date.now() - 86400 * 1000 *14

This is a template format to express the fixed timeframe "14 days ago" (now minus 14 days in milliseconds). You can use this template to create your own fixed timeframe.

How to read the parameters of the template:

Date.now() = the current date and time (now) in milliseconds
86400 = 24 hours in seconds
1000 = converts the seconds into milliseconds
14 = 14 days

If you want to use a fixed timeframe in seconds, you need to convert the Date.now() into seconds, for example "4 days ago in seconds": (Date.now() /1000) - 86400 * 4.

new Date().toISOString() A text based representation of "now". Use this format if you want to insert the date as a string in ISO 8601 format, rather than leaving it as a date object.

Query requirements and tips for Grids

There are no special requirements for grid queries, since an SQL query will always return a grid.

Tip: How to convert a Unix timestamp column into a more readable format with your query

You need to insert CONVERT into your SQL query string.

For example, if your query string is SELECT TOP 10 * from Alert.vAlert and dwLastModifiedDateTime is the name of the column you want to convert, your conversion would look like this:

Copy

SELECT TOP 10 CONVERT(varchar(64), dwLastModifiedDateTime, 21) AS dwLastModifiedDateTime from Alert.vAlert

You can configure the date format by editing 21, replacing it with a chosen format which can be found in the following article: MSDN: CAST and CONVERT

Query requirements for Status Icons or Blocks

The return data must include a state column which must contain the following values:

healthy, critical, and/or warning (the values are not case-sensitive). Any other values will result in state unknown.

The state values define the color of the status icons or blocks:

`Healthy`	green
`Warning`	yellow
`Critical`	red
`Unknown`	gray

My return data doesn't contain a state column

If your return data doesn't contain a state column, you can define a state column in your query. You need to define which data you want to be interpreted as healthy, critical, and/or warning and use AS State to put the results in a state column.

Example:

Copy

SELECT Name, CASE WHEN Duration < 500 THEN 'Healthy' ELSE 'Critical' END AS State

My return data contains a state column, but different values

If your return data contains a state column, but the values are not healthy, critical, or warning, you need to map the values you want to use to the values healthy, critical, and/or warning.

Example:

Copy

SELECT
    Computer as Name,
    Max(TimeGenerated) as max_TimeGenerated,
    State as OriginalState,
    CASE
        WHEN State = 'up' THEN 'Healthy'
        WHEN State = 'down' THEN 'Critical'
        ELSE 'Warning'
    END AS State
FROM
    StateTable
GROUP BY
    Computer,
    State

Configure the settings for your visualization:

Settings for Scalars

Scalar

Font size	Allows you to set the font size of the value in the tile.
Unit	Allows you to add a unit to the value displayed in the Scalar tile. For example, if your value shows a time in milliseconds, you can enter "ms" or if your value shows pageviews, you can enter "pageviews".
Value formatter	Allows you to format the value by using the mustache picker. For example, you can round the value up or down or convert it.

Color

Conditional formatting:

You can display the scalar in different colors based on conditions you defined here. For example, you can display the scalar in green when the value is below 100 and in red when it is above 100.

Click on add to configure a condition.
Click on select color.... to open the color picker. Select the color for this condition.
Enter your condition in the field next to the color. You can use the value property and manipulate it with JavaScript String and Regex APIs. When you click on the mustache picker, you'll get some examples:
- Value is greater than something, less than something, etc.
  For example: {{value < 10}} (The color you picked will be used if the value is less than 10)
- Value is present in the result
  For example: value.IndexOf('error') != -1 (The color you picked will be used if the string value "error" is present in the results)
- Value matches one of the regular expressions you defined
  For example: value.match(/healthy|good|up/) (The color you picked will be used if the string values are healthy, good, or up)

Display:

Here you decide how the color is used:

Tile background	Highlight the tile in the color you defined.
Text foreground	Display the text in the color you defined.

Link options

Allows you to turn the graph item(s) into links. You can either enter plain text to create a fixed link (URL always stays the same) or use dynamic properties to create a dynamic link.

Dynamic links make use of dynamic properties which are inserted as part of the URL. This creates a template URL that will be resolved to an actual URL based on the items properties.

For example, if you want to link to tickets in your ticket system and the format of the URL for tickets in your system is https://www.my-system/ticket-123, where 123 is the ticket ID, you can use the dynamic property that contains the ticket ID and enter the dynamic URL https://www.my-system/ticket-{{ticketID}}.

For scalars, you can only use the dynamic property value in dynamic links, which means the link changes when the value of the scalar changes. Since a scalar is just one item, it would also make sense to use a fixed link, for example the link to the website of which you are displaying the response time.
For status icon or bars and the rows of a grid, you usually want to use a dynamic link since you get multiple items or rows that represent different things. You can use any of the dynamic properties the mustache picker offers you.

Settings for Grids

Grid columns

Grid columns opens the grid designer, where you can show or hide columns, change the order of columns, edit column names or add custom columns.

How to use the Grid Designer

Grid options

Row link	Allows you to turn the graph item(s) into links. You can either enter plain text to create a fixed link (URL always stays the same) or use dynamic properties to create a dynamic link. Dynamic links make use of dynamic properties which are inserted as part of the URL. This creates a template URL that will be resolved to an actual URL based on the items properties. For example, if you want to link to tickets in your ticket system and the format of the URL for tickets in your system is `https://www.my-system/ticket-123`, where `123` is the ticket ID, you can use the dynamic property that contains the ticket ID and enter the dynamic URL `https://www.my-system/ticket-{{ticketID}}`. For scalars, you can only use the dynamic property `value` in dynamic links, which means the link changes when the value of the scalar changes. Since a scalar is just one item, it would also make sense to use a fixed link, for example the link to the website of which you are displaying the response time. For status icon or bars and the rows of a grid, you usually want to use a dynamic link since you get multiple items or rows that represent different things. You can use any of the dynamic properties the mustache picker offers you. Examples for URLs with dynamic properties for popular APIs Dynamic mustache properties and values you need to change according to your instance are highlighted in bold. ServiceNow incidents: `https://<your-instance>.service-now.com/nav_to.do?uri=%2Fincident.do%3Fsys_id%3D{{sys_id}}` PagerDuty incidents: `{{incident.html_url}}` Azure DevOps projects: `https://dev.azure.com/<your-instance>/{{name}}` Azure DevOps builds: `https://dev.azure.com/<your-instance>/_build/results?buildId={{id}}` Zendesk tickets: `https://<your-instance>.zendesk.com/agent/tickets/{{id}}` Azure Application Insights `https://portal.azure.com/#@squaredup.net/resource/{{ResourceId}}`
Show column headers	You can choose between showing or hiding the header for all columns.
Expand rows automatically	Activate this checkbox if you want the row height to expand automatically based on the row content, for example if your grid uses increased text size, images, emojis etc.
Limit number of results displayed	You can set a limit of the initial number of results displayed in the grid. If you have set a limit and there are more results to display, users will see a "show all" button below the grid.
Font size	Use the slider to adjust the font size.

Tip for column sizing: You can change the column width directly in the grid by clicking on the divider lines between columns and dragging them to the width you want. You need to show column headers (by activating the show column headers check box) to be able to change the column width.
Resizing columns while in edit mode affects how the grid looks by default when users open the dashboard. Users can temporarily change the column sizes by dragging them, but those changes only last until they leave the page.

Settings for Donuts

Sort

Sort allows you to change the order of the results displayed. You can sort by value (ascending or descending) or label (alphabetically ascending or descending).

Display

Size mode:

Default	Displays the donut scaled to the height of the tile.
Fill	Enlarges the donut to use the whole width of the tile. If you chose the fill option and show the legend, you can define the size of the legend with a slider.

Show legend:

Allows you to show or hide the legend of the graph.

Display mode:

Allows you to switch between displaying absolute values or percentages.

Color palette:

Here you can choose between different color palettes.

Note: If there are more items than colors, the colors repeat from the beginning.

Tip for displaying priorities or health states: If you want to display priorities or health states from a data source that doesn't enrich the data with information about priority or health (like the SQL tile or external APIs), use the custom color option and map the results to the correct color. This way, you can make sure that healthy or low priority results are displayed in green, unhealthy or high priority results are displayed in red, etc. If you use the color palettes Priorities, Health1, or Health2 the colors get assigned depending on how the results are sorted, which doesn't guarantee that the colors make sense for the priority or state they represent.

General	10 different colors without specific meaning
Priorities	5 different colors representing 5 different priority states
Health1	3 different colors representing 3 different health states (red=unhealthy, green=healthy, gray=unknown)
Health2	4 different colors representing 4 different health states (red=critical, orange=unhealthy, green=healthy, gray=unknown)
Pastel	10 different pastel colors without specific meaning
Blue	4 different shades of blue from dark to light
Orange	4 different shades of orange from dark to light
Green	4 different shades of green from dark to light
Pink	4 different shades of pink from dark to light
Custom	Here you can choose colors and map them to a value. Click on Select color... to select a color and enter the name of the value that you want to display in that color. Make sure you spell the value's name correctly (case-sensitive), otherwise the color won't be assigned to it. Note if your color mapping doesn't work (color stays gray) If you entered the value's name correctly (case-sensitive) and your mapping still doesn't work, check if the mapping value contains leading or trailing spaces. Try to enter the value with and without those spaces. Alternatively, you can remove spaces from the mustache expression and enter the values without spaces. Example: Mustache expression with leading and trailing spaces in the values: `{{#if Status == "1" }} Healthy {{elseif Status == "2" }} Down {{elseif Status == "3" }} Warning {{/if}}` Mustache expression without spaces in the values: `{{#if Status == "1" }}Healthy{{elseif Status == "2" }}Down{{elseif Status == "3" }}Warning{{/if}}`

Settings for Status Icons

Link options

item link:

Allows you to turn the graph item(s) into links. You can either enter plain text to create a fixed link (URL always stays the same) or use dynamic properties to create a dynamic link.

Dynamic links make use of dynamic properties which are inserted as part of the URL. This creates a template URL that will be resolved to an actual URL based on the items properties.

For scalars, you can only use the dynamic property value in dynamic links, which means the link changes when the value of the scalar changes. Since a scalar is just one item, it would also make sense to use a fixed link, for example the link to the website of which you are displaying the response time.
For status icon or bars and the rows of a grid, you usually want to use a dynamic link since you get multiple items or rows that represent different things. You can use any of the dynamic properties the mustache picker offers you.

Label

Allows you to change the label of the results.

name

Choose this option if you want to use the default label that has been created automatically.

custom

Here you can change the label to a custom label. You can use static text and dynamic properties. Use the mustache picker to select dynamic properties from the response data to use them as labels.

For more information see How to use Custom Labels

Sublabel

Allows you to add a sublabel of the results.

custom

Here you can change the label to a custom label. You can use static text and dynamic properties. Use the mustache picker to select dynamic properties from the response data to use them as labels.

For more information see How to use Custom Labels

none By default, no sublabels are shown.

Sort

Sort allows you to change the order of the results displayed. You can also group them by their characteristics.

default	By default, the sorting of the blocks or icons depends on the data source. This can be alphabetical sorting or the order in which data comes back from an API request.
sort by	Sort by label or health state, ascending or descending
group by	Group by label or health state, ascending or descending

Image

Here you can choose one of the provided images or upload your own.
Tip: If you want a different selection of maps, you can download more at https://freevectormaps.com/

Supported image formats: png, jpg, jpeg, gif, tif, tiff. svg, bmp
Tip: SVG images resize best since they are vector images.

File size limit: 10MB

Image size: Images fill the size of the tile, which means you can resize the image by adjusting the tile's size. The size of the tile also depends on the screen the dashboard is being viewed on.

Icons

Here you can customize the icons on the image:

You can change the size of the icons with the slider
You can change the shape of the icons (square or circle)
You can drag the icons on the image into position

Display styles for Status icons

This setting is not done in a panel, you can change the display style even after you finished configuring the tile.

You can use toggle zoom button at the top right of the tile to change between the different ways Status icons can be displayed.

One long list
Column list
Icons only

Settings for Status Blocks

Link options

item link:

Allows you to turn the graph item(s) into links. You can either enter plain text to create a fixed link (URL always stays the same) or use dynamic properties to create a dynamic link.

Dynamic links make use of dynamic properties which are inserted as part of the URL. This creates a template URL that will be resolved to an actual URL based on the items properties.

For scalars, you can only use the dynamic property value in dynamic links, which means the link changes when the value of the scalar changes. Since a scalar is just one item, it would also make sense to use a fixed link, for example the link to the website of which you are displaying the response time.
For status icon or bars and the rows of a grid, you usually want to use a dynamic link since you get multiple items or rows that represent different things. You can use any of the dynamic properties the mustache picker offers you.

Label

Allows you to change the label of the results.

name

Choose this option if you want to use the default label that has been created automatically.

custom

Here you can change the label to a custom label. You can use static text and dynamic properties. Use the mustache picker to select dynamic properties from the response data to use them as labels.

For more information see How to use Custom Labels

Sublabel

Allows you to add a sublabel of the results.

custom

Here you can change the label to a custom label. You can use static text and dynamic properties. Use the mustache picker to select dynamic properties from the response data to use them as labels.

For more information see How to use Custom Labels

none By default, no sublabels are shown.

Sort

Sort allows you to change the order of the results displayed. You can also group them by their characteristics.

default	By default, the sorting of the blocks or icons depends on the data source. This can be alphabetical sorting or the order in which data comes back from an API request.
sort by	Sort by label or health state, ascending or descending
group by	Group by label or health state, ascending or descending

Blocks

Here you can set the number of columns for the blocks, their height and the font size within the blocks.

Click done to save the tile.
The tile now shows data according to your settings.

Walkthroughs

FAQs

Who can create and edit SQL queries?

By default, only Dashboard Server administrators can create and edit SQL queries in the SQL tile (see How to make a user a Dashboard Server Community Edition administrator).

How do I configure access to a database?

To be able to query databases, such as the Operations Manager database, the Dashboard Server application pool identity needs to be given the db_datareader role in SQL Server Management Studio for the database you wish to query. See How to configure access to a database for use with the SQL tile

Line Graph shows "A value column and a timestamp column are mandatory in the query results, please modify your query"

Both a DateTime field AND a Numeric value field are necessary for a line graph to be drawn. This message indicates that the query results are missing either a DateTime field, a Numeric value field or both.

Can I use parameters to customize a SQL query?

You can use the following parameters in your SQL query:

On dashboards	Page timeframe parameters
On perspectives	Page timeframe and scope parameters

How can I get dates and times to show correctly in my Grid visualization?

If your grid columns show times in the Unix timestamp format (milliseconds), there are two ways for you to convert them into a readable date and time format:

convert the timestamp directly with your SQL query
use a custom template for your grid columns and insert the conversion there

Converting the timestamp with your SQL query

You need to insert CONVERT into your SQL query string.

For example, if your query string is SELECT TOP 10 * from Alert.vAlert and dwLastModifiedDateTime is the name of the column you want to convert, your conversion would look like this:

Copy

SELECT TOP 10 CONVERT(varchar(64), dwLastModifiedDateTime, 21) AS dwLastModifiedDateTime from Alert.vAlert

You can configure the date format by editing 21, replacing it with a chosen format which can be found in the following article: MSDN: CAST and CONVERT

Converting the timestamp with a custom template

You can use timeago to convert Unix timestamps from milliseconds to show a readable date and time. You can either display an absolute time (for example, August 20th 2021) or a relative time (for example, 20 hours ago).

There are four parameters you can use for converting the time, written in the following format:
timeago(Value you want to convert, Show Absolute, Show Time, Without Suffix, With Prefix).

The parameters for the value you want to convert can either be true or false:

Show Absolute	`true` = show absolute time (date) rather than relative time `false` = show relative time
Show Time	`true` = if showing absolute time, show the time as well as the date `false` = do not show the time with the date
Without Suffix	`true` = if showing relative time, this removes the "ago" `false` = "ago" at the end will be shown (e.g. 10 hours ago)
With Prefix	`true` = adds "since" ahead of the absolute time, or "for" ahead of the relative time `false` = no prefix will be shown

Tip: The default setting for all parameters is false. If you only want to change the first parameters, you can just use timeago(value, true, true) and it will be interpreted as timeago(value, true, true, false, false).

Examples:

To display the relative time (how long ago something occurred):

Copy

{{timeago(value)}}

To display the absolute time as the date without the time:

Copy

{{timeago(value, true)}}

To display the absolute time as the date with the time:

Copy

{{timeago(value, true, true)}}

To display the time with the prefix "for" for relative time and "since" for absolute time (for example, "the status has been unhealthy for 10 hours")

Option A) Use the fourth parameter and set it to true. This will insert the appropriate prefix for the absolute or relative time:

Copy

timeago(value, false, false, true, true)

Option B) You can leave out the fourth parameter that controls if the prefix "for" or "since" is inserted automatically. Since you left it out, it defaults to false, causing no prefix to be shown. Instead you insert the word "for" or "since" manually before the timeago function.

Copy

for timeago(value, false, false, true)

To convert a time value from seconds to milliseconds:

Some APIs, like Pingdom for example, return the value in seconds. Since Timeago uses the time value in milliseconds, you need to multiply by 1000 in that case:

Copy

{{timeago(value*1000)}}

Example with a Pingdom property:

Copy

{{timeago(properties.lasttesttime*1000)}}

DS LIVE KB.10.log-347084369.zip
5 KB Download

percentage	Shows 0 to 100
fit to data	Shows the data minimum to data maximum
fit to data (from zero)	Shows from 0 to the data maximum
custom	Allows you to specify the min and max
custom fit	Allows you to specify the min and max limits, so that data outside your settings will not be shown. If all the data falls within your specified ranges then the y-axis range will fit to the data rather than your caps.

percentage	Shows 0 to 100
fit to data	Shows the data minimum to data maximum
fit to data (from zero)	Shows from 0 to the data maximum
custom	Allows you to specify the min and max
custom fit	Allows you to specify the min and max limits, so that data outside your settings will not be shown. If all the data falls within your specified ranges then the y-axis range will fit to the data rather than your caps.

percentage	Shows 0 to 100
fit to data	Shows the data minimum to data maximum
fit to data (from zero)	Shows from 0 to the data maximum
custom	Allows you to specify the min and max
custom fit	Allows you to specify the min and max limits, so that data outside your settings will not be shown. If all the data falls within your specified ranges then the y-axis range will fit to the data rather than your caps.