PowerShell tile
About using PowerShell in SquaredUp DS
You can use PowerShell to visualize data from external tools and data sources directly in your SquaredUp DS dashboards. The PowerShell feature consists of three components:
PowerShell tiles contain the individual PowerShell script for the tile.
A PowerShell tile can be added to any of your dashboards. Each PowerShell tile consists of a PowerShell Run As account, an optional PowerShell profile, and a script that is inserted within the tile.
Since the script in the tile isn't encrypted you shouldn't store any sensitive data like passwords in a PowerShell tile.
Only administrators can add script to a PowerShell tile. Users who can edit tiles due to their Team Folder permissions can see the script, but they will get an error message when they try to save changes (for more information about security measures for users trying to edit sensitive tiles see Signing and security for sensitive tiles).
Jump to How to configure a PowerShell tilePowerShell profiles contain re-usable scripts with encrypted sensitive data.
A PowerShell profile is created once and then can be re-used in PowerShell tiles. Only administrators can create PowerShell profiles. Since PowerShell profile scripts are encrypted and can only be seen by administrators, you can safely store scripts that contain credentials, authentication tokens, etc. You can also load external modules in a profile (e.g. a VMWare module downloaded from the internet).
You can also use PowerShell profiles for more sophisticated code, for example if your tile needs to combine data from two different API connections, you can put credentials for both connections in the profile. Make sure to give your profile a meaningful description to remember which provider(s) the profile connects to and what it does with the data.
SquaredUp DS users who can edit tiles due to their Team Folder permissions can use PowerShell profiles in their PowerShell tiles, but they can’t see the underlying script.
Jump to How to configure a PowerShell profilePowerShell Run As accounts contain the credentials that define the permissions deciding how PowerShell scripts are run (both the script in the tile and the profile script chosen for the tile).
The PowerShell Run As account Default comes with every SquaredUp DS installation and uses the SquaredUp DS app pool identity to run the scripts. Since running PowerShell scripts within the SquaredUp DS application pool process can pose a security risk and affect SquaredUp DS performance, you can change the default Run As to use a different account.
You can also add new Run As accounts to be able to execute scripts with different credentials.
Jump to Managing PowerShell Run As accounts
Required PowerShell version
Using PowerShell in SquaredUp DS requires PowerShell version 5.1 and above. If you want to use .NET Core PowerShell scripts, you need to have .NET Core 6.0 installed.
If you are using HA, make sure .NET Core is installed on all HA machines. If you configured a tile to use the NET core option and try to view the tile on a HA machine that doesn't have .NET Core installed, the tile will display the error message "PowerShell host process returned errors: A fatal error occurred. The required library hostfxr.dll could not be found."
When do you use a PowerShell tile?
Since PowerShell tiles contain any PowerShell script you want, there are a lot of different use cases for them. Here are some examples:
You can use a PowerShell tile when the Web API tile is not sufficient for your requirements:
- You can retrieve and combine data from different APIs. For example, if you want a status to turn “critical” when two different sources return “unhealthy”, you can use a script that retrieves data from Pingdom and from PagerDuty. If only Pingdom or PagerDuty returns “unhealthy”, you want the status to be “unhealthy”, but if both sources return “unhealthy”, you want the status to turn “critical”.
- You can make several different API requests at once to the same API and bring them together in one visualization.
- You can manipulate API requests and responses. For example, if you want to include authentication tokens or other complexities in your API request.
- You can retrieve data from management tools that don’t support REST API.
You can access and visualize data from locally stored files (CSV and TXT). You can also merge data from the different file sources. For example, you can merge data from daily CSV log files into a monthly overview.
You can use a PowerShell tile when the SQL tile is not sufficient for your requirements:
- You can retrieve data from management tools that don’t support SQL.
- You can connect to non-SQL databases, such as Oracle, PostGre and MySQL.
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:
How to configure a PowerShell tile
- Add a new tile to a dashboard and click on Integrations > PowerShell.
- Choose the visualization for your PowerShell 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.
- Environment:
Run As
Choose the Run As account you want to use for running the profile and the script in this tile. Choosing a Run As is mandatory. If you haven't configured any Run As accounts, the tile will use the Default Run As.
Note: If you click on add new, you can create a new Run As in a new tab. Click on reload after you created the new Run As to be able to choose it from the drop-down.ProfilePowerShell Run As accounts contain the credentials that define the permissions deciding how PowerShell scripts are run (both the script in the tile and the profile script chosen for the tile).
The PowerShell Run As account Default comes with every SquaredUp DS installation and uses the SquaredUp DS app pool identity to run the scripts. Since running PowerShell scripts within the SquaredUp DS application pool process can pose a security risk and affect SquaredUp DS performance, you can change the default Run As to use a different account.
You can also add new Run As accounts to be able to execute scripts with different credentials.
Jump to Managing PowerShell Run As accounts to learn more about Run As accounts.
If you want to use a PowerShell profile for this tile, choose the profile (optional).
Note: If you click on add new, you can create a new profile in a new tab. Click on reload after you created the new profile to be able to choose it from the drop-down.AdvancedPowerShell profiles contain re-usable scripts with encrypted sensitive data.
A PowerShell profile is created once and then can be re-used in PowerShell tiles. Only administrators can create PowerShell profiles. Since PowerShell profile scripts are encrypted and can only be seen by administrators, you can safely store scripts that contain credentials, authentication tokens, etc. You can also load external modules in a profile (e.g. a VMWare module downloaded from the internet).
You can also use PowerShell profiles for more sophisticated code, for example if your tile needs to combine data from two different API connections, you can put credentials for both connections in the profile. Make sure to give your profile a meaningful description to remember which provider(s) the profile connects to and what it does with the data.
SquaredUp DS users who can edit tiles due to their Team Folder permissions can use PowerShell profiles in their PowerShell tiles, but they can’t see the underlying script.
Execution environment:Choose the execution environment your PowerShell script was intended for to make sure it gets executed correctly:
- Windows PowerShell (.NET framework)
- PowerShell (.NET Core)
Note:
The .NET Core option is only available if it is installed on your server, .NET Core is not automatically installed with SquaredUp DS.
Note:
If you are using HA, make sure .NET Core is installed on all HA machines. If you configured a tile to use the NET core option and try to view the tile on a HA machine that doesn't have .NET Core installed, the tile will display the error message "PowerShell host process returned errors: A fatal error occurred. The required library hostfxr.dll could not be found."
Interval:The interval enables you to limit how often a script gets executed in SquaredUp DS. For example, you might want to run a script less frequently if it makes a request to an API that charges you per request or an API that puts a limit on how many requests you can make within a time period.
How does the interval affect how often PowerShell scripts are run in SquaredUp DS?
By default, a PowerShell script will be executed every time the dashboard refreshes (every minute). If you set the interval to 10 mins, you create a 10 min cache for your script results and your script won't run until the last fetched results are 10 mins old.
The interval is not a schedule, it does not trigger a script execution every 10 mins. Scripts will only be executed when the dashboard is reloaded and the results in the cache are older than the interval (10 mins in this example). The cache is valid for all users, which means if another user opens the same dashboard in SquaredUp DS or via Open Access and the script has been executed 5 mins ago, they see the cached results immediately but have to wait for 5 mins to see fresh results.
Can multiple tiles share the same cache?
Identical tiles share the same cache. For tiles to be considered identical, the JSON code of both tiles needs to be identical. If you want to use identical tiles to reduce the load on the back-end, you can copy the JSON from one tile and paste it into a different tile.
The shared cache works across your whole SquaredUp DS instance on:- All dashboards (including Open Access dashboards), as long as they use the same page timeframe
- Perspectives for the same object on the same drill-down using the same page timeframe
You can control when the script will run into a timeout. By default, scripts will be aborted after 1 min. You can define a longer timeout for long running scripts.
Best practice:
Even if you can use long running scripts by setting the timeout to several minutes, you shouldn't use scripts that run for a long time. Long running scripts lead to tiles that show a loading spinner for minutes and are not user-friendly.
Tip:
Instead of setting the timeout for scripts to a longer time, run the script outside of SquaredUp DS periodically, and store the results in a CSV file. Create a PowerShell tile that accesses and visualizes the results in the CSV file.
- Script:
Insert the PowerShell script you want to use. You can view your script's response data in the next step.You can make your PowerShell scripts responsive to the current page timeframe setting:
You can use the clock insert time value button to insert page timeframe and date variables in your query.
As the timeframe values are strings, you need to convert the
$timeFrame
variable into aTimeSpan
object:$timeSpan = [TimeSpan]::MaxValue switch ($timeFrame) { "last1Hour" { $timeSpan = [TimeSpan]::FromHours(1) } "last12Hours" { $timeSpan = [TimeSpan]::FromHours(12) } "last24Hours" { $timeSpan = [TimeSpan]::FromHours(24) } "last7Days" { $timeSpan = [TimeSpan]::FromDays(7) } "last30Days" { $timeSpan = [TimeSpan]::FromDays(30) } "last3Months" { $now = [DateTime]::Now; $timeSpan = $now - $now.AddMonths(-3) } "last6Months" { $now = [DateTime]::Now; $timeSpan = $now - $now.AddMonths(-6) } "last12Months" { $now = [DateTime]::Now; $timeSpan = $now - $now.AddYears(-1) } } "TimeSpan is {0}" -f $timeSpan
The above script returns a
TimeSpan
object calculated from the$timeFrame
variable as the following:You need to have maximum 1 of:
- numeric data type (
System.Byte, System.Int16, System.Int32, System.Int64, System.Single System.Double
, orSystem.Decimal
) System.DateTime
System.String
Alternatively, return an object with a single property of one of the above types.
Example:
Get-Process | Measure-Object
You need to return a collection of objects. The properties can be of any data type, but a property of a given name should have a consistent data type across the collection.
Example:
Get-Process | select Id,Name | sort Name
You need to return a collection of objects. And each object must have:
- for "timestamp": min 1
System.DateTime
property - for "value": min 1 property of numeric data type (
System.Byte, System.Int16, System.Int32, System.Int64, System.Single System.Double
, orSystem.Decimal
) - optional, for "grouping": min 1
System.String
property
Example:
$rnd = New-Object Random $date = [DateTime]::Now.Date $i = 0 $sampleTime = $date + [TimeSpan]::FromMinutes($i) while ($sampleTime -lt [DateTime]::Now) { $sample = $rnd.Next(0,100) New-Object PSObject -Property @{ time = $sampleTime; time2 = $sampleTime; val = $sample; val2 = $sample * 2; } $i++ $sampleTime = $date + [TimeSpan]::FromMinutes($i) }
Column Overrides
You only see the Grouping field in the Column Overrides when your script returns at least one
string
property for each object.Here you define how the returned data is displayed. Use the dropdowns to specify which data/column you want to use:
timestampHere you define the time series to be used for the visualization.
valueHere 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).
show all: If there are multiple values, you can display these by ticking this box. Each value will get its own series (a line in a line graph, a bar in a bar graph etc.).
groupingHere 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.
You need to return a collection of objects. Each object must have:
- For "value": min 1 property of numeric data type (
System.Byte, System.Int16, System.Int32, System.Int64, System.Single System.Double
, orSystem.Decimal
) - For "grouping": min 1
System.String
property
Example:
dir | group-object Extension | sort -property Count -desc
Column Overwrites:
You only see the Grouping field in the Column Overrides when your script returns at least one
string
property for each object.Here you define how the returned data is displayed. Use the dropdowns to specify which data/column you want to use:
valueHere 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).
Only for Bar Graphs:show all: If there are multiple values, you can display these by ticking this box. Each value will get its own series (a line in a line graph, a bar in a bar graph etc.).
groupingHere 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.
Click next.You need to return a property named state and this must contain the following values: Healthy, Critical, and/or Warning. The values are not case-sensitive.
Any other state values will be displayed as Unknown (gray tile).
The state values define the color of the status icons or blocks:
Healthy
greenWarning
yellowCritical
redUnknown
grayExample:
@{ state = "healthy"; id = "1"; name = "Object 1"; metric = "90%" } @{ state = "healthy"; id = "2"; name = "Object 2"; metric = "83%" } @{ state = "warning"; id = "3"; name = "Object 3"; metric = "63%" } @{ state = "critical"; id = "4"; name = "Object 4"; metric = "22%" } @{ state = "error"; id = "5"; name = "Object 5"; metric = "unknown" }
- numeric data type (
- Response data:
Here you can check if your script works and returns the expected data. - Configure the settings for the visualization you chose:
Scalar
Font sizeAllows you to set the font size of the value in the tile.
AlignmentSelect the scalar text alignment. Choose from left, center or right.UnitAllows 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 formatterAllows 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 arehealthy
,good
, orup
)
- Value is greater than something, less than something, etc.
Display:
Here you decide how the color is used:
Tile backgroundHighlight the tile in the color you defined.Text foregroundDisplay 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
, where123
is the ticket ID, you can use the dynamic property that contains the ticket ID and enter the dynamic URLhttps://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.
ServiceNow incidents:
https://<your-instance>.service-now.com/nav_to.do?uri=%2Fincident.do%3Fsys_id%3D{{sys_id}}
PagerDuty incidents:
{{incident.html_url}}
Azure DevOps projects:
https://dev.azure.com/<your-instance>/{{name}}
Azure DevOps builds:
https://dev.azure.com/<your-instance>/_build/results?buildId={{id}}
Zendesk tickets:
https://<your-instance>.zendesk.com/agent/tickets/{{id}}
Azure Application Insights
https://portal.azure.com/#@squaredup.net/resource/{{ResourceId}}
Grid columns
Grid columns opens the grid designer, where you can show or hide columns, change the order of columns, edit column names or add custom columns.
Grid options
Row linkAllows 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
, where123
is the ticket ID, you can use the dynamic property that contains the ticket ID and enter the dynamic URLhttps://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.
ServiceNow incidents:
https://<your-instance>.service-now.com/nav_to.do?uri=%2Fincident.do%3Fsys_id%3D{{sys_id}}
PagerDuty incidents:
{{incident.html_url}}
Azure DevOps projects:
https://dev.azure.com/<your-instance>/{{name}}
Azure DevOps builds:
https://dev.azure.com/<your-instance>/_build/results?buildId={{id}}
Zendesk tickets:
https://<your-instance>.zendesk.com/agent/tickets/{{id}}
Azure Application Insights
https://portal.azure.com/#@squaredup.net/resource/{{ResourceId}}
Show column headersYou can choose between showing or hiding the header for all columns.
Expand rows automaticallyActivate 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 displayedYou 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 sizeUse 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.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.
percentageShows 0 to 100fit to dataShows the data minimum to data maximumfit to data (from zero)Shows from 0 to the data maximumcustomAllows you to specify the min and maxcustom fitAllows 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)
- Condition is true if the label contains something
Label
Allows you to change the label of the results.
Show legend:
Allows you to show or hide the legend of the graph.
Label:
autoChoose this option if you want to use the default label that has been created automatically.
customHere you can change the label to a custom label. You can use static text and dynamic properties. Use the mustache picker to select dynamic properties from the response data to use them as labels.
For more information see How to use Custom Labels
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}}
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.
percentageShows 0 to 100fit to dataShows the data minimum to data maximumfit to data (from zero)Shows from 0 to the data maximumcustomAllows you to specify the min and maxcustom fitAllows 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)
- Condition is true if the label contains something
Label
Allows you to change the label of the results.
Show legend:
Allows you to show or hide the legend of the graph.
Label:
autoChoose this option if you want to use the default label that has been created automatically.
customHere you can change the label to a custom label. You can use static text and dynamic properties. Use the mustache picker to select dynamic properties from the response data to use them as labels.
For more information see How to use Custom Labels
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 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.
percentageShows 0 to 100fit to dataShows the data minimum to data maximumfit to data (from zero)Shows from 0 to the data maximumcustomAllows you to specify the min and maxcustom fitAllows 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.Label
Allows you to change the label of the results.
autoChoose this option if you want to use the default label that has been created automatically.
customHere you can change the label to a custom label. You can use static text and dynamic properties. Use the mustache picker to select dynamic properties from the response data to use them as labels.
For more information see How to use Custom Labels
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 colorsHere 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 colorsSetting 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 arehealthy
,good
, orup
)
- Value is greater than something, less than something, etc.
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)
- Condition is true if the label contains something
You are able to combine label matching with value matching.
Note: If you want to return results in a specific order, you need to sort the results within your script since there is no sorting panel in the settings.
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.
percentageShows 0 to 100fit to dataShows the data minimum to data maximumfit to data (from zero)Shows from 0 to the data maximumcustomAllows you to specify the min and maxcustom fitAllows 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.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.
autoChoose this option if you want to use the default label that has been created automatically.
customHere you can change the label to a custom label. You can use static text and dynamic properties. Use the mustache picker to select dynamic properties from the response data to use them as labels.
For more information see How to use Custom Labels
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 colorsHere 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 colorsSetting 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 arehealthy
,good
, orup
)
- Value is greater than something, less than something, etc.
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)
- Condition is true if the label contains something
You are able to combine label matching with value matching.
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:
DefaultDisplays the donut scaled to the height of the tile.FillEnlarges 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.
General10 different colors without specific meaningPriorities5 different colors representing 5 different priority statesHealth13 different colors representing 3 different health states
(red=unhealthy, green=healthy, gray=unknown)Health24 different colors representing 4 different health states
(red=critical, orange=unhealthy, green=healthy, gray=unknown)Pastel10 different pastel colors without specific meaningBlue4 different shades of blue from dark to lightOrange4 different shades of orange from dark to lightGreen4 different shades of green from dark to lightPink4 different shades of pink from dark to lightCustomSetting 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 arehealthy
,good
, orup
)
- Value is greater than something, less than something, etc.
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)
- Condition is true if the label contains something
You are able to combine label matching with value matching.
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
, where123
is the ticket ID, you can use the dynamic property that contains the ticket ID and enter the dynamic URLhttps://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.
ServiceNow incidents:
https://<your-instance>.service-now.com/nav_to.do?uri=%2Fincident.do%3Fsys_id%3D{{sys_id}}
PagerDuty incidents:
{{incident.html_url}}
Azure DevOps projects:
https://dev.azure.com/<your-instance>/{{name}}
Azure DevOps builds:
https://dev.azure.com/<your-instance>/_build/results?buildId={{id}}
Zendesk tickets:
https://<your-instance>.zendesk.com/agent/tickets/{{id}}
Azure Application Insights
https://portal.azure.com/#@squaredup.net/resource/{{ResourceId}}
Label
Allows you to change the label of the results.
nameChoose this option if you want to use the default label that has been created automatically.
customHere you can change the label to a custom label. You can use static text and dynamic properties. Use the mustache picker to select dynamic properties from the response data to use them as labels.
For more information see How to use Custom Labels
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.
customHere you can change the label to a custom label. You can use static text and dynamic properties. Use the mustache picker to select dynamic properties from the response data to use them as labels.
For more information see How to use Custom Labels
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}}
noneBy 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.
defaultBy 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 bySort 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 descendinggroup byGroup 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 descendingLimit:
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 listColumn listIcons onlyLink 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
, where123
is the ticket ID, you can use the dynamic property that contains the ticket ID and enter the dynamic URLhttps://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.
ServiceNow incidents:
https://<your-instance>.service-now.com/nav_to.do?uri=%2Fincident.do%3Fsys_id%3D{{sys_id}}
PagerDuty incidents:
{{incident.html_url}}
Azure DevOps projects:
https://dev.azure.com/<your-instance>/{{name}}
Azure DevOps builds:
https://dev.azure.com/<your-instance>/_build/results?buildId={{id}}
Zendesk tickets:
https://<your-instance>.zendesk.com/agent/tickets/{{id}}
Azure Application Insights
https://portal.azure.com/#@squaredup.net/resource/{{ResourceId}}
Label
Allows you to change the label of the results.
nameChoose this option if you want to use the default label that has been created automatically.
customHere you can change the label to a custom label. You can use static text and dynamic properties. Use the mustache picker to select dynamic properties from the response data to use them as labels.
For more information see How to use Custom Labels
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.
customHere you can change the label to a custom label. You can use static text and dynamic properties. Use the mustache picker to select dynamic properties from the response data to use them as labels.
For more information see How to use Custom Labels
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}}
noneBy 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.
defaultBy 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 bySort 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 descendinggroup byGroup 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 descendingLimit:
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.
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.
percentageShows 0 to 100fit to dataShows the data minimum to data maximumfit to data (from zero)Shows from 0 to the data maximumcustomAllows you to specify the min and maxcustom fitAllows 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 script.
How to configure a PowerShell profile
- From the top right hand menu ☰ click system.
- Go to the PowerShell tab.
- Click add new profile.
- Enter a name and a description for the new profile.
- Enter the profile script.
- Click add profile.
The profile is now saved and can be used in a PowerShell tile.
When do you need to re-enter PowerShell profiles?
Encrypted information like providers, PowerShell profiles, and Run As accounts can get lost under certain circumstances:
When you are running SquaredUp DS without High Availability (HA):
When you change SquaredUp DS's application pool identity
When you are running SquaredUp DS with High Availability (HA):
When you change the license key you are using.
Make sure that you are able to recreate the information after you changed the app pool identity or your license key, for example by storing them temporarily in a safe place.
Managing PowerShell Run As accounts
PowerShell scripts are very powerful and can cause damage when not properly configured. Your Run As accounts contain the credentials a script uses to run as, which means the Run As determines the permissions a PowerShell script has when it is executed. When you are creating Run As accounts, you want to give your PowerShell scripts the minimum permissions needed so that they can do what you intended for them to do without giving them permissions that can be exploited and could lead to security risks.
Best practices for Run As accounts:
1) For all Run As accounts: Use a service account, not a user account for Run As accounts.
Do not use your own or anyone's personal user account for Run As accounts. Instead, create a new account that is not used by a specific person (a "service account"), but only used for running PowerShell scripts. Consider the permissions of this service account carefully.
Required permissions for service accounts:
The service account you use for Run As must have at least the following permission:
- Allow log on locally
If you don't use the default NetworkService as your application pool identity, you might see the following error message when using Run As accounts: A required privilege is not held by the client.
In this case you need to add the application pool identity to the following policies:
- Adjust memory quotas for a process
- Replace a process-level token (you need to reboot the server for this policy to take effect)
The user credentials you enter for the Run As account are used to run all PowerShell scripts in tiles that use the Run As account. Once created, your Run As account can be used by other SquaredUp DS administrators to run their scripts. By using your or any user's credentials, you lose control over which scripts are executed in the name of this user which can cause privacy issues. In addition to that, users often have more rights than a script would need. By using a user account with extensive permissions, scripts that use the Run As can exploit those permissions.
- From the top right hand menu ☰ click system.
- Go to the PowerShell tab.
- In the Run As section, click on the + button to add a new Run As.
- Enter a name and a description for your new Run As.
Note: Once you have saved the Run As account, you can't change its name anymore. You can always change the description. - Enter the user credentials you want to use for this Run As account.
Do not use your own or anyone's personal user account for Run As accounts. Instead, create a new account that is not used by a specific person (a "service account"), but only used for running PowerShell scripts. Consider the permissions of this service account carefully.
Required permissions for service accounts:
The service account you use for Run As must have at least the following permission:
- Allow log on locally
If you don't use the default NetworkService as your application pool identity, you might see the following error message when using Run As accounts: A required privilege is not held by the client.
In this case you need to add the application pool identity to the following policies:
- Adjust memory quotas for a process
- Replace a process-level token (you need to reboot the server for this policy to take effect)
The user credentials you enter for the Run As account are used to run all PowerShell scripts in tiles that use the Run As account. Once created, your Run As account can be used by other SquaredUp DS administrators to run their scripts. By using your or any user's credentials, you lose control over which scripts are executed in the name of this user which can cause privacy issues. In addition to that, users often have more rights than a script would need. By using a user account with extensive permissions, scripts that use the Run As can exploit those permissions.
- Click save to save the new Run As account.
The Run As account is now available in PowerShell tiles and can be used to execute scripts.
2) We strongly recommend you change the Default Run As account to the credentials you want to use as the default Run As.
Every PowerShell tile needs a Run As and if you haven't created a Run As yet, tiles will use the Default Run As. The Default Run As uses the SquaredUp DS app pool to run scripts. The SquaredUp DS app pool account might grant too many permissions that are not needed for your scripts and can potentially damage your system, which is why using this default account is not recommended. Create a service account that you want to use for the Default Run As and change the Default Run As to use those credentials.
- From the top right hand menu ☰ click system.
- Go to the PowerShell tab.
You see the Default Run As. If you haven't changed the Default Run As account yet, you see a yellow icon indicating that the Run As uses the not recommended default setting "run as SquaredUp DS app pool". - Click on the Default Run As to edit it.
As long as the Run as SquaredUp DS app pool toggle is on, the Default Run As is read only. - Switch the Run as SquaredUp DS app pool toggle to off.
- Change the description to indicate that the Default Run As no longer uses the SquaredUp DS app pool.
- Enter the user credentials you want to use for the Default Run As.
Do not use your own or anyone's personal user account for Run As accounts. Instead, create a new account that is not used by a specific person (a "service account"), but only used for running PowerShell scripts. Consider the permissions of this service account carefully.
Required permissions for service accounts:
The service account you use for Run As must have at least the following permission:
- Allow log on locally
If you don't use the default NetworkService as your application pool identity, you might see the following error message when using Run As accounts: A required privilege is not held by the client.
In this case you need to add the application pool identity to the following policies:
- Adjust memory quotas for a process
- Replace a process-level token (you need to reboot the server for this policy to take effect)
The user credentials you enter for the Run As account are used to run all PowerShell scripts in tiles that use the Run As account. Once created, your Run As account can be used by other SquaredUp DS administrators to run their scripts. By using your or any user's credentials, you lose control over which scripts are executed in the name of this user which can cause privacy issues. In addition to that, users often have more rights than a script would need. By using a user account with extensive permissions, scripts that use the Run As can exploit those permissions.
- Click save to save the changes.
The Default Run As profile now uses the user account you entered when executing scripts.
3) Consider disabling the option to use the SquaredUp DS app pool for the Default Run As.
To make sure that the SquaredUp DS app pool can't be used after you changed the Default Run As, you can disable the option to use the SquaredUp DS App pool.
By default, the toggle Run as SquaredUp DS app pool is visible in the Default Run As account. By setting this toggle to on, the Default Run As can be (re)set to use the SquaredUp DS app pool to run scripts. SquaredUp DSadministrators can disable the toggle to prevent that the SquaredUp DSapp pool can be used for running PowerShell scripts.
- If you haven't already done it, change the Default Run As from using the SquaredUp DS app pool to using the credentials you want to use.
Note: If you disable the toggle Run as SquaredUp DS app pool while the Default Run As still uses the SquaredUp DS app pool (toggle on), the credentials in the Default Run As will be empty and any PowerShell tiles using the Default Run As will show an error. You need to go into the Default Run As and enter the credentials you want to use to fix this issue.- From the top right hand menu ☰ click system.
- Go to the PowerShell tab.
You see the Default Run As. If you haven't changed the Default Run As account yet, you see a yellow icon indicating that the Run As uses the not recommended default setting "run as SquaredUp DS app pool". - Click on the Default Run As to edit it.
As long as the Run as SquaredUp DS app pool toggle is on, the Default Run As is read only. - Switch the Run as SquaredUp DS app pool toggle to off.
- Change the description to indicate that the Default Run As no longer uses the SquaredUp DS app pool.
- Enter the user credentials you want to use for the Default Run As.
Do not use your own or anyone's personal user account for Run As accounts. Instead, create a new account that is not used by a specific person (a "service account"), but only used for running PowerShell scripts. Consider the permissions of this service account carefully.
Required permissions for service accounts:
The service account you use for Run As must have at least the following permission:
- Allow log on locally
If you don't use the default NetworkService as your application pool identity, you might see the following error message when using Run As accounts: A required privilege is not held by the client.
In this case you need to add the application pool identity to the following policies:
- Adjust memory quotas for a process
- Replace a process-level token (you need to reboot the server for this policy to take effect)
The user credentials you enter for the Run As account are used to run all PowerShell scripts in tiles that use the Run As account. Once created, your Run As account can be used by other SquaredUp DS administrators to run their scripts. By using your or any user's credentials, you lose control over which scripts are executed in the name of this user which can cause privacy issues. In addition to that, users often have more rights than a script would need. By using a user account with extensive permissions, scripts that use the Run As can exploit those permissions.
- Click save to save the changes.
The Default Run As profile now uses the user account you entered when executing scripts.
On the SquaredUp server, run Notepad as administrator (Start, Run, type notepad
, and then right-click and select Run as administrator).
In Notepad, open the security.json
file from the SquaredUp DS folder:
...\User\Configuration\security.json
If the file doesn't exist, create it by following these steps and saving the file as security.json
at the end.
Name of the SquaredUp folder
The default name of the SquaredUp folder is SquaredUp
for v6 and above.
For v5 it is SquaredUpv5
.
Location of the SquaredUp folder
If you deployed SquaredUp DS via the Azure or AWS Marketplace:
The default location for the SquaredUp folder is F:\
.SquaredUpv[Version Number]
For v5 it is F:\SquaredUpv5
.
If you installed SquaredUp DS using the installer:
A custom location may have been chosen during the installation.
The default location for the SquaredUp folder is C:\inetpub\wwwroot\SquaredUp
For v5 it is C:\inetpub\wwwroot\SquaredUpv5
.
Edit the JSON file to contain the following property:{ "enable-powershell-run-as-app-pool": false }
If the file already contains settings, then you will need to add a comma at the end of the previous line.- Save the JSON file.
- Recycle the SquaredUp DS application pool.
The toggle Run as SquaredUp DS app pool is now disabled and hidden. It is not possible to (re)set the Default Run As to use the SquaredUp DS app pool anymore.
4) Consider creating different service accounts for running different scripts, depending on what their purpose is and what permissions they need. Save each service account as a different Run As account in SquaredUp DS.
When do you need to re-enter Run As accounts?
Encrypted information like providers, PowerShell profiles, and Run As accounts can get lost under certain circumstances:
When you are running SquaredUp DS without High Availability (HA):
When you change SquaredUp DS's application pool identity
When you are running SquaredUp DS with High Availability (HA):
When you change the license key you are using.
Make sure that you are able to recreate the information after you changed the app pool identity or your license key, for example by storing them temporarily in a safe place.
How to disable the PowerShell feature
By default, the PowerShell feature is available, but SquaredUp DS administrators can globally disable it. When the feature is disabled, any existing PowerShell tiles will still be visible to users as before but the scripts won't be executed anymore. Instead, PowerShell tiles will display the error message "PowerShell functionality is disabled". Administrators will still be able to create and edit PowerShell tiles, profiles and Run As accounts.
On the SquaredUp server, run Notepad as administrator (Start, Run, type notepad
, and then right-click and select Run as administrator).
In Notepad, open the security.json
file from the SquaredUp DS folder:
...\User\Configuration\security.json
If the file doesn't exist, create it by following these steps and saving the file as security.json
at the end.
Name of the SquaredUp folder
The default name of the SquaredUp folder is SquaredUp
for v6 and above.
For v5 it is SquaredUpv5
.
Location of the SquaredUp folder
If you deployed SquaredUp DS via the Azure or AWS Marketplace:
The default location for the SquaredUp folder is F:\
.SquaredUpv[Version Number]
For v5 it is F:\SquaredUpv5
.
If you installed SquaredUp DS using the installer:
A custom location may have been chosen during the installation.
The default location for the SquaredUp folder is C:\inetpub\wwwroot\SquaredUp
For v5 it is C:\inetpub\wwwroot\SquaredUpv5
.
Edit the JSON file to contain the following property:{ "enable-powershell-execution": false }
If the file already contains settings, then you will need to add a comma at the end of the previous line.- Save the JSON file.
- Recycle the SquaredUp DS application pool.
The PowerShell feature is now disabled. Scripts in existing PowerShell tiles won't be executed anymore.
Tips for your PowerShell scripts
You can make your PowerShell scripts responsive to the current page timeframe setting:
You can use the clock insert time value button to insert page timeframe and date variables in your query.
As the timeframe values are strings, you need to convert the $timeFrame
variable into a TimeSpan
object:
$timeSpan = [TimeSpan]::MaxValue
switch ($timeFrame) {
"last1Hour" { $timeSpan = [TimeSpan]::FromHours(1) }
"last12Hours" { $timeSpan = [TimeSpan]::FromHours(12) }
"last24Hours" { $timeSpan = [TimeSpan]::FromHours(24) }
"last7Days" { $timeSpan = [TimeSpan]::FromDays(7) }
"last30Days" { $timeSpan = [TimeSpan]::FromDays(30) }
"last3Months" { $now = [DateTime]::Now; $timeSpan = $now - $now.AddMonths(-3) }
"last6Months" { $now = [DateTime]::Now; $timeSpan = $now - $now.AddMonths(-6) }
"last12Months" { $now = [DateTime]::Now; $timeSpan = $now - $now.AddYears(-1) }
}
"TimeSpan is {0}" -f $timeSpan
The above script returns a TimeSpan
object calculated from the $timeFrame
variable as the following:
Troubleshooting
You can control when the script will run into a timeout. By default, scripts will be aborted after 1 min. You can define a longer timeout for long running scripts.
Best practice:
Even if you can use long running scripts by setting the timeout to several minutes, you shouldn't use scripts that run for a long time. Long running scripts lead to tiles that show a loading spinner for minutes and are not user-friendly.
Tip:
Instead of setting the timeout for scripts to a longer time, run the script outside of SquaredUp DS periodically, and store the results in a CSV file. Create a PowerShell tile that accesses and visualizes the results in the CSV file.
You can increase the timeout for your script in the Environment panel of a tile (jump to the settings for the Environment: panel).
When writing your PowerShell script, make sure that the output of your commands goes to the output stream and not other streams like host or debug. PowerShell tiles only process data sent to the output stream.
If the results don't change when you reload the dashboard, the interval for the tile is probably set to a longer time and you are looking at the cached results during the interval time.
The interval enables you to limit how often a script gets executed in SquaredUp DS. For example, you might want to run a script less frequently if it makes a request to an API that charges you per request or an API that puts a limit on how many requests you can make within a time period.
How does the interval affect how often PowerShell scripts are run in SquaredUp DS?
By default, a PowerShell script will be executed every time the dashboard refreshes (every minute). If you set the interval to 10 mins, you create a 10 min cache for your script results and your script won't run until the last fetched results are 10 mins old.
The interval is not a schedule, it does not trigger a script execution every 10 mins. Scripts will only be executed when the dashboard is reloaded and the results in the cache are older than the interval (10 mins in this example). The cache is valid for all users, which means if another user opens the same dashboard in SquaredUp DS or via Open Access and the script has been executed 5 mins ago, they see the cached results immediately but have to wait for 5 mins to see fresh results.
Can multiple tiles share the same cache?
Identical tiles share the same cache. For tiles to be considered identical, the JSON code of both tiles needs to be identical. If you want to use identical tiles to reduce the load on the back-end, you can copy the JSON from one tile and paste it into a different tile.
The shared cache works across your whole SquaredUp DS instance on:
- All dashboards (including Open Access dashboards), as long as they use the same page timeframe
- Perspectives for the same object on the same drill-down using the same page timeframe
If you are using HA, make sure .NET Core is installed on all HA machines. If you configured a tile to use the NET core option and try to view the tile on a HA machine that doesn't have .NET Core installed, the tile will display the error message "PowerShell host process returned errors: A fatal error occurred. The required library hostfxr.dll could not be found."
If you don't use the default NetworkService as your application pool identity, you might see the following error message when using Run As accounts: A required privilege is not held by the client.
In this case you need to add the application pool identity to the following policies:
- Adjust memory quotas for a process
- Replace a process-level token (you need to reboot the server for this policy to take effect)