How to migrate content from Squared Up v2 to v3

Summary

The Squared Up Migration Tool is a PowerShell script which converts Squared Up v2 dashboards and navigation bar items from Squared Up v2 XML files to JSON files for use in Squared Up v3.

Prerequisites

  • Ensure that your Squared Up v3 instance is using the latest version.

  • Your Squared Up v2 instance can be running any version of Squared Up v2.

  • The Migration Tool requires PowerShell version 3.0.0+

Description

You can specify parameters when running the script, for example the location of the v2 content, or use the -Confirm parameter to be prompted for the information as you go.

Dashboards migrated into Squared Up v3 will be placed in a custom dashboard pack so will not overwrite any dashboards you may have already created in v3.

Backups of existing v3 navigation bar profiles will be created within SquaredUpv3\User\Profiles called ProfileName-Backup.bak.

After running the tool you will need to force a reload of all dashboard packs on your v3 instance, as described below.

To see the Migration Tool in action take a look at the webinar ‘Squared Up v2 to v3 Migration’:

Below you will see walkthroughs for several common scenarios:

  • Migrating content in bulk from Squared Up v2 straight into v3.

  • Migrating individual files from v2 XML format to v3 JSON format. This might be an individual file from your Squared Up v2 instance, or perhaps a dashboard from the v2 Community Dashboards site.

  • Migrating content when you have enabled high availability (HA) on your v3 instance.

Walkthrough: Migrating content in bulk from Squared Up v2 to v3

  1. On your Squared Up v3 server download the Migration Tool. Extract the contents to a sensible location, for example C:\scripts

  2. Open Windows PowerShell as an administrator (Start Menu > Windows PowerShell, then right-click and select Run As Administrator).

  3. Change location into the directory where you extracted the script, for example cd C:\scripts

  4. To run the Migration Tool type the following and press enter:

    .\MigrationTool.ps1 -Confirm

  5. The default location for the new v3 files to be output to is C:\inetpub\wwwroot\squaredupv3. If your v3 instance is in a different location or you would like to output the migrated content to a different location type Y, press enter and then type the path you require.

  6. The Migration Tool will assume your v2 directory is located in C:\inetpub\wwwroot\SquaredUpv2 on the same server. If this is not the case type Y, press enter and then type the path of your v2 directory.

    For example, if your v2 instance is on another server your can specify a UNC path such as \\10.0.0.24\c$\inetpub\wwwroot\squaredupv2

    When either instance is on a different machine you will be prompted for your domain\username and password to connect to that machine.
  7. You will be prompted to migrate each file, and any supporting files, or you can press A to migrate all without further prompts.

    Migrating from v2 to v3

  8. The Migration Tool will then run a series of translations from the specified v2 directory into the v3 directory.

    Migration Output

  9. Once the Migration Tool has finished, open Squared Up v3 and go to the right-hand menu ☰ > system > dashboard packs. Click the reload button at the bottom of the page to force a reload of all dashboard packs. This will make the dashboards and navigation items appear in Squared Up.

    Reload

If you can’t find the v3 dashboards in Squared Up v3 see I’ve run the migration tool but my dashboards haven’t appeared?

Walkthrough: Migrating individual files into Squared Up v3

You may wish to convert only one or two files from v2 XML format to v3 JSON format. This might be an individual file from your Squared Up v2 instance, or perhaps a dashboard you have downloaded from the v2 Community Dashboards site.

  1. On your Squared Up v3 server download the Migration Tool. Extract the contents to a sensible location, for example C:\scripts.

  2. Copy the files you want to convert into a separate folder, for example c:\v2files

    • If you have downloaded a .ZIP file from the v2 Community Dashboards site, you should copy the view.xml file out of the ZIP file into the folder you created. The manifest.xml file is not required.

    • If you want to migrate one or more dashboards from your v2 instance copy them from the v2 Views folder which by default is located at C:\inetpub\wwwroot\squaredupv2\Configuration\Views into the folder you created.

  3. Open Windows PowerShell as an administrator (Start Menu > Windows PowerShell, then right-click and select Run As Administrator).

  4. Change location into the directory where you extracted the script, for example cd C:\scripts

  5. To run the Migration Tool type the following and press enter:

    .\MigrationTool.ps1 -Source "c:\v2files" -OutputFolder "C:\inetpub\wwwroot\squaredupv3"

    where c:\v2files is the folder where you placed your v2 XML file(s).

    and where C:\inetpub\wwwroot\squaredupv3 is the location of your v3 instance or HA share.

    If you have run the Migration Tool previously on this v3 instance you may see the message Migration has already been performed, and may like to type N to not remove any previously migrated files.
  6. The Migration Tool will then run a series of translations from the specified v2 directory to your Squared Up v3 instance.

  7. Once the Migration Tool has finished, open Squared Up v3 and go to the right-hand menu ☰ > system > dashboard packs. Click the reload button at the bottom of the page to force a reload of all dashboard packs. This will make the dashboards and navigation items appear in Squared Up.

