Importing/Exporting Modern Dashboards

I think I posted this somewhere else, but I wanted to put it here so that it's easily accessible to all those interested in the Orion API and SDK Discussions.

Preamble

TL;DR: Take me directly code and steps 

Important: Read the Some Final Notes area for details about the format of the JSON files.

A while ago some of the super-intelligent people in the SolarWinds technical advisory team told me about a page they came across in our recent documentation to ask if I had seen it.  At the time, I had not, but afterwards, I was struck by the implications.  I won't belabor the details of the page as you can read it yourself, but I want to say what I did with that information.

Long story short, SolarWinds realized that Modern Dashboards are pretty [EXPLETIVE DELETED] cool.  Some people knew that already, but they are complex. I don't mean that they are difficult to consume when completed as   discussed in his excellent series of posts about getting started with Modern Dashboards.  What I mean is that the Modern Dashboards are not raw data, and as such, the presentation of said data can get complex.  There are multiple types of widgets, each has multiple settings to define how it's presented, and each of the fields presented can have additional settings (including colors, icons, thresholds, and more).

This means if I want to share a Modern Dashboard that I built, I'll be sending people dozens of screenshots to encapsulate all the settings that are configured.  This is (in no uncertain terms) extremely painful.  So the smart people who work on the SolarWinds development and architecture teams wanted to make it easier to share this information.  That's why the Import/Export of Modern Dashboards functionality was built.

Doing the work in SWQL Studio

If you are already familiar with SWQL Studio, then the functionality is right there for you.  Just navigate down to the Orion.Dashboards.Instances entity and expand it, right-click on the Export or Import verb and select Invoke.  The rest of the details on Importing/Exporting this way via SWQL Studio are in the aforementioned documentation article.

The raw format of Modern Dashboards isn't anything new.  Everything is stored in a JSON formatted string.  I've seen the joke that JSON is just hipster XML - and while I don't disagree, I will concede that JSON works better for extremely large datasets.  Both XML and JSON are both great for representing data structures because they have parent-child relationships, can handle all types of data serialization, support arrays, and a bunch of other things.  This is why most exports (not all) from the Orion Platform products use one or the other as the underlying architecture.

I thought we might have have missed a specific scenario though - what about the person who has a Orion staging (or test/dev) environment and an Orion production environment?  They build everything in staging and then recreate it (after approval).  This is the way I did things for years as a customer.  When new things came out, I'd run an evaluation version in a segregated lab, add in a few lab devices and see how it would affect my experience and interaction with the products.  Then I could plan my upgrades accordingly.

Moving to PowerShell

Heart PowerShell and anyone who has known me for any amount of time knows this about me.  Since both Import and Export are simple verbs and take basic parameters, it was an idea candidate for me to put it into a PowerShell function.

I won't bore you with all of the steps I used while developing this function, but I did try to cover what I felt were the most important features that would be required for most scenarios.  If you want specifics, you can always ask here, but if there's some functionality I'm missing, let me know.

The Simple Step-by-Step Process

My functions require PowerShell version 7 or later and the SolarWinds Information Service Module version 3 or later.  Reasons are explained below.

Get PowerShell 7

First things first, you'll need a newer version of PowerShell.  The script I wrote does not support anything before PowerShell 7.0.  This was intentional because the JSON functions native to PowerShell were significantly improved in that version.  If you don't have it, you can download it from the Microsoft GitHub releases pages or (on Windows) install it directly from the Microsoft Store.  the same is available for macOS and Linux (using different installation methods of course).

You only have to do this once per machine.

Get the latest SolarWinds Information Service PowerShell Module

Once installed on your computer launch PowerShell 7 and from that prompt, install the SolarWinds Information Service Module from the PS Gallery.  You may be prompted to trust PSGallery if you've not installed modules from there before.

You only need to do this once per machine.

# Install the SolarWinds Information Service PowerShell Module
Install-Module -Name SwisPowerShell

Import the SwisPowerShell Module

# Import the SwisPowerShell Module (not always required)
Import-Module -Name SwisPowerShell

Connect to your SolarWinds Orion server

# Swap for your own hostname, username, and password
$SwisConnection = Connect-Swis -Hostname "myOrionServer.domain.local" -UserName "myUsername" -Password "myComplexPassword"
# there are other authentication methods available, but this is the most basic

Validate you are Connected by running a Simple Query

# Simple query using our previously build connection
Get-SwisData -SwisConnection $SwisConnection -Query "SELECT TOP 10 Caption, IPAddress, ObjectSubType FROM Orion.Nodes"
# You should get a list of 10 nodes.

Download the script directly to a working directory on your machine

The function is up in the Orion SDK GitHub.  Download it however you like as long as you can call it in the next step.

# Download the current 'func_ModernDashboards.ps1' to your local computer.
Start-BitsTransfer -Source "https://raw.githubusercontent.com/solarwinds/OrionSDK/master/Samples/PowerShell/functions/func_ModernDashboards.ps1" -Destination ".\func_ModernDashboards.ps1"

Run the script to load the functions

# Execute the downloaded script to load the functions into memory
. .\func_ModernDashboards.ps1

# Validate the functions are loaded
Get-Command -Noun "ModernDashboard"

# You should see two functions listed.

Export a Modern Dashboard

# Export the modern dashboard with ID #10
Export-ModernDashboard -SwisConnection $SwisConnection -DashboardId 10

# This will export a modern dashboard with the ID number of 10 to a JSON file in the current location

Import a Modern Dashboard

# Import a Modern Dashboard from a JSON file
Import-ModernDashboard -SwisConnection $SwisConnection -Path C:\Path\To\Dashboard.json

Additional Function Options

# Show me some examples for exporting
Get-Help -Name Export-ModernDashboard -Examples

# Show me some examples for importing
Get-Help -Name Import-ModernDashboard -Examples

That's pretty much it for now.  I plan on continuing to contribute new functions to the Orion SDK library on GitHub, so keep an eye on that space and we'll continue to grow and learn together.

Some Final Notes

Importing/Exporting with SWQL Studio

  • Importing the Modern Dashboard JSON using the SWQL Studio method (as described in the support documentation) requires the JSON to be 'linearized' (all the content on one line). This can be done in a number of ways, but most people use a plain text editor which has this as a native feature or via a plugin.
  • When exporting Modern Dashboards to a JSON file, it is also exported without any line breaks.  This is good for size, but makes it incredibly difficult to interpret if you want to review the body of the dashboard and the definitions of the various objects.

Importing/Exporting with the PowerShell function

  • When you export a Modern Dashboard via the PowerShell function, the file is exported in a "pretty" format (with line breaks and sections indented).  The native "knowledge" of JSON formatting within PowerShell is leveraged and this is the default for exporting.  This can be overridden by passing the -Compress parameter which removes the extra characters.
  • The PowerShell function can import either 'linearized' or 'pretty' JSON definitions for Modern Dashboards without any need to touch the files themselves.
Parents Reply Children