How to migrate from SquaredUp DS for SCOM v3 to v4

This article describes how to migrate from SquaredUp DS v3 to v4. We recommend you read through this article before starting the migration, to familiarize yourself with the migration process and the changes between versions.

Why migrate to the latest version of SquaredUp DS?

The latest version of SquaredUp DS is v5. If you already using SquaredUp DS v4 and are looking to upgrade to v5 see How to migrate from SquaredUp DS for SCOM v4 to v5.

If you are currently using SquaredUp DS 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 DS v3 end-of-life was 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 DS 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 DS 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 organization.

• Dark theme - users can now choose to run SquaredUp DS in light or dark mode (see Theme Personalization).
• Line graph and donut visualizations 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-customizable, 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 organization (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 DS v4 to make it simple to configure and support higher volumes of usage (see Enabling High Availability).

For the full list of improvements and bugs addressed see the What's New in SquaredUp DS for SCOM and Release Notes for SquaredUp DS for SCOM.

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 DS navigation structure and Team Folders before giving users permissions. Some tasks can only be carried out by SquaredUp DS 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 DS admins can create/edit SQL, Web API, and Azure tiles (Application Insights and Log Analytics), seeHow 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 DS admins can create/edit perspectives (see Working with perspectives).
• Only SquaredUp DS admins can manage the global navigation bar structure (see How to edit the Navigation Bar).
• Only SquaredUp DS admins can create/delete Team Folders.
• Administrative permissions cannot be delegated outside of SquaredUp DS admins (see How do SCOM roles affect what users can do in SquaredUp DS?)

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 5. Configure SquaredUp DS v4.

Planning the upgrade

Summary of the upgrade process

1. Before Upgrading - complete the upgrade prerequisites

2. Licensing - get a v4 license from the switchover portal

3. Download and install SquaredUp DS v4 side-by-side

4. Resolve any migration issues

5. Configure SquaredUp DS v4

6. User Training

7. 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. Contact SquaredUp Support for the v3.4.6 download if needed.
• Check the SquaredUp server spec (see System Requirements, 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 Sharing Dashboards with anyone - Open Access)

How to add a perspective to the navigation bar (v3)

When you publish the perspective tick add perspective to navigation bar (option available in SquaredUp v3.1 onwards).

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

How to revoke all dashboard authoring privileges (v3)

SCOM administrators can author dashboards and you cannot revoke this in SquaredUp. For other users who have been given dashboard authoring via user profiles this can be switched off via user profiles.

1. In SquaredUp click on the right-hand menu ☰ > system > profiles

2. Select the relevant AD group in the Choose profile dropdown.

3. Under Permissions > Authoring click disable all. Users will have their authoring permissions revoked when they logout and log back into SquaredUp.

• Consider user acceptance testing prior to upgrading, and user training after upgrading (jump to 6. User Training).
• Backup SquaredUp DS v3 - it is good practice to ensure you have a working backup before upgrading.

How to backup SquaredUp (v3)

You can backup the entire application folder, which by default is located at C:\inetpub\wwwroot\SquaredUpv3,

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

2. Licensing

You may want to perform upgrade testing and user acceptance testing (jump to 6. User Training) in your test/dev environment. For this please request a 30 day evaluation license 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 SquaredUp Support.

Once you are ready to move to v4 in production, enter your Primary license key into the v4 Switchover Portal to convert all your existing v3 licenses to v4 licenses which can be used to activate v4.

3. Download and install SquaredUp DS 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 DS for SCOM.

1. Download the latest version of SquaredUp DS v4

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

   

3. Click Next

4. Accept the License 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.

   Understanding the Upgrade Report

   The Upgrade Report 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 (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 Sharing Dashboards with anyone - Open Access). How to add a perspective to the navigation bar (v3) When you publish the perspective tick add perspective to navigation bar (option available in SquaredUp v3.1 onwards).
   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 DS but some of the built in dashboards are missing, others are duplicated?)

    

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

   The new SquaredUp DS 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 User authentication methods for SquaredUp DS for SCOM) with Kerberos.

10. Complete the installer.

    If the message Upgrading SquaredUp will currently fail is displayed, contact SquaredUp 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.

4. 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 Upgrade Report for you to resolve later.

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 DS 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 DS uses secure encryption to store any credentials and connection details for Web API providers. SquaredUp DS 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 DS.

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

For more information see How to use the Web API tile.

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 (see How to configure a redirect using the IIS URL Rewrite module)
• Load Balancer
• HTTP Proxy forwarding rule

5. Configure SquaredUp DS v4

SquaredUp DS administrators

Decide which users should be able to administer SquaredUp DS and make them SCOM admins (How do SCOM roles affect what users can do in SquaredUp DS?).

Configure the navigation bar

Configure the navigation experience, as this can only be done by SquaredUp DS 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)

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 (Sharing Dashboards with anyone - Open Access) must be made available by a SquaredUp DS 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 DS 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 DS 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.

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 DS v3. You may choose to do this now, or following user training. How you do this depends on how you were originally serving SquaredUp DS to users:

• DNS A/CName record change
• IIS Rewrite rule
• Load Balancer
• HTTP Proxy forwarding rule

6. User Training

SquaredUp DS 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 organization 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 DS 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 DS administrators (SCOM admins) can manage Enterprise Applications.

VADA

In v4 the VADA (Visual Application Discovery and Analysis) perspective is now primarily focused 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.

7. Decommission v3

Backup

Before decommissioning and disabling your v3 instance, we recommend taking a backup of the SquaredUp DS files so that you can refer back to them should any issues come up in the future (most likely a user realizing they had an unpublished draft they want to retrieve). See How to backup and restore SquaredUp DS for SCOM. 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 SquaredUp Support.

Redirect users from v3 to v4

If you haven't already done so you should redirect traffic from SquaredUp DS v3 to v4, jump to Redirect traffic from v3.

FAQ

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

The v4 upgrade process preserves any dashboards that you have customized - 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 customized one of those dashboards yourself you will now have two versions - the native v4 version and your customized 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 DS 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 DS when using high availability (see Enabling High Availability).

The installer will recognize that HA is configured and automatically configure SquaredUp DS v4 to use the same share.

Please note that the new SquaredUp DS 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 modeled 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 How to migrate from SquaredUp DS for SCOM v3 to v4).

I'm running SquaredUp DS v2, how do I upgrade to v4?

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