If you choose to output the v3 files to a folder rather than a v3 instance, see I converted v2 files and placed them in a folder, how do I get them into Squared Up? for how to add theses files to a v3 instance

If you can’t find the v3 dashboards in Squared Up v3 see I’ve run the migration tool but my dashboards haven’t appeared?

Walkthrough: Migrating content when using high availability on v3

  1. On your Squared Up v3 server download the Migration Tool. Extract the contents to a sensible location, for example C:\scripts

  2. Open Windows PowerShell as an administrator (Start Menu > Windows PowerShell, then right-click and select Run As Administrator).

  3. Change location into the directory where you extracted the script, for example cd C:\scripts

  4. To run the Migration Tool type the following and press enter:

    .\MigrationTool.ps1 -Source "\\server\share\v2" -OutputFolder "\\server\share\v3"

    where \\server\share\v2 is the path your v2 HA share, where the Configuration and UserProfiles folders are located.

    and where \\server\share\v3 is the path your v3 HA share, where the Configuration and UserProfiles folders reside.

    For example:

    .\MigrationTool.ps1 -Source "\\10.0.0.24\share\squaredupv2HA" -OutputFolder "\\10.0.0.23\share\squaredupv3HA"

    When the location is on a different machine you will be prompted for your domain\username and password to connect to that machine.

    Credential Request

  5. The Migration Tool will then run a series of translations from the specified v2 directory into the v3 directory.

  6. Once the Migration Tool has finished, open Squared Up v3 and go to the right-hand menu ☰ > system > dashboard packs. Click the reload button at the bottom of the page to force a reload of all dashboard packs. This will make the dashboards and navigation items appear in Squared Up.

If you can’t find the v3 dashboards in Squared Up v3 see I’ve run the migration tool but my dashboards haven’t appeared?

FAQs

I’ve run the migration tool but my dashboards haven’t appeared?

  1. In Squared Up v3 go to the right-hand menu ☰ > system > dashboard packs > reload at the bottom of the dashboard packs perspective.

  2. In the Custom dashboard packs section of the dashboard packs perspective look for a pack called A user-migrated pack (v2Dashboards-Migrated). Click on this pack to expand it, and check if any dashboards are listed as invalid, then see A dashboard or perspective is missing and listed as invalid.

  3. Check the More menu. Dashboards may appear on the More menu if they are migrated individually, or if the user does not have visibility of the navigation bar they are on. SCOM Administrators can see the More menu by default, but other users may not (see Visibility of the More menu) so you should add the new dashboard to the navigation bar from ☰ > system > profiles, or set it as a perspective to make it available.

I converted v2 files and placed them in a folder, how do I get them into Squared Up?

If you migrated v2 content and chose to place it into a folder rather than straight into your v3 instance, you will need to copy the migrated files into the Squared Up v3 directory.

  1. You need to merge the User folder created in the output folder SquaredUpV3Migrated with the User folder on your v3 instance. To do this, copy the User folder (inside SquaredUpV3Migrated) and paste it into the root of your Squared Up v3 instance, which by default is located at C:\inetpub\wwwroot\squaredupv3. If you are using high availability (HA) this will be your HA share path.

    For any subsequent migrations you will receive a message when pasting the User folder: The destination already has a file named “pack.json. You should click on Replace the file in the destination, as it is fine to overwrite the pack.json file.

  2. Open Squared Up v3 and go to the right-hand menu ☰ > system > dashboard packs. Click the reload button at the bottom of the page to force a reload of all dashboard packs.

  3. When dashboards are migrated individually they may appear on the More menu. SCOM Administrators can see the More menu by default, but other users may not (see Visibility of the More menu) so you should add the new dashboard to the navigation bar from ☰ > system > profiles, or set it as a perspective to make it available.

Can I run the Migration Tool multiple times against an instance of v3?

The Migration Tool can be run as many times as you like against an instance of v3, each subsequent time you specify to directly migrate to a v3 instance you will be given the option to clean up all previously migrated content.

Subsequent migrations prompt

If you select ‘Yes’ then any previously migrated navigation items, dashboards and perspectives will be removed. Any content created within v3 will be preserved.

Reference: Migration Tool Parameters

Source [Path]

Changes where the script will gather migration data from, by default the v2 instance is assumed to be located at C:\inetpub\wwwroot\SquaredUpv2.

Example: .\MigrationTool.ps1 -Source "\\1.0.0.24\c$\inetpub\wwwroot\squaredupv2"

Explanation: This will migrate all v2 dashboards and user profiles that can be found at the path \\1.0.0.24\c$\inetpub\wwwroot\squaredupv2. The migrated files will be saved to the default v3 location C:\inetpub\wwroot\SquaredUpv3 as OutputFolder was unspecified.

The path can be a folder (in which case all sub-folders are recursively checked for dashboards), a file (only that specific dashboard is converted), or an array of either (all listed folders/files are converted).

OutputFolder [Path]

Changes where the script will output the converted dashboards. If importing directly into Squared Up this needs to be the v3 application root directory. By default this will output to C:\inetpub\wwwroot\SquaredUpv3. If you are using HA you will need to specify your share path.

