Migrating content from v2 to v3
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.
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
To see the Migration Tool in action take a look at the webinar ‘Squared Up v2 to v3 Migration’:
On your Squared Up v3 server download the Migration Tool. Extract the contents to a sensible location (e.g. C:\Scripts or the desktop).
Open Windows PowerShell as an administrator (Start Menu > Windows PowerShell, then right click and select Run As Administrator).
Change location into the directory where you extracted the script, for example:
Run the script by typing:
Press Enter (or
rwhen using the Operations Manager Shell) to run the script.
The script will by default assume your v2 directory is located in
C:\inetpub\wwwroot\SquaredUpv2and your v3 directory is located in
Nto use the default v2 path or
Yto specify the path to your v2 directory i.e.
As this instance exists on a different machine, the user will be prompted for their domain\username and password
Nto use the default v3 path
Yto specify the path to your v3 directory.
The Migration Tool will then run a series of translations from the specified v2 directory into the v3 directory.
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.
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
.\MigrationTool.ps1 -V2Directory "\\188.8.131.52\c$\inetpub\wwwroot\squaredupv2"
Explanation: This will migrate all v2 dashboards and user profiles that can be found at the path
\\184.108.40.206\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.
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.
.\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
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
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
.\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.
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.
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).
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.
Explanation: This will display detailed results on the conversion process of dashboard sections and navigation items.
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.
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.
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.
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.
".\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.
".\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.
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.
Explanation: This will migrate all dashboards and navigation and where eligible create v3 perspectives from dashboards.
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.
“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.
.\MigrationTool.ps1 -LogTileSettings "disable"
Explanation: No log tiles will be created on dashboards with settings that couldn’t be migrated.
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.
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
OutputFolderparameter, you can merge the
Userfolder created inside the output
SquaredUpV3Migratedfolder with your
Userfolder of your v3 instance which by default is located at
C:\inetpub\wwwroot\squaredupv3\UserThis 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
Everyonepackage which by default is located at
\dashboardsfor dashboards and
\perspectivesfor 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
Getting Started Guide