The Web API tile allows you to pull data from external APIs and display this data using a variety of visualizations.
What kinds of APIs are supported?
The Web API tile works with any REST API that returns JSON.
How do I connect to the API I want to use?
The connection details are not stored in the tile, but in the provider. You need to create a provider before you can use the Web API tile. Adding an API provider is a one-time configuration task to be carried out by a SquaredUp DS administrator.
The Web API tile supports GET and POST requests. For the format of those requests, you need to refer to the API documentation of the service you want to integrate with.
Should I use the Web API tile or one of the dedicated tiles?
For the most used APIs we now have dedicated tiles to make integration quicker and simpler:
If there's no dedicated tile for the API you want to use, you can always use the Web API tile. Here are articles with examples about how to integrate with some popular APIs using the Web API tile:
Take a look at our Community Answers site, where there's a wealth of knowledge about APIs
If you're looking for some real-life examples of dashboards, check out the Dashboard Gallery. You'll find dashboards that users from SquaredUp and the Community have created to help you get the most out of SquaredUp DS:
If you don't already have a provider for Web API tiles, you need to create one before you can configure your Web API tile (How to add a Web API provider).
Add a new tile to a dashboard and choose Integrations > Web API.
Choose the visualization for your Web API tile:
A Scalar displays one value. A Scalar is useful to show a specific number like "total cost of my services" or "free disk space on this server". When a Data Stream returns multiple values (meaning a table with multiple rows), you will still be able to pick the Scalar visualization, but the Scalar will only show the value of the first row.
Example:
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 SquaredUp DS 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.
Shows time-series 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:
Visualizes time-series data as vertical columns.
Example:
Shows data over time (like line graphs), but each item gets its own graph instead of showing all lines in one graph.
Example:
Visualizes both a number and the resulting bar width based on the number value.
Example:
Shows the results in a donut shape.
Example:
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:
Shows the state of items as blocks with different colors.
Example:
The Date Heatmap shows the number of events per hour of the day. It uses lighter colors to show higher values and darker for lower values.
Provider: Choose the provider you want to use for this tile.
You can use generic and dedicated integrations to create your own providers. Of course, a dedicated provider like ServiceNow will only work with the ServiceNow API.
HTTP mode: Choose if you want to use a GET or POST request. URL: This is the query URL. The query URL gets added to the URL you defined in the provider you are using for this tile. Example: You want to query https://myservice/customers/tickets. Your provider URL is https://myservice/ Your query URL needs to be customers/tickets
The easiest way to add query parameters to your query URL is using the data section in the Headers&Data panel. The parameters you enter there automatically get added to your query URL in the correct format.
If you want to add the query parameters manually here, you need to make sure you use the correct format to separate the query parameters from the query URL, for example https://myservice/endpoint?filter=customers
Please refer to the API documentation of the API you are using to see which query parameters are supported and what values they can have.
Using the page timeframe as a query parameter
You can use the clock insert time value button to insert page timeframe and date variables in your query.
Please refer to the API documentation of the API you are using to see what kind of time format is required as a value.
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 8601 format
Example: When the 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 format
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 format
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
By default, only SquaredUp DS administrators can create and edit Web API queries in the Web API tile.
Headers & Data: Headers: The HTTP header. Here you can enter properties for authentication or specify that the content type of the return data needs to be JSON. Please refer to the API documentation of the API you are using to see what properties are supported. Data: If you are using a GETrequest: Here you can add query string parameters to your query string. If you are using a POSTrequest: Here you can add additional data to the request body of your query. You can send query string parameters as a form, and other data in the content type json, xml, or text. Please refer to the API documentation of the API you are using to see what parameters and content types are supported.
You can use the clock insert time value button to insert page timeframe and date variables in your query.
Please refer to the API documentation of the API you are using to see what kind of time format is required as a value.
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 8601 format
Example: When the 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 format
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 format
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
Example for using the page timeframe as a query parameter:
You want the results of your query to adapt to the page timeframe. The API supports the from query parameter, so you can use it to select results starting from whatever page timeframe is currently set. You want to query an API which uses milliseconds to denote a time range. This means you can use the unixStart page timeframe format.
Data
Name: from
value: {{timeframe.unixStart}}
Example for using the page timeframe in the request body:
You want your POST request to create a table of sales data that adapts to the page timeframe, because you want to see closed and won opportunities within the time period of the currently set page timeframe. The API for your CRM system supports plain text request bodies and ISO-format date strings, which means you can use the isoStart page timeframe format to filter out opportunities that are older than the currently set page timeframe.
Content type: text
Body:
Select Name, Amount, CLoseDate
FROM Opportunity
WHERE StageName ='Closed Won'AND CloseDate > {{timeframe.isoStart}}
Note:
By default, only SquaredUp DS administrators can create and edit Web API queries in the Web API tile.
Response Data: This is where you enter the location of the results set that is returned. The response data box shows you a preview of the data returned, so you can check the location of the data returned, and use that in the key path.
Configure the settings for your visualization:
Scalar
Font size
Allows you to set the font size of the value in the tile.
Alignment
Select the scalar text alignment. Choose from left, center or right.
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 data in different colors based on values you define here. For example, you can display the data 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 pick will be used if the value is less than 10)
Value is present in the result (scalar tiles only) For example: value.IndexOf('error') != -1 (The color you pick will be used if the string value "error" is present in the results)
Value matches one of the regular expressions you defined (scalar tiles only) 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.
Dynamic mustache properties and values you need to change according to your instance are highlighted in bold.
Property names that contain hyphens (for example properties.name-with-hyphens) can't be processed due to a JavaScript limitation. If you want to use a property that contains a hyphen, you have two options:
If you have access to the data source and can change the name of the property, change the name of the property to a name without hyphens. For example, if your Elasticsearch query uses a property (an aggregation, a grouping or any other property you want to use) with a name that contains a hyphen, you can either access your Elasticsearch instance and change the name there or you can overwrite the name in the query dsl field.
If you can't change the name of the property, you need to enter the property name in the following format: Original property name: {{properties.name-with-hyphens.value}} New format: {{properties['name-with-hyphens'].value}}
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.
Dynamic mustache properties and values you need to change according to your instance are highlighted in bold.
Property names that contain hyphens (for example properties.name-with-hyphens) can't be processed due to a JavaScript limitation. If you want to use a property that contains a hyphen, you have two options:
If you have access to the data source and can change the name of the property, change the name of the property to a name without hyphens. For example, if your Elasticsearch query uses a property (an aggregation, a grouping or any other property you want to use) with a name that contains a hyphen, you can either access your Elasticsearch instance and change the name there or you can overwrite the name in the query dsl field.
If you can't change the name of the property, you need to enter the property name in the following format: Original property name: {{properties.name-with-hyphens.value}} New format: {{properties['name-with-hyphens'].value}}
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.
Data mapping
Property names that contain hyphens (for example properties.name-with-hyphens) can't be processed due to a JavaScript limitation. If you want to use a property that contains a hyphen, you have two options:
If you have access to the data source and can change the name of the property, change the name of the property to a name without hyphens. For example, if your Elasticsearch query uses a property (an aggregation, a grouping or any other property you want to use) with a name that contains a hyphen, you can either access your Elasticsearch instance and change the name there or you can overwrite the name in the query dsl field.
If you can't change the name of the property, you need to enter the property name in the following format: Original property name: {{properties.name-with-hyphens.value}} New format: {{properties['name-with-hyphens'].value}}
grouping
Here you can define a group to take a closer look at the graph's value(s). Each item in the group will create its own series (a line in a line graph, a bar in a bar graph etc.). For example, if you group the value response time by servers on a line graph, you'll see one line per server, each line showing you the response time for this one server over time.
To enter your grouping, you have to find the property that contains it. You can use the mustache picker to see every property returned from the response data. Pick the property that contains the grouping you want your graph to show.
Note: If you type in the property, make sure you add the mustache {{}} to the property name. Otherwise, you'll either get an error message or the property will be interpreted as a static value and be the same for every result.
Note: If your grouping needs more than one property, you can combine multiple properties. For example, if you want to see the disk space on the c: drive of different computers, your grouping needs to be c: drive and computer. You can combine them in one mustache {{PropertyForComputer + PropertyForC:Drive}} or keep them in separate mustaches {{PropertyForComputer} {PropertyForC:Drive}}.
timestamp
Here you define the time series to be used for the visualization.
To enter your timestamp, you have to find the property that contains it. If there is a mustache picker you can use this to see every property from the response data. Pick the property that contains the timestamp you want the visualization to use.
Note: If you type in the property, make sure you add the mustache {{}} to the property name. Otherwise, you'll either get an error message or the property will be interpreted as a static value and be the same for every result.
Note: Timestamps that are supported are Unix timestamp in milliseconds or the ISO 8601 format
metrics
Here you define which value the graph will show. For example, if you want to see the response time of different servers, your metric value would be response time. If you want to see the number of tickets, your metric value would be number (of tickets).
To enter your metric value, you have to find the property that contains that value. You can use the mustache picker to see every property returned from the response data. Pick the property that contains the value you want your graph to show
Note: If you type in the property, make sure you add the mustache {{}} to the property name. Otherwise, you'll either get an error message or the property will be interpreted as a static value and be the same for every result.
Note: The metric value must be a numeric object. If an API returns values as strings, you can convert them from a string to a numeric object with the parseFloat() function.
Info: You can manipulate the value by adding operators to add, substract, divide or multiply. You can pick additonal properties from the response data or insert plain text for those functions. For example, if you want to multiply two properties you can do that by entering {{PropertyForMetricValue*PropertyForOtherMetricValue2}} . If you want to change Kb in Gb you can divide the value by 1024: {{PropertyForMetricValue/1024}}. You can also use more elaborate functions according to JavaScript syntax.
Extract multiple metrics:
If you want to see more than one value, you can tick the "Extract multiple metrics" checkbox. You can manipulate those metrics exactly like the first metric you chose. The metrics won't affect each other, they are all treated as separate metrics. Each value will get its own series (a line in a line graph, a bar in a bar graph etc.).
Top N
Here you can define a limit for the number of results you want to see. Activate the limit number of results displayed checkbox to enter a limit for results. You can choose if this limit should be applied from the top ranking results down (ascending, default option) or from the bottom ranking results up (descending).
Threshold
You can choose to apply a threshold line at a specified value, and whether you wish to fill above or below this value, or just show the line. For example, for free disk space you might want to fill below the line to highlight when space goes below a particular threshold. For processor information you might want to fill above the line to highlight when processor percentage goes above that threshold. The threshold is also shown on the drilldown view.
Max, min, avg
When drilled-down to view a graph, you can select the min, max and avgoptions for each object (displayed to the right of the graph), which displays a line cutting horizontally across the graph a each of the selected value points.
Data range
The Data Range option allows you to choose the range of data the graph will display. For line graphs, this means the data on the y-axis.
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.
Display
Height:
Allows you to set the height of the tile with a slider.
Show hover details:
Shows the value for all lines at any point you hover. There may not be a value exactly where you hover so the value is interpolated from the values either side.
Show points:
Shows where the data points are on the line. Useful to identify missing points, or detail for changing data.
Show trend
Enable the Show Trend Linestoggle to display a trend line for the line graph data. Disable the toggle to hide the trend line.
Custom colors:
You can display the data in different colors based on labels. For example, you can display data in green for a specific user.
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 label property and manipulate it with JavaScript String and Regex APIs. When you click on the mustache picker, you'll get some examples:
Condition is true if the label contains something For example: {{label.indexOf('SQL') != -1}} (The color you pick will be used if the label contains 'SQL')
Condition is true if the label contains multiple things For example: {{label.match(/C:|D:|E:/) != null}} (The color you pick will be used if the label contains 'C:', 'D:' or 'E:')
Condition is true if the label contains multiple things with multiple variations For example: {{label.match(/^[Ss]erver[0-9]+$/) != null}} (The color you pick will be used if the label is 'Server' or 'server' with a number after it)
Label
Allows you to change the label of the results.
Show legend:
Allows you to show or hide the legend of the graph.
Label:
auto
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.
Property names that contain hyphens (for example properties.name-with-hyphens) can't be processed due to a JavaScript limitation. If you want to use a property that contains a hyphen, you have two options:
If you have access to the data source and can change the name of the property, change the name of the property to a name without hyphens. For example, if your Elasticsearch query uses a property (an aggregation, a grouping or any other property you want to use) with a name that contains a hyphen, you can either access your Elasticsearch instance and change the name there or you can overwrite the name in the query dsl field.
If you can't change the name of the property, you need to enter the property name in the following format: Original property name: {{properties.name-with-hyphens.value}} New format: {{properties['name-with-hyphens'].value}}
Data mapping
Property names that contain hyphens (for example properties.name-with-hyphens) can't be processed due to a JavaScript limitation. If you want to use a property that contains a hyphen, you have two options:
If you have access to the data source and can change the name of the property, change the name of the property to a name without hyphens. For example, if your Elasticsearch query uses a property (an aggregation, a grouping or any other property you want to use) with a name that contains a hyphen, you can either access your Elasticsearch instance and change the name there or you can overwrite the name in the query dsl field.
If you can't change the name of the property, you need to enter the property name in the following format: Original property name: {{properties.name-with-hyphens.value}} New format: {{properties['name-with-hyphens'].value}}
grouping
Here you can define a group to take a closer look at the graph's value(s). Each item in the group will create its own series (a line in a line graph, a bar in a bar graph etc.). For example, if you group the value response time by servers on a line graph, you'll see one line per server, each line showing you the response time for this one server over time.
To enter your grouping, you have to find the property that contains it. You can use the mustache picker to see every property returned from the response data. Pick the property that contains the grouping you want your graph to show.
Note: If you type in the property, make sure you add the mustache {{}} to the property name. Otherwise, you'll either get an error message or the property will be interpreted as a static value and be the same for every result.
Note: If your grouping needs more than one property, you can combine multiple properties. For example, if you want to see the disk space on the c: drive of different computers, your grouping needs to be c: drive and computer. You can combine them in one mustache {{PropertyForComputer + PropertyForC:Drive}} or keep them in separate mustaches {{PropertyForComputer} {PropertyForC:Drive}}.
timestamp
Here you define the time series to be used for the visualization.
To enter your timestamp, you have to find the property that contains it. If there is a mustache picker you can use this to see every property from the response data. Pick the property that contains the timestamp you want the visualization to use.
Note: If you type in the property, make sure you add the mustache {{}} to the property name. Otherwise, you'll either get an error message or the property will be interpreted as a static value and be the same for every result.
Note: Timestamps that are supported are Unix timestamp in milliseconds or the ISO 8601 format
metrics
Here you define which value the graph will show. For example, if you want to see the response time of different servers, your metric value would be response time. If you want to see the number of tickets, your metric value would be number (of tickets).
To enter your metric value, you have to find the property that contains that value. You can use the mustache picker to see every property returned from the response data. Pick the property that contains the value you want your graph to show
Note: If you type in the property, make sure you add the mustache {{}} to the property name. Otherwise, you'll either get an error message or the property will be interpreted as a static value and be the same for every result.
Note: The metric value must be a numeric object. If an API returns values as strings, you can convert them from a string to a numeric object with the parseFloat() function.
Info: You can manipulate the value by adding operators to add, substract, divide or multiply. You can pick additonal properties from the response data or insert plain text for those functions. For example, if you want to multiply two properties you can do that by entering {{PropertyForMetricValue*PropertyForOtherMetricValue2}} . If you want to change Kb in Gb you can divide the value by 1024: {{PropertyForMetricValue/1024}}. You can also use more elaborate functions according to JavaScript syntax.
Extract multiple metrics:
If you want to see more than one value, you can tick the "Extract multiple metrics" checkbox. You can manipulate those metrics exactly like the first metric you chose. The metrics won't affect each other, they are all treated as separate metrics. Each value will get its own series (a line in a line graph, a bar in a bar graph etc.).
Threshold
You can choose to apply a threshold line at a specified value, and whether you wish to fill above or below this value, or just show the line. For example, for free disk space you might want to fill below the line to highlight when space goes below a particular threshold. For processor information you might want to fill above the line to highlight when processor percentage goes above that threshold. The threshold is also shown on the drilldown view.
Data range
The Data Range option allows you to choose the range of data the graph will display. For line graphs, this means the data on the y-axis.
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.
Display
Height:
Allows you to set the height of the tile with a slider.
Show hover details:
Shows the value for all lines at any point you hover. There may not be a value exactly where you hover so the value is interpolated from the values either side.
Solid bars:
Show the bars as solid color or translucent.
Custom colors:
You can display the data in different colors based on labels. For example, you can display data in green for a specific user.
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 label property and manipulate it with JavaScript String and Regex APIs. When you click on the mustache picker, you'll get some examples:
Condition is true if the label contains something For example: {{label.indexOf('SQL') != -1}} (The color you pick will be used if the label contains 'SQL')
Condition is true if the label contains multiple things For example: {{label.match(/C:|D:|E:/) != null}} (The color you pick will be used if the label contains 'C:', 'D:' or 'E:')
Condition is true if the label contains multiple things with multiple variations For example: {{label.match(/^[Ss]erver[0-9]+$/) != null}} (The color you pick will be used if the label is 'Server' or 'server' with a number after it)
Label
Allows you to change the label of the results.
Show legend:
Allows you to show or hide the legend of the graph.
Label:
auto
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.
Property names that contain hyphens (for example properties.name-with-hyphens) can't be processed due to a JavaScript limitation. If you want to use a property that contains a hyphen, you have two options:
If you have access to the data source and can change the name of the property, change the name of the property to a name without hyphens. For example, if your Elasticsearch query uses a property (an aggregation, a grouping or any other property you want to use) with a name that contains a hyphen, you can either access your Elasticsearch instance and change the name there or you can overwrite the name in the query dsl field.
If you can't change the name of the property, you need to enter the property name in the following format: Original property name: {{properties.name-with-hyphens.value}} New format: {{properties['name-with-hyphens'].value}}
Data mapping
Property names that contain hyphens (for example properties.name-with-hyphens) can't be processed due to a JavaScript limitation. If you want to use a property that contains a hyphen, you have two options:
If you have access to the data source and can change the name of the property, change the name of the property to a name without hyphens. For example, if your Elasticsearch query uses a property (an aggregation, a grouping or any other property you want to use) with a name that contains a hyphen, you can either access your Elasticsearch instance and change the name there or you can overwrite the name in the query dsl field.
If you can't change the name of the property, you need to enter the property name in the following format: Original property name: {{properties.name-with-hyphens.value}} New format: {{properties['name-with-hyphens'].value}}
grouping
Here you can define a group to take a closer look at the graph's value(s). Each item in the group will create its own series (a line in a line graph, a bar in a bar graph etc.). For example, if you group the value response time by servers on a line graph, you'll see one line per server, each line showing you the response time for this one server over time.
To enter your grouping, you have to find the property that contains it. You can use the mustache picker to see every property returned from the response data. Pick the property that contains the grouping you want your graph to show.
Note: If you type in the property, make sure you add the mustache {{}} to the property name. Otherwise, you'll either get an error message or the property will be interpreted as a static value and be the same for every result.
Note: If your grouping needs more than one property, you can combine multiple properties. For example, if you want to see the disk space on the c: drive of different computers, your grouping needs to be c: drive and computer. You can combine them in one mustache {{PropertyForComputer + PropertyForC:Drive}} or keep them in separate mustaches {{PropertyForComputer} {PropertyForC:Drive}}.
timestamp
Here you define the time series to be used for the visualization.
To enter your timestamp, you have to find the property that contains it. If there is a mustache picker you can use this to see every property from the response data. Pick the property that contains the timestamp you want the visualization to use.
Note: If you type in the property, make sure you add the mustache {{}} to the property name. Otherwise, you'll either get an error message or the property will be interpreted as a static value and be the same for every result.
Note: Timestamps that are supported are Unix timestamp in milliseconds or the ISO 8601 format
metrics
Here you define which value the graph will show. For example, if you want to see the response time of different servers, your metric value would be response time. If you want to see the number of tickets, your metric value would be number (of tickets).
To enter your metric value, you have to find the property that contains that value. You can use the mustache picker to see every property returned from the response data. Pick the property that contains the value you want your graph to show
Note: If you type in the property, make sure you add the mustache {{}} to the property name. Otherwise, you'll either get an error message or the property will be interpreted as a static value and be the same for every result.
Note: The metric value must be a numeric object. If an API returns values as strings, you can convert them from a string to a numeric object with the parseFloat() function.
Info: You can manipulate the value by adding operators to add, substract, divide or multiply. You can pick additonal properties from the response data or insert plain text for those functions. For example, if you want to multiply two properties you can do that by entering {{PropertyForMetricValue*PropertyForOtherMetricValue2}} . If you want to change Kb in Gb you can divide the value by 1024: {{PropertyForMetricValue/1024}}. You can also use more elaborate functions according to JavaScript syntax.
Extract multiple metrics:
If you want to see more than one value, you can tick the "Extract multiple metrics" checkbox. You can manipulate those metrics exactly like the first metric you chose. The metrics won't affect each other, they are all treated as separate metrics. Each value will get its own series (a line in a line graph, a bar in a bar graph etc.).
Data Range
The Data Range option allows you to choose the range of data the graph will display. For line graphs, this means the data on the y-axis.
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.
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).
Label
Allows you to change the label of the results.
auto
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.
Property names that contain hyphens (for example properties.name-with-hyphens) can't be processed due to a JavaScript limitation. If you want to use a property that contains a hyphen, you have two options:
If you have access to the data source and can change the name of the property, change the name of the property to a name without hyphens. For example, if your Elasticsearch query uses a property (an aggregation, a grouping or any other property you want to use) with a name that contains a hyphen, you can either access your Elasticsearch instance and change the name there or you can overwrite the name in the query dsl field.
If you can't change the name of the property, you need to enter the property name in the following format: Original property name: {{properties.name-with-hyphens.value}} New format: {{properties['name-with-hyphens'].value}}
Color
multiple colors
Here you can enable or disable graph color matching.
If you turn color matching on, one item (a specific resource, object, site, anything you are displaying in your graphs) is shown in the same color in different graphs on one dashboard. You can use either color matching or custom colors (colors based on values), they cannot both be used at the same time.
custom colors
Setting colors based on values
You can display the data in different colors based on values you define here. For example, you can display the data 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 pick will be used if the value is less than 10)
Value is present in the result (scalar tiles only) For example: value.IndexOf('error') != -1 (The color you pick will be used if the string value "error" is present in the results)
Value matches one of the regular expressions you defined (scalar tiles only) For example: value.match(/healthy|good|up/) (The color you picked will be used if the string values are healthy, good, or up)
You are able to combine value matching with label matching.
Setting colors based on labels
You can display the data in different colors based on labels. For example, you can display data in green for a specific user.
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 label property and manipulate it with JavaScript String and Regex APIs. When you click on the mustache picker, you'll get some examples:
Condition is true if the label contains something For example: {{label.indexOf('SQL') != -1}} (The color you pick will be used if the label contains 'SQL')
Condition is true if the label contains multiple things For example: {{label.match(/C:|D:|E:/) != null}} (The color you pick will be used if the label contains 'C:', 'D:' or 'E:')
Condition is true if the label contains multiple things with multiple variations For example: {{label.match(/^[Ss]erver[0-9]+$/) != null}} (The color you pick will be used if the label is 'Server' or 'server' with a number after it)
You are able to combine label matching with value matching.
Data mapping
Property names that contain hyphens (for example properties.name-with-hyphens) can't be processed due to a JavaScript limitation. If you want to use a property that contains a hyphen, you have two options:
If you have access to the data source and can change the name of the property, change the name of the property to a name without hyphens. For example, if your Elasticsearch query uses a property (an aggregation, a grouping or any other property you want to use) with a name that contains a hyphen, you can either access your Elasticsearch instance and change the name there or you can overwrite the name in the query dsl field.
If you can't change the name of the property, you need to enter the property name in the following format: Original property name: {{properties.name-with-hyphens.value}} New format: {{properties['name-with-hyphens'].value}}
data aggregation
Here you can aggregate the results of the return data.
none: No aggregation, use raw data (for example, when the data provided by the API has already been aggregated in some way due to the type of request).
count: Count how many results are returned (for example, when you return a list of unavailable servers, you can count the results to show how many servers are unavailable).
sum: Show the sum of all results (for example, your return data is a list of tickets in various states and you want to know how many tickets there are in total). For sum, you need numeric values. If your return data contains strings, you need to convert them into a numeric value.
grouping
Here you can define a group to take a closer look at the graph's value(s). Each item in the group will create its own series (a line in a line graph, a bar in a bar graph etc.). For example, if you group the value response time by servers on a line graph, you'll see one line per server, each line showing you the response time for this one server over time.
To enter your grouping, you have to find the property that contains it. You can use the mustache picker to see every property returned from the response data. Pick the property that contains the grouping you want your graph to show.
Note: If you type in the property, make sure you add the mustache {{}} to the property name. Otherwise, you'll either get an error message or the property will be interpreted as a static value and be the same for every result.
Note: If your grouping needs more than one property, you can combine multiple properties. For example, if you want to see the disk space on the c: drive of different computers, your grouping needs to be c: drive and computer. You can combine them in one mustache {{PropertyForComputer + PropertyForC:Drive}} or keep them in separate mustaches {{PropertyForComputer} {PropertyForC:Drive}}.
metrics
Here you define which value the graph will show. For example, if you want to see the response time of different servers, your metric value would be response time. If you want to see the number of tickets, your metric value would be number (of tickets).
To enter your metric value, you have to find the property that contains that value. You can use the mustache picker to see every property returned from the response data. Pick the property that contains the value you want your graph to show
Note: If you type in the property, make sure you add the mustache {{}} to the property name. Otherwise, you'll either get an error message or the property will be interpreted as a static value and be the same for every result.
Note: The metric value must be a numeric object. If an API returns values as strings, you can convert them from a string to a numeric object with the parseFloat() function.
Info: You can manipulate the value by adding operators to add, substract, divide or multiply. You can pick additonal properties from the response data or insert plain text for those functions. For example, if you want to multiply two properties you can do that by entering {{PropertyForMetricValue*PropertyForOtherMetricValue2}} . If you want to change Kb in Gb you can divide the value by 1024: {{PropertyForMetricValue/1024}}. You can also use more elaborate functions according to JavaScript syntax.
Extract multiple metrics:
If you want to see more than one value, you can tick the "Extract multiple metrics" checkbox. You can manipulate those metrics exactly like the first metric you chose. The metrics won't affect each other, they are all treated as separate metrics. Each value will get its own series (a line in a line graph, a bar in a bar graph etc.).
Data Range
The Data Range option allows you to choose the range of data the graph will display. For line graphs, this means the data on the y-axis.
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.
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).
Value
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.
Label
Allows you to change the label of the results.
auto
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.
Property names that contain hyphens (for example properties.name-with-hyphens) can't be processed due to a JavaScript limitation. If you want to use a property that contains a hyphen, you have two options:
If you have access to the data source and can change the name of the property, change the name of the property to a name without hyphens. For example, if your Elasticsearch query uses a property (an aggregation, a grouping or any other property you want to use) with a name that contains a hyphen, you can either access your Elasticsearch instance and change the name there or you can overwrite the name in the query dsl field.
If you can't change the name of the property, you need to enter the property name in the following format: Original property name: {{properties.name-with-hyphens.value}} New format: {{properties['name-with-hyphens'].value}}
Display
Vertical:
Tick this option to show vertical bars, otherwise horizontal bars are shown.
Bar width:
Allows you to set the width of the bars with a slider.
Color
multiple colors
Here you can enable or disable graph color matching.
If you turn color matching on, one item (a specific resource, object, site, anything you are displaying in your graphs) is shown in the same color in different graphs on one dashboard. You can use either color matching or custom colors (colors based on values), they cannot both be used at the same time.
custom colors
Setting colors based on values
You can display the data in different colors based on values you define here. For example, you can display the data 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 pick will be used if the value is less than 10)
Value is present in the result (scalar tiles only) For example: value.IndexOf('error') != -1 (The color you pick will be used if the string value "error" is present in the results)
Value matches one of the regular expressions you defined (scalar tiles only) For example: value.match(/healthy|good|up/) (The color you picked will be used if the string values are healthy, good, or up)
You are able to combine value matching with label matching.
Setting colors based on labels
You can display the data in different colors based on labels. For example, you can display data in green for a specific user.
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 label property and manipulate it with JavaScript String and Regex APIs. When you click on the mustache picker, you'll get some examples:
Condition is true if the label contains something For example: {{label.indexOf('SQL') != -1}} (The color you pick will be used if the label contains 'SQL')
Condition is true if the label contains multiple things For example: {{label.match(/C:|D:|E:/) != null}} (The color you pick will be used if the label contains 'C:', 'D:' or 'E:')
Condition is true if the label contains multiple things with multiple variations For example: {{label.match(/^[Ss]erver[0-9]+$/) != null}} (The color you pick will be used if the label is 'Server' or 'server' with a number after it)
You are able to combine label matching with value matching.
Data mapping
Property names that contain hyphens (for example properties.name-with-hyphens) can't be processed due to a JavaScript limitation. If you want to use a property that contains a hyphen, you have two options:
If you have access to the data source and can change the name of the property, change the name of the property to a name without hyphens. For example, if your Elasticsearch query uses a property (an aggregation, a grouping or any other property you want to use) with a name that contains a hyphen, you can either access your Elasticsearch instance and change the name there or you can overwrite the name in the query dsl field.
If you can't change the name of the property, you need to enter the property name in the following format: Original property name: {{properties.name-with-hyphens.value}} New format: {{properties['name-with-hyphens'].value}}
data aggregation
Here you can aggregate the results of the return data.
none: No aggregation, use raw data (for example, when the data provided by the API has already been aggregated in some way due to the type of request).
count: Count how many results are returned (for example, when you return a list of unavailable servers, you can count the results to show how many servers are unavailable).
sum: Show the sum of all results (for example, your return data is a list of tickets in various states and you want to know how many tickets there are in total). For sum, you need numeric values. If your return data contains strings, you need to convert them into a numeric value.
grouping
Here you can define a group to take a closer look at the graph's value(s). Each item in the group will create its own series (a line in a line graph, a bar in a bar graph etc.). For example, if you group the value response time by servers on a line graph, you'll see one line per server, each line showing you the response time for this one server over time.
To enter your grouping, you have to find the property that contains it. You can use the mustache picker to see every property returned from the response data. Pick the property that contains the grouping you want your graph to show.
Note: If you type in the property, make sure you add the mustache {{}} to the property name. Otherwise, you'll either get an error message or the property will be interpreted as a static value and be the same for every result.
Note: If your grouping needs more than one property, you can combine multiple properties. For example, if you want to see the disk space on the c: drive of different computers, your grouping needs to be c: drive and computer. You can combine them in one mustache {{PropertyForComputer + PropertyForC:Drive}} or keep them in separate mustaches {{PropertyForComputer} {PropertyForC:Drive}}.
metrics
Here you define which value the graph will show. For example, if you want to see the response time of different servers, your metric value would be response time. If you want to see the number of tickets, your metric value would be number (of tickets).
To enter your metric value, you have to find the property that contains that value. You can use the mustache picker to see every property returned from the response data. Pick the property that contains the value you want your graph to show
Note: If you type in the property, make sure you add the mustache {{}} to the property name. Otherwise, you'll either get an error message or the property will be interpreted as a static value and be the same for every result.
Note: The metric value must be a numeric object. If an API returns values as strings, you can convert them from a string to a numeric object with the parseFloat() function.
Info: You can manipulate the value by adding operators to add, substract, divide or multiply. You can pick additonal properties from the response data or insert plain text for those functions. For example, if you want to multiply two properties you can do that by entering {{PropertyForMetricValue*PropertyForOtherMetricValue2}} . If you want to change Kb in Gb you can divide the value by 1024: {{PropertyForMetricValue/1024}}. You can also use more elaborate functions according to JavaScript syntax.
Extract multiple metrics:
If you want to see more than one value, you can tick the "Extract multiple metrics" checkbox. You can manipulate those metrics exactly like the first metric you chose. The metrics won't affect each other, they are all treated as separate metrics. Each value will get its own series (a line in a line graph, a bar in a bar graph etc.).
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).
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.
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.
Table or Inline:
Show the legend as a separate table or as labels pointing to the segments. When using Inline you can also hide the segment values, and use the slider to change the size of the labels.
Show zero values in legend:
Will show legend items for values of zero which are otherwise missing from the donut.
Fixed height scrollable legend:
Sets the legend to a fixed height where you can scroll through the items. This means that the tile doesn't become too large if there are many items.
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
Setting colors based on values
You can display the data in different colors based on values you define here. For example, you can display the data 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 pick will be used if the value is less than 10)
Value is present in the result (scalar tiles only) For example: value.IndexOf('error') != -1 (The color you pick will be used if the string value "error" is present in the results)
Value matches one of the regular expressions you defined (scalar tiles only) For example: value.match(/healthy|good|up/) (The color you picked will be used if the string values are healthy, good, or up)
You are able to combine value matching with label matching.
Setting colors based on labels
You can display the data in different colors based on labels. For example, you can display data in green for a specific user.
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 label property and manipulate it with JavaScript String and Regex APIs. When you click on the mustache picker, you'll get some examples:
Condition is true if the label contains something For example: {{label.indexOf('SQL') != -1}} (The color you pick will be used if the label contains 'SQL')
Condition is true if the label contains multiple things For example: {{label.match(/C:|D:|E:/) != null}} (The color you pick will be used if the label contains 'C:', 'D:' or 'E:')
Condition is true if the label contains multiple things with multiple variations For example: {{label.match(/^[Ss]erver[0-9]+$/) != null}} (The color you pick will be used if the label is 'Server' or 'server' with a number after it)
You are able to combine label matching with value matching.
Data mapping
Here you map the status information from your return data to the states of the status icons or blocks. Since every API returns data in a different format, you need to tell the tile where to find the status information and how to interpret it.
Property names that contain hyphens (for example properties.name-with-hyphens) can't be processed due to a JavaScript limitation. If you want to use a property that contains a hyphen, you have two options:
If you have access to the data source and can change the name of the property, change the name of the property to a name without hyphens. For example, if your Elasticsearch query uses a property (an aggregation, a grouping or any other property you want to use) with a name that contains a hyphen, you can either access your Elasticsearch instance and change the name there or you can overwrite the name in the query dsl field.
If you can't change the name of the property, you need to enter the property name in the following format: Original property name: {{properties.name-with-hyphens.value}} New format: {{properties['name-with-hyphens'].value}}
State property: Here you tell SquaredUp DS where to find the status information in the return data. Use the mustache picker to select the property from your return data that contains the status information, for example {{status}}.
Note: If you type in the property, make sure you add the mustache {{}} to the property name. Otherwise, you'll either get an error message or the property will be interpreted as a static value and be the same for every result.
Defining custom states If your return data doesn't contain a specific state property or you want to use your own categories, you can use JavaScript to define states. This allows you to take your return data and define something like "I want result x (number of open tickets, response time, etc.) to be considered as healthy, otherwise the result should be considered unhealthy."
Defining simple custom states
Use case: Your API returns data with a response time (for example, you monitor servers in Pingdom). You want a response time of over 500 ms to be considered as "Warning", anything else should be considered as "Ok".
{{lastresponsetime >= "500" ? "WARNING" : "OK" }}
Mapping:
Healthy
OK
Warning
WARNING
Result: You'll see yellow blocks or icons when the response time is over 500 ms and green blocks or icons if the response time is below 500 ms. There will be no red icons or blocks since there is no mapping for "Critical". There will also be no gray blocks since there will be no "Unknown" state, because the return data will always be either below or over 500 ms.
Displaying only results of a specific type
Use case: Your API returns data with a type and a priority (for example, tickets in Zendesk). You only want to see high priority cases. You consider a case high priority when the two fields "type: problem" and "priority: normal" apply to the result. All other results should be ignored.
{{#if type == "problem" && priority == "normal"}}HIGHPRIORITY{{else}}IGNORE{{/if}}
Mapping:
Critical
HIGHPRIORITY
The checkbox hide tiles where the state is unknown is activated.
Result: You'll see red blocks for the cases you defined as high priority. You'll see no green, yellow, or gray blocks, since they have not been mapped and unknown states are hidden.
Defining custom states based on multiple conditions
Use case: Your API returns data with a state and a response time (for example, you monitor servers in Pingdom). You want to define states based on those criteria. If the status is "up", you consider it healthy as long as it is below 65 ms response time. If it is "up" and over 65 ms, you want it to be considered as "warning" in SquaredUp DS (yellow block or icon). If the state in the response data is "warning" instead of "up", you also want it to be considered as "warning". If the state is "down", you want it to be "critical" in SquaredUp DS.
Result: You'll see green blocks or icons (Healthy) for results with the status "up" and a response time below 65 ms. If the status is "up" but the response time is above 65 ms, you'll see a yellow block or icon (Warning). If the status in the response data is "warning" instead of "up", you'll also see a yellow block, since you defined this also a yellow and yellow is mapped to Warning. If the status is "down", you'll see a red block (Critical). Any other results that don't fit in the categories you defined will be displayed as a gray block or icon (Unknown).
Tip: Since there are two possible causes for the Warning state, you want to be able to tell if the status or the response time caused the issue. Use a custom label or sublabel that shows you the status and the response time in your status icon or block to be able to see what caused the warning.
Defining custom states with a date and time threshold
Use case: Your API returns data with a date and time, as well as a type and a priority (for example, tickets in Zendesk). You want tickets of type problem with a normal priority to be acknowledged within 30 mins, which is why you want to see tickets older than 30 mins highlighted in yellow and older than 45 mins highlighted in red.
Result: You'll see tickets that have been created today (Date.now()), are older than 30 mins (1800000 ms), and are of the type problem with a normal priority as yellow blocks or icons since you mapped 30MINS to Warning. When those tickets are older than 45 mins (2700000 ms), they'll turn red since they are mapped to critical. All other tickets will be displayed as green blocks or icons because all other tickets fall into the OK category that is mapped to Healthy. There will be no gray (unknown) blocks or icons since all tickets will fall into one of the custom states you defined.
State mapping: Here you tell SquaredUp DS how you want the status information to be interpreted. Map the values of the property from your return data to the states of the status icons or blocks. For example, when the {{status}} property from your return data can have the values good, averageand bad, your mapping would look like this:
Healthy
good
Warning
average
Critical
bad
Any value that is not mapped to a state will be interpreted as unknown. The mapped state values define the color of the status icons or blocks:
Healthy
green
Warning
yellow
Critical
red
Unknown
gray
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 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.
Dynamic mustache properties and values you need to change according to your instance are highlighted in bold.
Property names that contain hyphens (for example properties.name-with-hyphens) can't be processed due to a JavaScript limitation. If you want to use a property that contains a hyphen, you have two options:
If you have access to the data source and can change the name of the property, change the name of the property to a name without hyphens. For example, if your Elasticsearch query uses a property (an aggregation, a grouping or any other property you want to use) with a name that contains a hyphen, you can either access your Elasticsearch instance and change the name there or you can overwrite the name in the query dsl field.
If you can't change the name of the property, you need to enter the property name in the following format: Original property name: {{properties.name-with-hyphens.value}} New format: {{properties['name-with-hyphens'].value}}
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.
Property names that contain hyphens (for example properties.name-with-hyphens) can't be processed due to a JavaScript limitation. If you want to use a property that contains a hyphen, you have two options:
If you have access to the data source and can change the name of the property, change the name of the property to a name without hyphens. For example, if your Elasticsearch query uses a property (an aggregation, a grouping or any other property you want to use) with a name that contains a hyphen, you can either access your Elasticsearch instance and change the name there or you can overwrite the name in the query dsl field.
If you can't change the name of the property, you need to enter the property name in the following format: Original property name: {{properties.name-with-hyphens.value}} New format: {{properties['name-with-hyphens'].value}}
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.
Property names that contain hyphens (for example properties.name-with-hyphens) can't be processed due to a JavaScript limitation. If you want to use a property that contains a hyphen, you have two options:
If you have access to the data source and can change the name of the property, change the name of the property to a name without hyphens. For example, if your Elasticsearch query uses a property (an aggregation, a grouping or any other property you want to use) with a name that contains a hyphen, you can either access your Elasticsearch instance and change the name there or you can overwrite the name in the query dsl field.
If you can't change the name of the property, you need to enter the property name in the following format: Original property name: {{properties.name-with-hyphens.value}} New format: {{properties['name-with-hyphens'].value}}
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 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, health state, or health state + availability where objects are sorted by availability (offline or maintenance mode) as well as health state. Ascending or descending
group by
Group by label, health state, or health state + availability where objects are Grouped by availability (offline or maintenance mode) as well as health state, for example Error (Available) and Error (Unavailable). Ascending or descending
Limit:
Allows you to define a maximum number of that will be shown. When 'group by' is used the limit applies to each group individually, for example to show 10 in each health state.
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
Data mapping
Here you map the status information from your return data to the states of the status icons or blocks. Since every API returns data in a different format, you need to tell the tile where to find the status information and how to interpret it.
Property names that contain hyphens (for example properties.name-with-hyphens) can't be processed due to a JavaScript limitation. If you want to use a property that contains a hyphen, you have two options:
If you have access to the data source and can change the name of the property, change the name of the property to a name without hyphens. For example, if your Elasticsearch query uses a property (an aggregation, a grouping or any other property you want to use) with a name that contains a hyphen, you can either access your Elasticsearch instance and change the name there or you can overwrite the name in the query dsl field.
If you can't change the name of the property, you need to enter the property name in the following format: Original property name: {{properties.name-with-hyphens.value}} New format: {{properties['name-with-hyphens'].value}}
State property: Here you tell SquaredUp DS where to find the status information in the return data. Use the mustache picker to select the property from your return data that contains the status information, for example {{status}}.
Note: If you type in the property, make sure you add the mustache {{}} to the property name. Otherwise, you'll either get an error message or the property will be interpreted as a static value and be the same for every result.
Defining custom states If your return data doesn't contain a specific state property or you want to use your own categories, you can use JavaScript to define states. This allows you to take your return data and define something like "I want result x (number of open tickets, response time, etc.) to be considered as healthy, otherwise the result should be considered unhealthy."
Defining simple custom states
Use case: Your API returns data with a response time (for example, you monitor servers in Pingdom). You want a response time of over 500 ms to be considered as "Warning", anything else should be considered as "Ok".
{{lastresponsetime >= "500" ? "WARNING" : "OK" }}
Mapping:
Healthy
OK
Warning
WARNING
Result: You'll see yellow blocks or icons when the response time is over 500 ms and green blocks or icons if the response time is below 500 ms. There will be no red icons or blocks since there is no mapping for "Critical". There will also be no gray blocks since there will be no "Unknown" state, because the return data will always be either below or over 500 ms.
Displaying only results of a specific type
Use case: Your API returns data with a type and a priority (for example, tickets in Zendesk). You only want to see high priority cases. You consider a case high priority when the two fields "type: problem" and "priority: normal" apply to the result. All other results should be ignored.
{{#if type == "problem" && priority == "normal"}}HIGHPRIORITY{{else}}IGNORE{{/if}}
Mapping:
Critical
HIGHPRIORITY
The checkbox hide tiles where the state is unknown is activated.
Result: You'll see red blocks for the cases you defined as high priority. You'll see no green, yellow, or gray blocks, since they have not been mapped and unknown states are hidden.
Defining custom states based on multiple conditions
Use case: Your API returns data with a state and a response time (for example, you monitor servers in Pingdom). You want to define states based on those criteria. If the status is "up", you consider it healthy as long as it is below 65 ms response time. If it is "up" and over 65 ms, you want it to be considered as "warning" in SquaredUp DS (yellow block or icon). If the state in the response data is "warning" instead of "up", you also want it to be considered as "warning". If the state is "down", you want it to be "critical" in SquaredUp DS.
Result: You'll see green blocks or icons (Healthy) for results with the status "up" and a response time below 65 ms. If the status is "up" but the response time is above 65 ms, you'll see a yellow block or icon (Warning). If the status in the response data is "warning" instead of "up", you'll also see a yellow block, since you defined this also a yellow and yellow is mapped to Warning. If the status is "down", you'll see a red block (Critical). Any other results that don't fit in the categories you defined will be displayed as a gray block or icon (Unknown).
Tip: Since there are two possible causes for the Warning state, you want to be able to tell if the status or the response time caused the issue. Use a custom label or sublabel that shows you the status and the response time in your status icon or block to be able to see what caused the warning.
Defining custom states with a date and time threshold
Use case: Your API returns data with a date and time, as well as a type and a priority (for example, tickets in Zendesk). You want tickets of type problem with a normal priority to be acknowledged within 30 mins, which is why you want to see tickets older than 30 mins highlighted in yellow and older than 45 mins highlighted in red.
Result: You'll see tickets that have been created today (Date.now()), are older than 30 mins (1800000 ms), and are of the type problem with a normal priority as yellow blocks or icons since you mapped 30MINS to Warning. When those tickets are older than 45 mins (2700000 ms), they'll turn red since they are mapped to critical. All other tickets will be displayed as green blocks or icons because all other tickets fall into the OK category that is mapped to Healthy. There will be no gray (unknown) blocks or icons since all tickets will fall into one of the custom states you defined.
State mapping: Here you tell SquaredUp DS how you want the status information to be interpreted. Map the values of the property from your return data to the states of the status icons or blocks. For example, when the {{status}} property from your return data can have the values good, averageand bad, your mapping would look like this:
Healthy
good
Warning
average
Critical
bad
Any value that is not mapped to a state will be interpreted as unknown. The mapped state values define the color of the status icons or blocks:
Healthy
green
Warning
yellow
Critical
red
Unknown
gray
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 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.
Dynamic mustache properties and values you need to change according to your instance are highlighted in bold.
Property names that contain hyphens (for example properties.name-with-hyphens) can't be processed due to a JavaScript limitation. If you want to use a property that contains a hyphen, you have two options:
If you have access to the data source and can change the name of the property, change the name of the property to a name without hyphens. For example, if your Elasticsearch query uses a property (an aggregation, a grouping or any other property you want to use) with a name that contains a hyphen, you can either access your Elasticsearch instance and change the name there or you can overwrite the name in the query dsl field.
If you can't change the name of the property, you need to enter the property name in the following format: Original property name: {{properties.name-with-hyphens.value}} New format: {{properties['name-with-hyphens'].value}}
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.
Property names that contain hyphens (for example properties.name-with-hyphens) can't be processed due to a JavaScript limitation. If you want to use a property that contains a hyphen, you have two options:
If you have access to the data source and can change the name of the property, change the name of the property to a name without hyphens. For example, if your Elasticsearch query uses a property (an aggregation, a grouping or any other property you want to use) with a name that contains a hyphen, you can either access your Elasticsearch instance and change the name there or you can overwrite the name in the query dsl field.
If you can't change the name of the property, you need to enter the property name in the following format: Original property name: {{properties.name-with-hyphens.value}} New format: {{properties['name-with-hyphens'].value}}
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.
Property names that contain hyphens (for example properties.name-with-hyphens) can't be processed due to a JavaScript limitation. If you want to use a property that contains a hyphen, you have two options:
If you have access to the data source and can change the name of the property, change the name of the property to a name without hyphens. For example, if your Elasticsearch query uses a property (an aggregation, a grouping or any other property you want to use) with a name that contains a hyphen, you can either access your Elasticsearch instance and change the name there or you can overwrite the name in the query dsl field.
If you can't change the name of the property, you need to enter the property name in the following format: Original property name: {{properties.name-with-hyphens.value}} New format: {{properties['name-with-hyphens'].value}}
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 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, health state, or health state + availability where objects are sorted by availability (offline or maintenance mode) as well as health state. Ascending or descending
group by
Group by label, health state, or health state + availability where objects are Grouped by availability (offline or maintenance mode) as well as health state, for example Error (Available) and Error (Unavailable). Ascending or descending
Limit:
Allows you to define a maximum number of that will be shown. When 'group by' is used the limit applies to each group individually, for example to show 10 in each health state.
Blocks
Here you can set the number of columns for the blocks, their height and the font size within the blocks.
Data mapping
Data aggregation
You can optionally choose the sum aggregation which uses the field you enter in the value box to sum up events for dates.
Timestamp
Here you define the time series to be used for the visualization.
To enter your timestamp, you have to find the property that contains it. If there is a mustache picker you can use this to see every property from the response data. Pick the property that contains the timestamp you want the visualization to use.
Note: If you type in the property, make sure you add the mustache {{}} to the property name. Otherwise, you'll either get an error message or the property will be interpreted as a static value and be the same for every result.
Note: Timestamps that are supported are Unix timestamp in milliseconds or the ISO 8601 format
Display
Choose to use squares or circles, and optionally whether to hide weekends, week days and/or empty days.
Color
Here you can choose the color scheme for your heatmap. Higher values are shown in a lighter shade of the color, and lower values in darker shades.
Data Range
The Data Range option allows you to choose the range of data the graph will display. For line graphs, this means the data on the y-axis.
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.
Click done to save the tile.
The tile now shows data according to your settings.
One thing to keep in mind when making queries is that the Web API tile does not support request paging. Some APIs will not return all the query results in a single request (say limiting each request to only 100 items), and require the user to make multiple subsequent requests to get the entire results set. Since there is no standard way of doing this, we are currently unable to support it.
This may mean your tile is only able to display the most recent results, and may be an issue if you are say trying to query for every incident in the system and display a donut showing the counts of incidents in each status. To avoid this, if you need to display summaries either query API endpoints that provide summarised information for you, or make sure you indicate in the tile name/description that this may be only recent results.
If your API does not page requests and instead can return large datasets in a single request, consider adding limits to your query if the API supports it. If your query returns 10,000 results, you may experience a tile that takes a long time to load and display data. Don't show data for all time when the last 30 days will do!
Where to use this code: You can use this code in Web API tiles for the Donut or Bar Graph visualization. Open the Data Mapping panel, set the data aggregation to count and enter this code in the Grouping field.
When to use this code: Let's say you want to group by the field status but aren't happy with the names of the field values. In this example, the values for status are 1,2, and 3 which doesn't tell your users much about the meaning of those values. With this code you can rename them to warning, critical, and healthy to make the values easier to understand:
{{#if status === 1}}Warning{{elseif status === 2}}Critical{{elseif status === 3}}Healthy{{else}}Unknown{{/if}}
If your field values are not numeric values but strings, you need to wrap them like this:
{{#if status === "Status A"}}Warning{{elseif status === "Status B"}}Critical{{elseif status === "Status C"}}Healthy{{else}}Unknown{{/if}}
http://jsonplaceholder.typicode.com/ is a JSON REST API used for testing services and this example demonstrates how you would retrieve data from this API and show it using SquaredUp DS.
Browse to http://jsonplaceholder.typicode.com/posts The data shown is a list of posts which we can show in SquaredUp DS as a table.
Create a new dashboard and click on the Web API tile.
Select Web API (Grid) and click next.
Leave the scope as it is and click next.
Select generic from the drop down list for the provider, and click next.
Paste the web address from step 1 into the URL box. For help customizing the columns of data see How to use the Grid Designer
Click done.
The data from the external API is now shown in SquaredUp DS.
It is important to note that this data will refresh along with the rest of your dashboard and is great for showing tabular data such as a list of open support tickets or configuration changes.
One long list
Column list
Icons only
