Migrating content from v2 to v3

Summary

The Squared Up Migration Tool is a PowerShell script requiring version 3.0.0+ of PowerShell to run. It converts v2 content from XML files to JSON files for use in v3 of Squared Up.

Please ensure you are using the latest version of Squared Up before using the Migration Tool.

Description

The Squared Up Migration Tool will run a series of translations on v2 dashboards and navigation bar items, converting them from XML files to JSON files which are supported within v3. When the script runs, it will display a number of default options such as file paths and will provide prompts to allow you to specify alternatives. These options can also be changed before execution by passing parameters to the script. The accepted parameters are listed below. If you have enabled high availability (HA) on your v3 instance, please ensure that you enter your network share path as the target using either a script parameter or when prompted during execution.

By default the script will run through all published v2 dashboards and navigation items converting each item into the v3 JSON format overwriting existing v3 profiles. Backups of existing v3 navigation bar profiles will be created within SquaredUpv3\User\Profiles called ProfileName-Backup.json.

After running the tool you will need to force a reload of all dashboard packs on your v3 instance. This can be achieved using the last step in the procedure section below.

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

Procedure

  1. On your Squared Up v3 server download the Migration Tool. Extract the contents to a sensible location (e.g. C:\Scripts or the desktop).

  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 or cd ~\desktop

  4. Run the script by typing: .\MigrationTool.ps1

  5. Press Enter (or a or r when using the Operations Manager Shell) to run the script.

    Migration Tool sample start of script <>

    The script will by default assume your v2 directory is located in C:\inetpub\wwwroot\SquaredUpv2 and your v3 directory is located in C:\inetpub\wwwroot\SquaredUpv3

  6. Type N to use the default v2 path or Y to specify the path to your v2 directory i.e. \\1.0.0.24\c$\inetpub\wwwroot\squaredupv2

    As this instance exists on a different machine, the user will be prompted for their domain\username and password

    Migration Tool Entering v2 directory <>

  7. Type N to use the default v3 path C:\inetpub\wwwroot\squaredupv3 or Y to specify the path to your v3 directory.

    Migration Tool Entering v3 directory <>

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

    Completion of Migration Tool <>

  9. Once the Migration Tool has finished open Squared Up and go to the right-hand menu ☰ then system and then the dashboard packs perspective. 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.

Parameters

V2Directory [Path]

Changes where the script will gather migration data from, this needs to be pointed at a v2 instance’s directory, by default the v2 instance is assumed to be located at C:\inetpub\wwwroot\SquaredUpv2.

Example: .\MigrationTool.ps1 -V2Directory "\\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 user will be prompted to input the path to their v3 instance which will default to C:\inetpub\wwroot\SquaredUpv3 if unspecified.

V3Directory [Path]

Changes where the script will output the converted dashboards (This needs to be a 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 -V3Directory "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 -V3Directory "\\server\share\v3"

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

OutputFolder [Path]

Instead of outputting the converted dashboards straight into v3 instance, you can specify an alternative location where dashboard files should be created. To place the output into your v3 installation copy the folder User from inside the created SquaredUpV3Migrated folder into your 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]

Toggle whether to skip migration of your v2 navigation bars, if script is passed $True 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 (if enabled).

More menu with migrated dashboards

FullLog [Switch]

Toggles whether to show all log messages in the console. If script is passed FullLog this will be displayed in the console. By Default FullLog is set to False.

Example: .\MigrationTool.ps1 -FullLog

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

Full log output

FullPrompt [Switch]

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

Example: .\MigrationTool.ps1 -FullPrompt 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.

Image of example prompt?

PipedPath [Path]

Will pipe in a single quoted path to convert all XML dashboard files contained within the path into v3 JSON files i.e. "C:\Documents\V2Dashboards" | MigrationTool.ps1

Note: If the dashboard contains a Visio or Image section the file can’t be transferred using piping and will need to be added through the tile editor in v3.

Example: "C:\Documents\V2Dashboards" |.\MigrationTool.ps1

Explanation: This will convert each v2 XML dashboard within the V2Dashboards folder that is a XML file and create v3 JSON files in the same folder the script was run from.

Example: ".\domain.user-20160810093749.Xml" | .\MigrationTool.ps1

Explanation: This will convert the v2 dashboard with filename domain.user-20160810093749.Xml in the current path of the script and output the converted JSON file into the same directory.

Example: ".\domain.user-20160810093749.Xml" | .\MigrationTool.ps1 -V3Directory "C:\inetpub\wwwroot\squaredupv3"

Explanation: This will do the same as the example above except this will output the converted JSON file into a dashboard pack called MigratedDashboards in the Squared Up v3 instance which can then be accessed via the more menu in Squared Up.

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.

LogTileSettings [String]

Changing the amount of logging detail added to dashboards about the migration process. The log tile is added to the bottom of your dashboard when any issues occur during migration as shown below.

Example log tile on v3 dashboard

“Disable” If passed disable will not create a log tile when errors are thrown or settings are lost in conversion. “Errors” If passed errors will only display errors that are thrown during dashboard conversion.

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

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

FAQ

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.

Where do I place the created files and folders if I didn’t specify a v3 installation directory?

  • If you used the OutputFolder parameter, you can merge the User folder created inside the output SquaredUpV3Migrated folder with your User folder of your v3 instance which by default is located at C:\inetpub\wwwroot\squaredupv3\User This will be your share path if you have HA enabled

  • If you piped in a v2 dashboard folder you can copy the created JSON files into the Everyone package which by default is located at C:\inetpub\wwwroot\squaredupv3\user\packages\everyone \dashboards for dashboards and \perspectives for perspectives This will be your share path if you have HA enabled

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

Once the Migration Tool has finished open Squared Up and go to the right-hand menu ☰ then system, and then view the dashboard packs perspective. Scroll down and at the bottom of the page click the reload button to force a reload of all dashboard packs. This will make the dashboards and navigation items appear in Squared Up.

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.log 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: Migrating content from v2 to v3 keywords: Migrating content from v2 to v3