22 minute readApplies to: v4

Migrating from previous versions of Squared Up to v4

Summary

Squared Up v4 features several improvements to dashboard authoring, navigation, and performance. In most cases content and settings from previous versions can be migrated into Squared Up v4, however in a few cases there are gaps in currently implemented features or no direct equivalents. This article provides our suggested, fully supported migration strategies, and attempts to provide you with all the information you need to determine how best to deploy and migrate to Squared Up v4 in production.

Licensing

Before starting your v4 installation, you should request a v4 evaluation licence, which will allow you to perform any upgrade testing and user acceptance testing, prior to going live and switching your production use to v4. Without this licence you will be able to install v4 and perform an upgrade assessment, but unable to then activate the product and start testing.

Once you are ready to move to v4 in production, you can convert your existing v3 licence to a v4 licence, which you will then be able to use to activate v4. From that point you will have 3 months to run v3 and v4 side-by-side in production, before the v3 instance is no longer supported and you will be in violation of the Squared Up EULA.

Supported Upgrades

The following sections detail the supported migration paths for previous versions of Squared Up.

v3

Before any migration we recommend that you upgrade your v3 environment to the latest version, and only support upgrades from v3.3.5 or later. If you using the OMS tile on v3 we recommend that you first upgrade to at least v3.4, so that you can replace OMS tiles with Azure Log Analytics tiles prior to upgrading. The OMS tile has been removed from v4, as Microsoft are closing the OMS portal in January 2019, and switching to the Log Analytics tile whilst the OMS tile still functions is recommended.

When choosing to move from Squared Up v3 to v4 you have three migration strategies (installation options):

  • Side-by-side upgrade (recommended) - this will attempt to migrate all supported content from v3 to v4, while leaving v3 as it is. This is the default and recommended installation strategy. V4 adoption may also need some user training which, depending on the number of Squared Up users, may require a phased approach to user adoption, only possible with a side-by-side upgrade.
  • In-place upgrade - this will upgrade v3 to v4, but as not all v3 navigation layouts and permissions can be directly migrated into Team Folders some may be lost during an in-place upgrade.
  • New installation - this is a new and separate installation of v4 alongside your v3 instance, that does not attempt to migrate any content from v3.

This article explores these three installation options, the planning and installation considerations for each and the 'Upgrade readiness assessment' tool.

v3 CE (Community Edition)

As it has been withdrawn, there is no migration path between CE editions of Squared Up v3 and v4. In order to move to v4 CE users will need to upgrade to a paid edition of v4.

v2

As with migrating from v2 to v3, no direct upgrade path exists between v2 and v4 of Squared Up. Whilst migration paths do exist, much has changed between v2 and v4 and this may require a re-envisioning of your dashboards, navigation bar, and integration scenarios.

Squared Up v4 builds on a number of key features implemented in v3, so if you have never looked at v3 we recommend you familiarize yourself with the key changes.

Contact Squared Up Support (support@squaredup.com) so we can discuss your options and undertake a migration strategy that best suits your needs.

Technical Preview

If you have a technical preview (TP) installed, you should remove this before installing Squared Up v4.

Upgrading a high availability (HA) configuration

We recommend running a side-by-side upgrade on the Primary and then Secondary servers. The installer will recognise that HA is configured and automatically configure Squared Up v4 to use the same share. Please note that the new Squared Up 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 a domain service account that account's password must be entered, which the installer is unable to do.

Authentication

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

Planning

The following sections outline key decisions and activities you should complete when planning a migration.

Squared Up Prerequisites

There are no other changes to either recommended software/hardware configurations to run Squared Up, or supported platforms (either server-side or client-side).

Known issues

