How to migrate from SquaredUp for SCOM v3 to v4
This article describes how to migrate from SquaredUp v3 to v4. We recommend you read through this article before starting the migration, to familiarise yourself with the migration process and the changes between versions.
Why migrate to the latest version of SquaredUp?
The latest version of SquaredUp is v5. If you already using SquaredUp v4 and are looking to upgrade to v5 see How to migrate from SquaredUp for SCOM v4 to v5.
If you are currently using SquaredUp v3 you should upgrade to v4 first, before upgrading to v5. This is because there are significant changes between v3 and v4 which are migrated as part of the v3 to v4 upgrade process.
SquaredUp v3 will reach end-of-life on 31st March 2021. To benefit from the many new features in v4 and v5 please get in contact with SquaredUp Support so we can discuss your options and undertake a migration strategy that best suits your needs.
New features in v4
SquaredUp v4 is a major new release that brings significant updates to the dashboarding fundamentals, as well as introducing a brand new Enterprise Application model to SCOM. Upgrading to SquaredUp v4 will firstly enable you to deliver a greater array of dashboards to an even wider audience, and secondly deliver a true enterprise application monitoring solution for your organisation.
- Dark theme - users can now choose to run SquaredUp in light or dark mode (see Theme Personalisation).
- Line graph and donut visualisations for the Log Analytics tile (see How to use the Azure Log Analytics tile)
- New Performance Report tile allows you to add 'layers' to the same graph, for example to show different metrics on the same chart, or compare metrics over a different time period such as last week or last month (see How to use the Performance tile).
- New ServiceNow tile which introduces a new ServiceNow provider that is much simpler to configure than the generic Web API oauth provider (see How to use the ServiceNow tile).
- Pinning Perspectives to the navigation bar allows you to make them available via Open Access (see Pinned Perspectives).
- New navigation structure offers a more intuitive navigation and authoring experience (see How to edit the Navigation Bar).
- New Matrix tile which supersedes the Dynamic Table tile to bring fully-customisable, data-rich grids to your dashboards (see How to use the Matrix tile).
- Team Folders replace user profiles to enable you to deliver dashboards and delegate control to different teams within your organisation (see Team Folders).
- The new Enterprise Application (EA) Designer enables you to model your applications and save directly to SCOM as a new Enterprise Application class, replacing traditional SCOM distributed applications (see Enterprise Applications).
- Manual availability reporting - allows you to manually change the health state of an Enterprise application from available to either degraded or unavailable, as well as enter your own message to users (see How to manually set the health state of an application).
- New high availability (HA) architecture - we have redesigned HA in SquaredUp v4 to make it simple to configure and support higher volumes of usage (see Enabling High Availability).
It is useful to have an overview of the changes to the navigation bar and permissions when planning the upgrade. The upgrade assessment tool may mention dashboards that need to be relocated after upgrading, or you may wish to configure the SquaredUp navigation structure and Team Folders before giving users permissions. Some tasks can only be carried out by SquaredUp administrators (i.e. SCOM admins).
- Using Team Folders users are given permissions to edit or create dashboards in a particular folder and need to navigate to the folder before they can click the + button to create a new dashboard (see Team Folders).
- Only SquaredUp admins can create/edit SQL, Web API, and Azure tiles (Application Insights and Log Analytics), see How to use the SQL tile, How to use the Web API tile, How to use the Azure Application Insights tile, How to use the Azure Log Analytics tile.
- Only SquaredUp admins can create/edit perspectives (see What is a perspective?).
- Only SquaredUp admins can manage the global navigation bar structure (see How to edit the Navigation Bar).
- Only SquaredUp admins can create/delete Team Folders.
- Administrative permissions cannot be delegated outside of SquaredUp admins (see How do SCOM roles and permissions affect what users can do in SquaredUp?)
The new navigation experience is more intuitive to use, it acts more like a file system, and some things have changed from v3:
- Each dashboard can only appear in one location on the navigation bar.
- A dashboard must be created in a particular location on the navigation bar (a more menu for homeless dashboards is no longer used).
- A dashboard cannot act like a folder on a navigation bar (i.e. cannot contain child dashboards).
- Dashboards cannot be in the root of a profile's navigation bar (except on the global navigation bar).
This configuration is covered in 6. Configure SquaredUp v4.
Planning the upgrade
Summary of the upgrade process
1. Before Upgrading - complete the upgrade prerequisites
3. Licensing - get a v4 licence from the switchover portal
You may also like to watch the v4 training webinar: Upgrading from v3 to v4 (42 mins).
There are a few key tasks you should complete before upgrading:
- Ensure you have v3.4.6 installed. Contact Support for the v3.4.6 download if needed.
- Check the SquaredUp server spec (see Server Spec and Sizing), you may need a small memory upgrade (about 1GB) when upgrading to v4.
- Replace any OMS tiles with Azure Log Analytics tiles so they continue to work with v4.
- Publish any draft dashboards and perspectives you want to keep. Ask other users with authoring rights do the same, because draft dashboards and perspectives are not migrated to the upgraded instance.
- Any v3 perspectives published with Open Access should be added to the navigation bar before upgrading. This will enable them to be automatically migrated to v4 both as pinned perspectives and Open Access. (see Pinned Perspectives and Open Access)
- Ensure no changes are made to your v3 instance. You might like to revoke all dashboard authoring privileges, and advise other administrators not to not to make any changes to v3, in particular dashboards, perspectives, profiles, web API providers, dashboard packs, publishing Open Access dashboards, or modifying named users.
- Consider user acceptance testing prior to upgrading, and user training after upgrading (jump to 7. User Training).
- Backup SquaredUp v3 - it is good practice to ensure you have a working backup before upgrading.
- Run the Upgrade Assessment Tool as described below (jump to 2. Run the v4 Upgrade Assessment Tool).
If you are using high availability see What do I need to consider when upgrading a high availability (HA) configuration?
Before starting the upgrade you should run the v4 Upgrade Assessment Tool to see if there are any issues to resolve before upgrading.
- On your SquaredUp server download the v4 Upgrade Assessment Tool.
- Open Windows Powershell for the location of
Upgrade.exe, for example in File Explorer browse to where you extracted
Upgrade.exethen File > Open Windows Powershell > Open Windows Powershell.
From Windows Powershell run the following using the location of your v3 instance:
.\upgrade.exe report --target="C:\inetpub\wwwroot\squaredupv3"
--targetargument refers to the installation location of your v3 instance
The report will show any issues that must be resolved manually after upgrade.
The Upgrade Assessment tool will report on any items that cannot be migrated automatically, and the table below shows how to deal with these.
Any dashboards placed in the Issues folder, because of navigation bar issues, can be moved to the correct
location after the upgrade.
|Draft dashboards and perspectives are not migrated||Before upgrading publish drafts|
|OMS tiles are not migrated||Before upgrading recreate OMS tiles as Azure Log Analytics tiles (How to use the Azure Log Analytics tile)|
|v3 perspectives published with Open Access should be added to the navigation bar so they are automatically migrated|
Before upgrading add v3 perspectives published with Open Access to the navigation bar. These will be automatically migrated to v4 both as pinned perspectives and Open Access (see Pinned Perspectives and Open Access).
|A dashboard cannot appear multiple times on the navigation bar||After upgrading move the dashboard from the Issues folder to the correct location (jump to Navigation bar migration).|
|A dashboard must appear in one location on the navigation bar||After upgrading move the dashboard from the Issues folder to the correct location. If the More menu is enabled on v3, all dashboards not in a profile will be added to a More folder (jump to Navigation bar migration).|
|A dashboard cannot act like a folder on a navigation bar (i.e. cannot contain child dashboards)||After upgrading review the folder structure created. A new folder will have been created with the parent and child dashboards within.|
|Dashboards cannot be in the root of a profile's navigation bar (except on the global navigation bar)||After upgrading move the dashboard from the Issues folder to the correct location (jump to Navigation bar migration).|
|Open Access pages will have different URLs||After upgrading update or redirect Open Access URLs (the report shows the old and new URLs) (jump to Update or redirect Open Access URLs).|
|The upgrade cannot migrate the Web API providers|
After upgrading recreate Web API providers (jump to Recreate Web API providers).
|The 4.0+ compatible version of Community Dashboard pack 'xxx' will need to be reimported manually after installation||After upgrading, you will need to import any additional Community Dashboard packs that you had on v3 into v4 (see Dashboard Packs). Only the Community Dashboard packs bundled with the product are automatically imported into v4 as part of the migration.|
|'xxx' is a modified version of a v3.0 Community Dashboard. After upgrade this item may be duplicated|
After upgrading decide whether to keep the edited dashboard or the new dashboard from the newly imported v4 Community dashboard pack(see Dashboard Packs). Any v3 dashboards which originated from Community Dashboard packs and were edited, are cloned and recreated in v4 as separate stand-alone dashboards (See FAQs I've upgraded SquaredUp but some of the built in dashboards are missing, others are duplicated?)
After making changes you can re-run the Upgrade Assessment Tool at any time following the steps above.
You are licensed to run v3 and v4 side-by-side in production for 3 months. This is to enable you to complete the migration and configure v4 before going live and switching your production use to v4. After 3 months your v3 instance will no longer be supported; if you have any concerns please contact Support.
Once you are ready to move to v4 in production, enter your Primary licence key into the v4 Switchover Portal to convert all your existing v3 licences to v4 licences which can be used to activate v4.
We recommend the side-by-side upgrade, and this article will you lead you through this process.
A side-by-side upgrade migrates all supported content from v3. This is our recommended upgrade method for production environments, as it will migrate as much content as possible. If any issues occur during the upgrade you still have access to the v3 instance to use as a reference to re-create content and continue to serve users. You can then carry out any user training and migrate users from v3 to v4.
We recommend the side-by-side upgrade, because the in-place upgrade installs v4 on top of the v3 instance. With in-place any migration issues that cannot be automatically resolved will result in data loss as the issue will not be migrated, and following an in-place upgrade it is not possible to revert or rollback to v3.
Carry out a side-by-side upgrade
For the full step-by-step guide see How to install SquaredUp for SCOM.
- Download the latest version of SquaredUp v4
Run the installer .exe that you have downloaded.
- Click Next
- Accept the Licence Agreement and click Install.
- Click Next to move on to check the deployment type.
Check that the installer has defaulted to a side-by-side installation:
Check that your v3 instance has been selected as the instance to be upgraded.
If necessary click the edit button to change the deployment type to side-by-side upgrade (Recommended), then click edit to select your v3 instance from a list of installed instances, and finally click ok twice to return to the deployment type screen.
- Click on View Upgrade Report to review any outstanding migration issues. This report shows the same issues as the v4 Upgrade Assessment Tool.
Click Next to move on to check the deployment location.
The new SquaredUp v4 application pool identity (How to check and modify the application pool identity) will be set to Network Service by default. This is because a new application pool is created for a side-by-side install of v4 and the installer cannot read the password for any domain service accounts that the v3 app pool may be using. It can be changed to a domain service account after selecting the deployment type during the install, and the password input manually. The application pool identity is important if you are using the SQL tiles (see How to configure access to a database for use with the SQL tile) or Windows authentication (see How to configure Windows authentication) with Kerberos.
Complete the installer.
If the message
Upgrading SquaredUp will currently failis displayed, contact Support with a copy of the log file (accessible by clicking view log). If in the meantime you wish to evaluate v4 without your existing settings, you can change the deployment type to
New Installationto deploy v4 without migrating any settings.
The upgrade will automatically migrate all applicable settings and content; in the event that something cannot be migrated to the v4 instance then it will be listed in the report for you to resolve later.
For more information on issues in the report see the earlier section Upgrade Assessment Report - Issues and Resolutions.
The upgrade process will migrate as much of the navigation bar as possible, before placing any remaining dashboards in an Issues folder. This may include:
- Dashboards that were in multiple places on the navigation bar or included in multiple profiles.
- Dashboards that were not on the navigation bar, if the More menu was not globally enabled.
Any issues should be reviewed and resolved by the SquaredUp admin team by choosing a new home for the dashboard and moving it out of the Issues folder into the appropriate place on the global navigation bar or Team Folder.
You will need to manually re-create all Web API and Azure providers with exactly the same name in v4.
SquaredUp uses secure encryption to store any credentials and connection details for Web API providers. SquaredUp relies on IIS to generate and store encryption keys. It is not possible for an IIS application to decrypt settings from another IIS application, unless you specifically generated and securely stored your own key prior to creating providers in SquaredUp.
When migrating dashboards, Web API and Azure tiles bind to and use the providers name. This means that if you recreate your providers with the same names, all tiles will continue to work.
Provider names are case-sensitive, so
ServiceNow are not equivalent.
If your providers make use of OAuth 2 or Azure connections, you will need to locate or regenerate the client secret as we do not expose the value of that field in either version of SquaredUp.
For more information see How to use the Web API tile - How to use the Web API tile.
All Open Access dashboards and perspectives will have been given new URLs in v4.
You must now either update all systems that are embedding Open Access dashboards or perspectives with the new URL (such as wall dashboards, Sharepoint, or other monitoring tools) or put some kind of redirect in place to automatically redirect traffic on the old URL to the v4 version. The Upgrade Assessment Tool will provide a list of the invalidated Open Access URLs and their updated value.
This can be achieved in a number of ways:
- IIS Rewrite rule (see How to configure a redirect using the IIS URL Rewrite module)
- Load Balancer
- HTTP Proxy forwarding rule
Decide which users should be able to administer SquaredUp and make them SCOM admins (How do SCOM roles and permissions affect what users can do in SquaredUp?).
Configure the navigation bar
Configure the navigation experience, as this can only be done by SquaredUp admins. See How to edit the Navigation Bar.
Configure Team Folders
The upgrade process will automatically recreate v3 user profiles as Team Folders in v4, in a way that makes the new v4 navigation structure similar to that of v3.
Following the upgrade you should review the navigation bar and Team Folders created, as you may like to change the structure that's been automatically created. For example, if a v3 profile has multiple sub-folders the migration may create several Team Folders, in order to replicate the v3 navigation bar.
Team Folders provide a new way of controlling not just authoring permissions, but also true role-based access control on dashboard visibility. Consider whether you have any dashboards that you may now wish to restrict access to and either:
- Create new Team Folders and move individual dashboards, or
- Convert an existing folder into a Team Folder (see Team Folders - Converting a folder into a Team Folder).
Once you have created a Team Folder you can configure permissions so that non-admins can create and edit dashboards within it, and the right users can view particular dashboards.
Publish any global dashboards and perspectives via Open Access
Any globally viewable dashboards you want to publish with Open Access (How to publish dashboards with Open Access) must be made available by a SquaredUp admin.
Any perspectives you want to make available via Open Access should be pinned to the navigation bar (see Pinned Perspectives) before being made available via Open Access by a SquaredUp admin.
Users given the author permission to a Team Folder will be able to publish dashboards within that Team Folder via Open Access.
Enterprise Applications (EAs) are new to v4, so you may want to spend some time reviewing how you can make best use of them. Only SquaredUp administrators (SCOM admins) can manage Enterprise Applications.
Find out more about what an Enterprise Application (EA) is (see Enterprise Applications), and how the EA Designer enables you to model your applications and save directly to SCOM as a new Enterprise Application class, replacing traditional SCOM distributed applications. Examine the new application status dashboards installed with v4, and see how you can create an Enterprise Application (How to create an Enterprise Application) and configure availability tests (Enterprise Applications - How to configure an availability test). There is also the option for Manual availability reporting (How to manually set the health state of an application) which allows you to manually change the health state of an application from available to either degraded or unavailable, as well as enter your own message to users.
Following a side-by-side upgrade, you may wish to re-use the URL that users were previously using to access SquaredUp v3. You may choose to do this now, or following user training. How you do this depends on how you were originally serving SquaredUp to users:
- DNS A/CName record change
- IIS Rewrite rule
- Load Balancer
- HTTP Proxy forwarding rule
SquaredUp v4 has several changes to navigation and dashboard authoring workflows to make them simpler and more intuitive. Users who have previously had access to v3 may require some end-user training if they are used to the v3 experience. Depending on your organisation you may cover this as user acceptance testing prior to upgrading, or user training afterwards.
Areas of focus should include:
- Navigation bar experience
- Dashboard authoring with Team Folders
- Using Team Folders to control dashboard visibility
- Enterprise Application dashboards
- Visual Application Discovery and Analysis (VADA)
Navigation bar experience
v4 includes an updated navigation experience that is more like a traditional file system. When clicking on a folder, SquaredUp will now automatically navigate to the first dashboard in that folder. When viewing a dashboard, a new ribbon is displayed below the navigation bar that displays all sibling items in the same folder. This can greatly simplify the navigation bar for users who typically work in a specific area of the navigation bar (such as the SQL team, who have their own subsection and rarely access dashboards beyond it).
Dashboard authoring with Team Folders
Using Team Folders users are given permissions to edit or create dashboards in a particular folder and need to navigate to the folder before they can click the + button to create a new dashboard.
Using Team Folders to control dashboard visibility
Team Folders represent a new way of controlling dashboard accessibility, which is extremely useful when teams wish to provide "public" dashboards to other teams, but maintain a set of private dashboards that only they have access to. This can be accomplished by creating two team folders - a "public" one that contains users/groups with view permissions but not authoring, and a "private" one that only that team has any visibility to. If you employ this setup, be sure to educate users on which folders are private and public, so they do not create/expose dashboards unintentionally.
Enterprise Application dashboards
Once you have configured some Enterprise Applications (EAs) you should show your users the Application status dashboards and how they work. Only SquaredUp administrators (SCOM admins) can manage Enterprise Applications.
In v4 the VADA (Visual Application Discovery and Analysis) perspective is now primarily focussed on troubleshooting and understanding upstream and downstream dependencies of a component (which now includes other objects, as well as computers). Such maps can no longer be saved when created via this method. In v3 users could browse to any computer, use VADA to map an application and save this map as either a dashboard or a SCOM Distributed Application (DA). This has now been incorporated into the new EA Designer (How to create an Enterprise Application).
When mapping using VADA we now use a 'Filter in' methodology - previously every discovered process would show and create network nodes on the diagram unless it had first been filtered out (either globally or via a map specific filter list). Now when performing discovery on a node you must explicitly select discovered processes, services and components that are part of your application, and only then will they be added to the diagram and links appear. This makes for much cleaner maps that only contain relevant items, and prevents a highly connected "management" server (such as an IT Monitoring tool) from flooding the diagram with every server in your environment.
Before decommissioning and disabling your v3 instance, we recommend taking a backup of the SquaredUp files so that you can refer back to them should any issues come up in the future (most likely a user realising they had an unpublished draft they want to retrieve). See How to backup and restore SquaredUp for SCOM. You can then use the JSON files as a reference for recreating that content in v4.
Once your migration has been completed and v4 is running in production, you have 3 months of support on your existing v3 instance before v4 is your only supported and licensed platform. This should give you enough grace period to migrate any users who did not move across immediately, and give you a fallback should any unanticipated issues arise during initial adoption. If you have any concerns please contact Support.
Redirect users from v3 to v4
If you haven't already done so you should redirect traffic from SquaredUp v3 to v4, jump to Redirect traffic from v3.
The v4 upgrade process preserves any dashboards that you have customised - any modified dashboards will be cloned and recreated in v4. During the upgrade all community packs are removed as v3 packs and v4 packs are no longer compatible. To restore those dashboards, please import the v4 version.
When v4 is installed we re-import the community packs bundled with the product (such as Windows Server, IIS and SQL). If you have customised one of those dashboards yourself you will now have two versions - the native v4 version and your customised v3 copy. It is up to you to choose which version you want to keep (or amalgamate the two).
SquaredUp v4 uses a new high availability (HA) architecture which makes it simple to configure and support higher volumes of usage.
We recommend a side-by-side upgrade as described in Upgrading SquaredUp when using high availability (see Enabling High Availability).
The installer will recognise that HA is configured and automatically configure SquaredUp v4 to use the same share.
Please note that the new SquaredUp v4 application pool identity (How to check and modify the application pool identity) will be set to Network Service by default, but can be changed to a domain service account during the install, and the password input manually. This is because a new application pool is created for v4 and to set it to use the v3 domain service account that account's password must be retrieved, which the installer is unable to do.
When upgrading a HA secondary server, EAM features are not available for the first 15 minutes.
For more information see Enabling High Availability.
Why is my Profile/Navigation bar layout no longer supported?
The v4 navigation bar, Team Folder system and role-based access control is modelled on a file system structure. Version 3 allowed you to do several things that often ended up being damaging or counter-intuitive, and became complicated once an RBAC model was applied to dashboard visibility. To find out more jump to Changes to be aware of.
During the upgrade issues were reported and I've made changes, can I rerun the report?
In the installer simply click back and next to re-run the report. If you performed the report via the
upgrade.exe tool, you can simply run the tool again (jump to 2. Run the v4 Upgrade Assessment Tool).
I'm running SquaredUp v2, how do I upgrade to v4?
SquaredUp v2 reached 'end of life' in July 2019. To benefit from the many new features in v4 please get in contact with SquaredUp Support so we can discuss your options and undertake a migration strategy that best suits your needs.
I'm running SquaredUp v3 CE (Community Edition), how do I upgrade to v4?
While Community Edition is no longer available, there are low priced options that will allow you to benefit from the latest version of SquaredUp for SCOM. Please contact our sales team at email@example.com.
How does upgrading effect the authentication I'm using?
Side-by-side and in-place upgrades will use the authentication method configured for the instance you are upgrading, either forms or Windows authentication. If SquaredUp is not installed on a SCOM server, and you are using Windows authentication with a domain service account it is particularly important that you reconfigure the domain service account and input the password during the upgrade. Otherwise, the installer will set the application pool to Network Service (as mentioned above) and you will be unable to login because the Kerberos SPNs will be configured for the domain service account.