Upgrading Alpana from v1.1 to v2.0

Notice of incompatibility

Between the last v1 (v1.1.1.5) and the first v2.0, major changes were made in the core of Alpana. Due to those breaking changes, v1 and v2 will not be compatible :

Dashboards created in v1 (v1.1.1.5 and before) cannot be opened in v2.0 (up to v2.0.7.6 at least).
Dashboard Server installations from v1 (v1.1.1.5 and before) cannot be upgraded to v2.0 (up to v2.0.7.6 at least) directly
v1.1 and v2.0 applications cannot be installed side by side on the same machine

This change was required in order to allow some of the new and upcoming features. We strive to avoid as much as possible this type of breaking change, and we are deeply sorry to make an exception for this release.

How to upgrade from v1.1 to v2.0

Automation

[code192] is currently working on an Alpana Upgrade Helper tool to automate part of the upgrade from v1.1 to v2.0. This tool will focus on upgrading part of the v1.1.1.5 dashboards to the new v2.0 format. It will not cover all features, in particular because some of the core concepts are quite different.

If you have a large number of dashboards and the below manual procedure is impractical, you may wish to wait for the release of this upgrade tool.

Please contact [code192] to know more. https://www.code192.com/

Manual upgrade

In order to upgrade Dashboards from v1 (v1.1.1.5 and before) to v2.0 (up to v2.0.7.6 at least), you will need to perform manual steps :

re-create dashboards in v2.0
backup v1.1 installation
un-install v1.1
install and configure v2.0
publish dashboards and re-create users, categories, schedules

Please see below for advice and more details.

General advice

You should keep your v1.1 installation running as long as possible in order to be able to view the old configuration at any time. You should wait to have re-created your dashboards before deploying v2.0 fully, in order to ensure continuity of service.

1 - Re-create dashboards in v2.0

When re-creating Dashboards, it can be an opportunity to create them differently in order to take advantage of new v2.0 features, like Parameters, Multi-Source, improved Stored Procedure handling, etc…

setup

Keep your v1.1 installation running, it will be useful for re-creating the configuration of your dashboards. On a separate machine with access to the data, install Alpana Designer v2.0 (note that .NET Framework 4.7 is now required). Like this, you can have the old dashboard open in the v1 Designer on one side, and your new work in v2.0 on the other side at the same time.

For each dashboard re-created, you can follow the following checklist :

a - Data Sources

For each Data Source :

Connections

Re-create Connections to your data.
Take a note of the database and users. You will need the same credentials to connect.
For Historian or Web Connections, you may not have access to the parameters directly in v1. If so, you will need to retrieve the information from the Data Integration Tool.

Tables

Add tables/views and make the same JOINs.

Columns