Example: .\MigrationTool.ps1 -OutputFolder "D:\inetpub\wwwroot\squaredupv3"

Explanation: This will migrate all v2 dashboards and user profiles to an instance of Squared Up v3 running off the path D:\inetpub\wwwroot\squaredupv3.

For example to specify a HA share: .\MigrationTool.ps1 -OutputFolder "\\server\share\v3"

Explanation: This will migrate all v2 dashboards and user profiles to a HA share located at the path \\server\share\v3.

Instead of outputting the converted dashboards straight into a v3 instance, you can specify an alternative location where dashboard files should be created. To then place the output into the v3 installation copy the sub-folder User from inside the created SquaredUpV3Migrated folder into the v3 instances directory (i.e. C:\inetpub\wwwroot\squaredupv3) and merge it with the existing User folder.

Example: .\MigrationTool.ps1 -OutputFolder "C:\Users\Anon\Documents"

Explanation: This will migrate the converted dashboards to a folder named SquaredUpV3Migrated at the path C:\Users\Anon\Documents. The contained User folder can then be merged with an existing User folder of a v3 instance.

SkipNavigationBars [Switch]

Toggles whether to skip migration of your v2 navigation bars, if enabled it will not migrate any v2 navigation bars over to v3. By default SkipNavigationBars is set to false.

Example: .\MigrationTool.ps1 -SkipNavigationBars

Explanation: This will skip migrating any navigation bar settings and user profiles from v2, causing all migrated dashboards to be shown under the More menu (SCOM Administrators can see the More menu by default, but other users may not (see Visibility of the More menu)).

More menu with migrated dashboards

OverwriteV3Profiles [Switch]

Toggles whether to overwrite existing v3 navigation bars. If enabled it will overwrite any v2 profiles that exist in v3 (typically from a previous migration) losing any navigation bar links that exist on that profile.

Example: .\MigrationTool.ps1 -OverwriteV3Profiles

Verbose [Switch]

Toggles whether to show all log messages in the console. If enabled this will be displayed in the console. By default Verbose is set to False.

Example: .\MigrationTool.ps1 -Verbose

Explanation: This will display detailed results on the conversion process of dashboard sections and navigation items.

Full log output

Confirm [Switch]

If enabled, the Migration Tool will prompt the user if they want to convert every dashboard that is found in the migration process.

Example: .\MigrationTool.ps1 -Confirm

Explanation: This will prompt the user for specific actions during the migration process, i.e. which dashboards and navigation items they want to migrate and whether eligible dashboards should be converted to perspectives.

ConvertToPerspectives [Switch]

Converts all eligible dashboards into v3 perspectives without prompting the user. More information on perspectives can be found here What Is A Perspective.

The following dashboards will be converted into perspectives:

  • Drilldown set -> Converts to a perspective that is shown when drilling down to the first object in drilldown list.

  • Single Object List Pagescope -> Converts to a perspective that is shown when drilling down to the object specified in the Pagescope.

  • Multiple Object List Pagescope -> Converts to a dashboard, each tile that inherited the page scope gets their scope set to the list of objects specified in the page scope.

  • Class & Group PageScope -> Converts to a dashboard, each tile that inherited the page scope gets scope set to page scope.

  • Class Pagescope -> Converts to a dashboard, each tile that inherited the page scope gets scope set to page scope.

  • Group Pagescope -> Converts to a perspective that is shown when drilling down to the group that was set in the page scope.

  • No pagescope or drilldown set -> Converts directly to a dashboard.

Example: .\MigrationTool.ps1 -ConvertToPerspectives

Explanation: This will migrate all dashboards and navigation and where eligible create v3 perspectives from dashboards.

CreateLogTile [Switch]

Toggle whether to create a log tile that displays errors that occur during the dashboard’s conversion in the dashboard itself.

Example log tile on v3 dashboard

Example: .\MigrationTool.ps1 -CreateLogTile "disable"

Explanation: Log tiles will be created on dashboards with settings that couldn’t be migrated.

Force [Switch]

If specified, will suppress all confirmation prompts and choices. This switch is ideal if the script is being run as part of an automated process, and should fail rather than prompting the user.

Example: .\MigrationTool.ps1 -Verbose -Force

Explanation: A migration will be run with all confirmation prompts automatically accepted, full output displayed, and an error thrown if any issues that require user input are encountered.

Whatif [Switch]

If specified, simulates the dashboard selection and migration process without actually creating/modifying any dashboards or profiles.

Example: .\MigrationTool.ps1 -Whatif

Issues with migrations

If you experience any issues with the Migration Tool please contact us at [email protected] with details of the error along with your MigrationLog.yyyyMMdd-hhmmss.log (which is located in your output folder and is date stamped) and Squared Up Diagnostics.

Webinar: Squared Up v2 to v3 Migration

Release notes

How to install Squared Up v3 for the first time

Getting Started Guide label: How to migrate content from Squared Up v2 to v3 keywords: Migrating content from v2 to v3 migrate xml to json dashboard pack convert converting script convert conversion