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 SquaredUp 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.

 

New features in v4

• Dark theme - users can now choose to run SquaredUp in light or dark mode.
• Line graph and donut visualisations for the 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.
• New ServiceNow tile which introduces a new ServiceNow provider that is much simpler to configure than the generic Web API oauth provider.
• Pinning Perspectives to the navigation bar allows you to make them available via Open Access.
• New navigation structure offers a more intuitive navigation and authoring experience.
• New Matrix tile which supersedes the Dynamic Table tile to bring fully-customisable, data-rich grids to your dashboards.
• Team Folders replace user profiles to enable you to deliver dashboards and delegate control to different teams within your organisation.
• 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.
• 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
• New high availability (HA) architecture - we have redesigned HA in SquaredUp v4 to make it simple to configure and support higher volumes of usage.

For the full list of improvements and bugs addressed see the What's New article and Release Notes.

Changes to be aware of

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.
• Only SquaredUp admins can create/edit SQL, Web API, and Azure tiles (Application Insights and Log Analytics).
• Only SquaredUp admins can create/edit perspectives
• Only SquaredUp admins can manage the global navigation bar structure
• Only SquaredUp admins can create/delete Team Folders
• Administrative permissions cannot be delegated outside of SquaredUp admins

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.

 

Planning the upgrade

 

Summary of the upgrade process

1. Before Upgrading - complete the upgrade prerequisites
2. Run the v4 Upgrade Assessment Tool
3. Licensing - get a v4 licence from the switchover portal
4. Download and install SquaredUp v4 side-by-side
5. Resolve any migration issues
6. Configure SquaredUp v4
7. User Training
8. Decommission v3

You may also like to watch the v4 training webinar: Upgrading from v3 to v4 (42 mins).

 

1. Before Upgrading

There are a few key tasks you should complete before upgrading:

• Ensure you have v3.4.6 installed. Download v3.4.6 here.
• Check the SquaredUp server spec, 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.
• 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.
• Backup SquaredUp v3 - it is good practice to ensure you have a working backup before upgrading.
• Run the Upgrade Assessment Tool as described below.

If you are using high availability see What do I need to consider when upgrading a high availability (HA) configuration?

 

2. Run the v4 Upgrade Assessment Tool

Before starting the upgrade you should run the v4 Upgrade Assessment Tool to see if there are any issues to resolve before upgrading.

1. On your SquaredUp server download the v4 Upgrade Assessment Tool.
2. Extract Upgrade.exe.
3. Open Windows Powershell for the location of Upgrade.exe, for example in File Explorer browse to where you extracted Upgrade.exe then File > Open Windows Powershell > Open Windows Powershell.

4. From Windows Powershell run the following using the location of your v3 instance:

   .\upgrade.exe report --target="C:\inetpub\wwwroot\squaredupv3"

   where the --target argument refers to the installation location of your v3 instance

   

5. The report will show any issues that must be resolved manually after upgrade.

   

 

Upgrade Assessment Report - Issues and Resolutions

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.

Issue	Resolution
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
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
A dashboard cannot appear multiple times on the navigation bar	After upgrading move the dashboard from the Issues folder to the correct location
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
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
Open Access pages will have different URLs	After upgrading update or redirect Open Access URLs (the report shows the old and new URLs)
The upgrade cannot migrate the Web API providers	After upgrading 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. 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. 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 re duplicate or missing dashboards).

After making changes you can re-run the Upgrade Assessment Tool at any time following the steps above.

 

3. Licensing

You may want to perform upgrade testing and user acceptance testing in your test/dev environment. For this please request a 30 day evaluation licence from Sales.

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.

 

4. Download and install SquaredUp v4 side-by-side

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 v4 for SCOM.

1. Download the latest version of SquaredUp v4

2. Run the installer .exe that you have downloaded.

   

3. Click Next
4. Accept the Licence Agreement and click Install.
5. Click Next to move on to check the deployment type.

6. Check that the installer has defaulted to a side-by-side installation:

   

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

8. Click on View Upgrade Report to review any outstanding migration issues. This report shows the same issues as the v4 Upgrade Assessment Tool.

9. Click Next to move on to check the deployment location.

   The new SquaredUp v4 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 or Windows authentication with Kerberos.

10. Complete the installer.

    If the message Upgrading SquaredUp will currently fail is 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 Installation to deploy v4 without migrating any settings.

 

5. Resolve any migration issues

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.

 

Navigation bar migration

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.

 

Recreate Web API providers

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 and 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 Adding a provider.

 

Update or redirect Open Access URLs

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
• Load Balancer
• HTTP Proxy forwarding rule

 

6. Configure SquaredUp v4

 

SquaredUp administrators

Decide which users should be able to administer SquaredUp and make them SCOM admins.

 

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.

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 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 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

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, 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 and configure availability tests. There is also the option for Manual availability reporting 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.

 

Redirect traffic from v3

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

 

7. User Training

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 represents 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.

 

VADA

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.

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.

 

8. Decommission v3

 

Backup

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). You can then use the JSON files as a reference for recreating that content in v4.

 

Licensing

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, see Redirect traffic from v3 above.

 

FAQ

 

I've upgraded SquaredUp but some of the built in dashboards are missing, others are duplicated?

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).

 

What do I need to consider when upgrading a high availability (HA) configuration?

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.

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 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 high availability (HA) on v4

 

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 see What's changed in v4?.

 

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.

 

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 sales@squaredup.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.