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 

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

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
 

Download the script directly to a working directory on your machine.

# 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 9 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 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.