The following items cannot be migrated directly between v3 and v4 (either due to feature gaps or design changes):

  • Draft dashboards and perspectives cannot be migrated
  • Perspectives cannot be added to the navigation bar
  • Perspectives cannot be published via Open Access
  • A dashboard cannot appear multiple times on the navigation bar
  • A dashboard must appear on at least one profile's navigation bar

    • If the More menu is enabled on v3, all dashboards that are not featured in a profile will be added to a More folder on the global nav bar
  • A dashboard may not act like a folder on a navigation bar (contain further child dashboards).
  • Dashboards may not appear at the root of a profile's navbar (does not apply to the global nav bar)
  • Only Squared Up admins can create/edit SQL, Web API, and Azure tiles
  • Only Squared Up admins can create/edit perspectives
  • Administrative permissions can no longer be delegated outside of Squared Up admins (all SCOM admins by default)
  • As it is not possible for an IIS application to decrypt settings from another IIS application, WebAPI providers must be recreated.
  • The OMS tile is removed in v4, and must be rebuilt as Azure Log Analytics tiles
  • Community Dashboard packs must be reimported after installation.

    • If you have made changes to a community pack dashboard, those changes will be migrated as a stand-alone dashboard
  • Dashboards published via Open Access will have different URLs

During migration, any issues with navigation bars will result in the dashboard being placed in an Issues folder, so content will not be lost. You can then assign the dashboard to an appropriate location post installation.

Upgrade readiness assessment

Before starting the upgrade process, you can run an upgrade readiness assessment to gauge how many issues are present in your v3 environment and attempt to resolve them prior to the upgrade. This is crucial when performing an in-place upgrade, as issues that cannot be automatically rectified may result in a loss of data or configuration settings.

The upgrade assessment will also highlight issues that are not related specifically to upgrading to v4 but may impact the health of v3 (such as corrupt or missing dashboards).

The assessment tool is run automatically, and the results presented during installation, but is also available as a command-line tool via the Squared Up deployment tools. This can be found at c:\Program Files\Squared Up\4x. You can also download it as a stand alone tool from https://download.squaredup.com/.

In the below example the --target argument refers to the install location of your v3 instance of Squared Up.

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

Select deployment method

When deploying Squared Up v4 you have three installation options, each one aimed at a particular migration strategy.

A side-by-side upgrade that attempts to migrate all supported content from v3. This is our recommended upgrade method for production environments, as it will migrate as much content as possible, but if any issues occur during upgrade you still have access to v3 to use as a reference to re-create content and continue to serve users.

After v4 has been installed, we recommend that you revoke all dashboard authoring privileges so that content cannot change during upgrade, and you are not required to make manual changes to keep v4 in sync with v3, whilst users are on-boarded into v4. This can be done by modifying user profiles, firewalls, or Active Directory groups.

As it is not possible for an IIS application to decrypt settings from another IIS application, you will be required to manually re-create all WebAPI providers (with exactly the same name) in v4. Creating them with the same name will allow all tiles which previously used that provider to continue to function.

New installation

A new installation of v4 alongside your v3 instance, that does not attempt to migrate any content from v3. This method is most useful in the following scenarios:

  • Upgrading test environments for platform compatibility.
  • You need to migrate small groups of users/teams over a long period of time, manually recreating their content right before moving each team.
  • You want a fresh start, manually rebuilding dashboards and navigation structures from the ground up with v4 changes and capabilities in mind.

In-place upgrade

An in-place upgrade installs Squared Up v4 on top of an existing v3 installation. Any migration issues that cannot be automatically resolved or mitigated will result in data loss as the issue will not be migrated and unavailable in v4. Once complete, it is not possible to revert or rollback to v3.

You should only choose this method if you have completed the upgrade readiness assessment without reported issues, and are confident that end-user adoption will not require any kind of phased onboarding from v3 to v4. This option is typically only useful for:

  • Small environments without any custom profiles.
  • Test environments where only Squared Up admins are using the environment.
  • Environments that feature many WebAPI providers, where it would be difficult to re-create each connection.

Encrypted connections

Squared Up uses secure encryption to store any credentials and connection details for Web API providers. Squared Up relies on IIS to generate and store encryption keys. Unless you specifically generated and securely stored your own key prior to creating providers in Squared Up, any side-by-side upgrade process will not be able to decrypt that data as IIS applications are isolated from each other and not able to access each other's keys.

When migrating dashboards, Web API and Azure tiles bind to and use the providers name. This means if after migrating content from v3 to v4 you recreate your providers with the same names, all tiles will continue to function correctly.