Renamed columns are marked with a star/asterisk/*
Hide columns if needed

Filters

Check for Data Source filters

Expressions

Re-create Expressions

(optional) Export

Save or publish the Data Source. It’s of course optional, but can be useful if you need to re-use it in your other Dashboards.

b - Layout

Re-create widget layout

For each Widget :

custom Maps

For Chorlopleth and Bubble Maps :

get custom map *.json file
for generic maps (World, etc), the same maps are included in v2.0

Data

Bind data
check for Widget-level filters on the data columns
check for sorting configuration
check for measure formatting. In v2.0 this configuration is made in the “Properties” pane instead.

Properties

copy-paste name and description
check properties one by one
for custom colors, copy-paste color hex codes
for URL link, copy-paste URL. You may need to update the target if they have been renamed. You can edit that later when the items are published.

Filter role

check if widget is Master Widget
check if widget has Ignore Filters

d - Filter binding

reproduce filter binding

e - Dashboard-level configuration

copy title and description
check for auto-refresh

f - Preview

Make a local dashboard Preview to check that the re-created dashboard behaves as expected, and make the required changes.

g - Save

Save your migrated dashboard as a local file.

Be careful that the extension name is the same (*.sydx).

2 - Backup v1.1 installation

backup

Perform a complete backup of your v1.1 installation :

archive the complete folder “C:\ProgramData\Code192\Dashboard Server\”
archive the Alpana Server database you configured when installing v1. You can find its name inside “C:\ProgramData\Code192\Dashboard Server\Configuration\Config.xml” under tag “<SqlConfiguration><DataBaseName>”

prepare user import

If you have many users to re-create, you can export the list as CSV from v1 : In the Alpana Server database, export the content of the [ALP_User] table as CSV.

prepare website binding

In IIS (inetmgr), take a note of the current bindings for your Alpana website : port number, name, …

prepare configuration

In Alpana Server web portal, go to the administration pages (at “http://yoursite/en-us/administration”) and take a note of all configuration to re-create :

site URL
branding
e-mail settings
AD settings

List other items

If there are other items to re-create from Server, list them :

Categories
Schedules
published Dashboards/Widgets/DataSources

3 - Un-install v1.1

The best workflow is to leave v1.1 installed as long as possible and deploy v2.0 on a different machine. This way, you can ensure that the migrated platform will behave as expected. For this workflow, you can delay the un-install of v1.1 to a later step.

However, if you need to install Alpana v2.0 on the same machine as v1.1, you will need to uninstall v1.1 first.

a - uninstall Data Integration Tool

If you installed the Data Integration Tool, you will need to un-install it.

From the system tray, right-click and Stop the Data Integration Service
uninstall “code192 Data Integration Platform” from the Windows Control Panel
in Windows services.msc , make sure that the Service “code192 Data Integration Agent” is well un-installed

b - uninstall Web API

If you installed the Web API, you won’t need it anymore to get data from Historian.

Un-install the code192 “Web API” from the Windows Control Panel. If needed, choose to “close application”.
in Windows services.msc , make sure that the Service “Code192 Web API” is well un-installed

c - uninstall Dashboard Designer

From Windows Control Panel, uninstall “code192 Dashboard Designer”

d - uninstall Dashboard Server

Make sure that you have backups
From Windows Control Panel, uninstall “code192 Dashboard Server”
During uninstallation, select to “Remove resources and drop the database”. WARNING : At this step, you will lose your v1.1 dashboards and configuration if you didn’t make backups.
in Windows services.msc , make sure that the Service “Code192 Dashboard Server Scheduler” is well un-installed

e - clean up

Services

If a service didn’t uninstall properly, you can follow the following Windows procedure :

get the Service name from services.msc, for example “Code192 Dashboard Server Scheduler”
Open a command prompt with administrative rights
stop the service using the command SC STOP for example : SC STOP Code192 Dashboard Server Scheduler
delete the service using the command SC DELETE for example : SC DELETE "Code192 Dashboard Server Scheduler"

folders

Unless you have other [code192] products installed, make sure that there are no more code192 folders inside :

C:\Program Files (x86)\
C:\ProgramData\
C:\ root directory

4 - Install and configure v2.0

installation

Check the new pre-requisites for Alpana v2.0. In particular, note that .NET Framework 4.7 is now required.
Follow installation instructions to install Alpana v2.0 Server and Designer.
When installing Alpana Server, install with the appropriate port and IIS site name

configure Alpana Server

In Alpana Server web portal, go to the administration pages (at “http://yoursite/en-us/administration”) and restore all the configuration needed :

site URL
branding
e-mail settings
AD settings

5 - Publish dashboards and re-create users, categories, schedules

In your new fresh install of Alpana Server v2.0, you will need to re-create items as backed-up previously :

create Categories

Create the Categories needed. Use the correct names for dashboard linking, or update the link URLs inside dashboards after publishing.

publish items

Publish the validated Dashboards/Widgets/DataSources

give access to users

re-create Groups of users
re-create Users. If you have many users, you can make use of the [ALP_User] table you exported as CSV from v1, and use “New User > Import from CSV”.
assign permissions to Categories for Groups, assign Users to Groups