Drafts

During the upgrade process all drafts will be discarded (for both in-place and side-by-side upgrades). For this reason it is important to ensure that any draft dashboards are published prior to running the upgrade (which may involve asking users with authoring rights to ensure they have published all dashboards and perspectives).

User acceptance testing

Squared Up 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. Areas of focus should include:

  • Dashboard authoring with Team Folders
  • Role-based access control using Team Folders
  • Mapping applications or discovering live dependencies using Visual Application Discovery and Analysis (VADA)
  • Navigation bar experience

Installation

Squared Up v4 continues to use the deployment tool technology developed for v3 that allows side-by-side installation of multiple versions and instances of Squared Up. As such deployment follows a similar process to the v3 process or a fresh install of v4:

  1. Run the downloaded Squared Up installer, which will install the Squared Up deployment tools used to deploy or remove Squared Up instances.
  2. Continue through the installer to deploy a Squared Up v4 instance (either in-place or side-by-side)
  3. Activate and configure the instance in-product using a browser.

Side-by-side

Restrict dashboard authoring/editing prior to upgrade

To avoid issues with synchronising content from v3 to v4 during side-by-side upgrades, we recommend that after the upgrade and migration process all users have dashboard/perspective creation, editing, and publishing rights revoked, and the Squared Up admins all be informed that they should not create content or modify settings. This includes:

  • Dashboards and Perspectives
  • Profiles
  • Web API Providers
  • Dashboard Packs
  • Publishing Open Access Dashboards
  • Modify Named Users

This will ensure that dashboards do not drift between v3 and v4 as once the side-by-side upgrade is performed changes made to v3 will not carry over to v4.

Deploy and install Squared Up

After the initial installation, when running the v4 deployment tools, ensure that the deployment type is side-by-side and that your v3 instance has been selected as the instance to be upgraded. If you already have an earlier v4 instance installed on this system, the installer will default to doing an in-place upgrade of that v4 instance. Click the edit button to change the deployment type, and select 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.

The new Squared Up v4 application pool identity will be set to Network Service by default, but can be changed to a domain service account after selecting the deployment type during the install, and the password input manually. This is because a new application pool is created for a side-by-side install of v4 and to set it to use a domain service account that account's password must be entered, which the installer is unable to do. The application pool identity is important if you are using the SQL tiles or Windows authentication with Kerberos.

If the message Upgrading Squared Up will currently fail is displayed, contact Squared Up 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, change the deployment type to New Installation to deploy v4 without migrating any settings.

New Installation

After the initial installation, when running the v4 deployment tools, ensure that the deployment type is New Installation. If you already have an earlier v4 instance installed on this system, the installer will default to doing an in-place upgrade of that v4 instance. Click the edit button to change the deployment type, and select New Installation. Click ok to return to the deployment type screen.

In-place

Create backup of v3 content

Prior to an in-place upgrade of a v3 instance, we recommend taking a backup of the Squared Up 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). Whilst it will not be possible to import dashboard packs from the backup into v4, you can use the JSON files as a reference for recreating that content in v4.

Deploy and install Squared Up

After the initial installation, when running the v4 deployment tools, ensure that the deployment type is in-place and that your v3 instance has been selected as the instance to be upgraded. If you already have an earlier v4 instance installed on this system, the installer will default to doing an in-place upgrade of that v4 instance. Click the edit button to change the deployment type, and select In-place upgrade. 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.

After selecting an in-place upgrade, a new upgrade assessment will run and any issues will be displayed. If any issues are displayed, view the report and attempt to resolve reported issues prior to continuing with the upgrade, otherwise dataloss may occur as a result of the upgrade.

If the message Upgrading Squared Up will currently fail is displayed, contact Squared Up 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, change the deployment type to New Installation to deploy v4 without migrating any settings.

Migrating content and settings

Where possible, an in-place or side-by-side upgrade will migrate all applicable settings and content. However currently v3 and v4 do not share perfect feature parity, and a number of design changes mean that not all settings can be migrated directly. As such you may have issues to resolve post upgrade, which are detailed below.

Resolve navigation bar migration issues

If during the upgrade process any profiles (including the default Everyone profile) contain an invalid navigation bar, the upgrade process will attempt to migrate as much of the nav bar as possible before placing any remaining dashboards under an Issues folder. This may include:

  • Dashboards that were in multiple places on the navbar or included in multiple profiles.
  • Dashboards that were not on the navbar, if the More menu was not globally enabled.

Any issues should be reviewed and resolved by the admin team (likely by choosing a new home for the dashboard and moving it out of the issues folder into the appropriate place on the global navbar or Team Folder), prior to user-acceptance testing.

Restore encrypted connections

When migrating dashboards, Web API and Azure tiles bind to and use the providers name. This means if after migrating content from v3 to v4 you recreate your providers with the same names, all tiles will continue to function correctly. 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 Squared Up.

Please note that provider names are case-sensitive, so servicenow and ServiceNow are not equivalent.

Convert/Create Team Folders

The upgrade process will attempt to automatically recreate any user profiles discovered in v3 as Team Folders in v4. Team Folders provide a new way of controlling not just authoring permissions, but also true role-based access control on dashboard visibility. As such you should review your navigation bar and identify any dashboards that you previously could not restrict access to and either create new team folders and move individual dashboards, or convert an existing folder structure into a team folder.

Update or redirect Open Access URLs

Regardless of which upgrade method you choose, all Open Access dashboards will have been modified with new URLs. The old URL will no longer be valid in an in-place scenario, and in a side-by-side scenario will not be valid when v3 is decommissioned.

You must now either update all systems that are embedding Open Access dashboards 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.

This can be achieved in a number of ways:

  • IIS Rewrite rule
  • Load Balancer
  • HTTP Proxy forwarding rule

The upgrade assessment tool will provide a list of the invalidated Open Access URLs and their updated value.

User training and adoption

There are a number of key areas in v4 that you may wish to focus on when transitioning users between v3 and v4 environments. This section discusses some of the major changes from an end-user perspective.

v4 includes an updated navigation experience that attempts to feel more like a traditional file system. When clicking on a folder, Squared Up 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 navbar (such as the SQL team, who have their own subsection and rarely access dashboards beyond it).

Dashboard visibility and authoring

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.

When clicking the "+" button to create dashboards, the dashboard is automatically placed in the current location on the navbar. This is important for users who only have permissions to create dashboards in certain team folders, as they will need to navigate to those folders before the "+" button will appear.

Mapping applications using Visual Application Discovery and Analysis

Previously in Squared Up v3 users could browse to any computer, use VADA to map an application and save this map as either a dashboard or SCOM distributed Application. This workflow has now been incorporated into the new EA Designer, and as such maps can no longer be saved when created via this method. A mapping session started in this way is now primarily focussed on troubleshooting and understanding upstream and downstream dependencies of a component (which now includes other objects, as well as computers).

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.

Decommissioning previous versions

Backup

Prior to decommissioning and disabling your v3 instance, we recommend taking a backup of the Squared Up 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). Whilst it will not be possible to import dashboard packs from the backup into v4, you can 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.

Redirecting traffic from previous versions

If you have performed a side-by-side upgrade, you may wish to re-use the URL that users were previously using to access Squared Up v3. Squared Up v4 does not include any automatic provision to do this, but here are some suggestions which may apply depending on how you were originally serving Squared Up to users:

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

FAQ

I've upgraded Squared Up 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).

Why is my Profile/Navigation bar layout no longer supported?

Squared Up v4 models its navigation bar and dashboard role-based access control around a file system, for both simplicity and security. Version 3 allowed you to do several things that often ended up being damaging or counter-intuitive, and made no sense once an RBAC model was applied to dashboard visibility.

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

What's New in v4

Where do I find my v4 activation key?

How to Backup Squared Up

How to configure a redirect using the IIS Rewrite module

Azure Log Analytics tile

What's New in v3

Upgrade readiness assessment tool

Squared Up Ltd. (c) 2018Report an issue with this article