Migrating from Dundas Dashboard to Dundas BI
1. Overview
DD Migrator is a command-line tool which lets you migrate or import one or more projects from an instance of Dundas Dashboard (DD) to an instance of Dundas BI. The following types of Dundas Dashboard objects can be migrated:
- data connectors
- virtual tables
- virtual cubes
- dimensions
- datasets
- KPIs
- analytical (OLAP) reports
- files and folders for the above objects
- user accounts
- security groups
- privileges
- internal objects such as parameters for the above objects, tokens, KPI/dataset states, and calculated measures
Note that dashboards and mashups in Dundas Dashboard are not migrated.
2. How to get the migration tool
DD Migrator is not included with the installation of Dundas BI and is only available upon request.
Please contact Dundas Support (support@dundas.com, 1.416.467.9100) for approval and instructions on downloading DD Migrator.
3. Prerequisites
The DD Migrator tool requires:
- Access to the DataStore database of a Dundas Dashboard 5.5 instance via connection string.
- Access to the Application database of a Dundas BI 2.6 instance via connection string.
- Optionally, a list of one or more IDs of the Dundas Dashboard projects you want to migrate.
If your Dundas Dashboard version number is below 5.5, you can either upgrade it to Dundas Dashboard 5.5 beforehand, or follow these steps:
- Download and install the latest Evaluation version of Dundas Dashboard 5.5 on your Dundas BI server. You don't need a retail license in this case, the evaluation version will do just fine for the purposes of migration.
- Go to your production version of Dundas Dashboard and use the Project Manager to export the project(s) you want to migrate into an export file.
- Use the Project Manager to import the export file into the Version 5.5 evaluation instance of Dundas Dashboard.
- Run DD Migrator using the connection string from the evaluation instance of Dundas Dashboard 5.5.
Technically, DD Migrator does not require access to the instance or installation of Dundas Dashboard to work. It just needs access to the DataStore database via connection string. So if your Dundas Dashboard instance is running on a separate server which is not directly accessible by DD Migrator, you can simply backup the Dundas Dashboard DataStore database and restore it within reach of DD Migrator via connection string.
4. Setting up DD Migrator
The DD Migrator tool is downloaded as a ZIP package containing a number of files without any folder structure. You can extract the files and place them anywhere on your Dundas BI server.
For example, create a sub-folder DDMigrator under the tools folder of your Dundas BI instance and extract the files into that sub-folder. In a default installation of Dundas BI, the full path of this sub-folder would be:
C:\Program Files\Dundas Data Visualization Inc\Dundas BI\Instances\Instance1\tools\DDMigrator
Once you've extracted the files, locate the configuration file named DDMigrator.exe.config.
Edit this file in Notepad and manually change the AppDataPath setting to point to the App_Data path of the target Dundas BI instance. This path can be relative or fully qualified.
Example:
<applicationSettings>
<Dundas.BI.DDMigrator.App>
<setting name="AppDataPath" serializeAs="String">
<value>C:\Program Files\Dundas Data Visualization Inc\Dundas BI\Instances\Instance1\www\BIWebsite\App_Data\</value>
</setting>
</Dundas.BI.DDMigrator.App>
</applicationSettings>
5. Mapping Dundas Dashboard objects to Dundas BI
The following table describes how Dundas Dashboard objects are mapped to Dundas BI objects during the migration process.
| Dundas Dashboard object | Dundas BI object | Comments |
|---|---|---|
| project | project | |
| folder | folder | |
| file | file | |
| data connector | data connector | |
| native structure | native structure | e.g., tables, views, functions, stored procedures, etc. |
| virtual table | data cube | |
| OLAP cube | OLAP cube | |
| virtual cube | cube perspective | |
| instant dimension | implicit hierarchy | |
| standard/full/regular dimension | implicit or explicit hierarchy | A standard dimension becomes an implicit hierarchy if it is used in any migrated KPI/Dataset, otherwise it is migrated as an explicit hierarchy. |
| time dimension | time dimension | |
| dataset | metric set | |
| KPI | metric set | |
| analytical (OLAP) report | metric set | |
| user account | user account |
Dundas Dashboard Role to Dundas BI License Seat mapping:
|
| security group | group |
6. Notes and recommendations
- It is strongly recommended that the target Dundas BI instance be a clean installation without any existing content or customizations.
- Migration is a one-time process. If you attempt to migrate an already migrated project, the migration will result in a new, separate project with new identifiers. There is no possibility of override of an existing Dundas BI project.
- Naming conflicts between existing and imported projects, accounts, and security groups are not automatically resolved. Instead, migration of any conflicting items will be skipped and a corresponding warning or note will be added to the migration report.
- Review the list of DD Migrator limitations.
7. Using DD Migrator
7.1. Folder location
The location of the DDMigrator.exe program depends on where you extracted the ZIP contents to. For example:
C:\Program Files\Dundas Data Visualization Inc\Dundas BI\Instances\Instance1\tools\DDMigrator
7.2. Command line usage
Open a Command Prompt window and type the following to see the command line usage for DD Migrator:
DDMigrator help
You'll see usage information as shown below:
Dundas Dashboard Migrator version 2.6.0.0
Copyright (c) 2016 Dundas Data Visualization Inc. All rights reserved.
Commands:
DDMigrator help Displays the current help.
DDMigrator migrate Migrates eligible data from Dundas Dashboard data store into Dundas BI application database.
Migration details are stored in generated report file.
Syntax:
DDMigrator migrate /ddcs:"<Dundas Dashboard data store connection string>"
/bics:"<Dundas BI application database connection string>"
[/ps:"<Dundas Dashboard project IDs selected for migration (comma-separated)>"]
<Dundas Dashboard data store connection string>
- The Dundas Dashboard data store connection string. The argument is mandatory.
<Dundas BI application database connection string>
- The Dundas BI application database connection string. The argument is mandatory.
<Dundas Dashboard project IDs selected for migration (comma-separated)>
- The Dundas Dashboard project IDs selected for migration (comma-separated). The argument is optional.
If not provided, all projects will be migrated.
Example:
DDMigrator migrate /ddcs:"Data Source=localhost; Initial Catalog=Dundas Dashboard DataStore; Integrated Security=True" /bics:"Data Source=localhost; Initial Catalog=Dundas BI application database; Integrated Security=True" /ps:"2f621e61-017d-4113-b4a9-ad8f4d2c3d93, bb465851-91f4-4aac-8c7c-97752c7334ff"
7.3. Connection strings
The connection string for your Dundas Dashboard instance can be found in the Dundas.Dashboard.config file which is located in the following folder by default. Edit the file in Notepad and locate the AppDatabaseConnectionString key.
C:\Program Files\Dundas Data Visualization Inc\Dundas Dashboard\Instance1\www
The connection string for your Dundas BI instance can be found in the dundasBIConnection.config file which is located in the following folder by default.
C:\Program Files\Dundas Data Visualization Inc\Dundas BI\Instances\Instance1\www\BIWebsite\App_Data
7.4. Dundas Dashboard project IDs
To get the ID of a project you want to migrate, log in to Dundas Dashboard, click Administration, expand the Projects folder, and then view the Properties for the project you want. Copy the Object ID value and paste into Notepad for later use.
7.5. Performing an example migration
Below is an example showing the contents of the command prompt window during a migration of the Dundas Dashboard sample project, Sonatica Performance.
C:\Program Files\Dundas Data Visualization Inc\Dundas BI\Instances\Instance1\tools\DDMigrator> DDMigrator.exe migrate /ddcs:"Data Source=SERVER1; Initial Catalog=Dundas Dashboard Instance1 DataStore; Integrated Security=True" /bics:"Data Source=SERVER1\;Initial Catalog=Dundas BI Instance1;Integrated Security=True" /ps:"2f621e61-017d-4113-b4a9-ad8f4d2c3d93" Migration started. User Accounts migration started. User Accounts migration finished with 0 error(s), 0 warning(s) and 0 note(s). Security Groups migration started. Security Groups migration finished with 0 error(s), 0 warning(s) and 0 note(s). 'Sonatica Performance' project migration started. 'Sonatica Performance' project migration finished with 0 error(s), 0 warning(s) and 41 note(s). Shared Resources migration started. Shared Resources migration finished with 0 error(s), 0 warning(s) and 0 note(s). Migration finished with 0 error(s), 0 warning(s) and 41 note(s). 1 project(s) migrated. Report file: C:\Program Files\Dundas Data Visualization Inc\Dundas BI\Instances\Instance1\tools\DDMigrator\DDMigrator report 20150227_111441.txt
7.6. Review the DD Migrator report
After the migration is complete, the tool generates a time-stamped report which you can review for errors, warnings, or notes.
DD Migrator is error-tolerant, and does not stop or exit when exceptions occur during migration. Instead, any exceptions are logged in the report as Errors. If an Error appears in the migration report, this could mean that the original object it is associated with is broken, but it could also mean that an unforeseen exception has occurred. Errors need to be investigated by Dundas.
Important migration problems and errors other than exceptions are logged as Warnings. Usually a warning explains the related situation. Sometimes the warning can be fixed in the original datastore and migration can be run again. But sometimes it cannot be fixed, although there is the possibility it can be worked around in the target Dundas BI project.
Less important migration problems are logged as Notes. As in the case of warnings, some notes may be fixable while others cannot be fixed.
7.7. Return codes
The DDMigrator command-line tool returns 1 in the following cases:
- No arguments were provided.
- Invalid number of arguments were provided.
- An exception occurred during execution.
Otherwise, the tool returns 0.
7.8. Set security privileges on migrated objects
You may want your migrated objects to be accessible to specific users and/or groups. In this case it is necessary to review and manually adjust the security privileges on each migrated object as desired.
Log on to Dundas BI as an administrator and click Projects under Projects & File System. Locate your migrated project (e.g., Sonatica Performance) in the list and edit its properties. Scroll down and click Security. Adjust the security privileges as desired.
Next, go to the admin File Explorer and expand your migrated project in the treeview. For each migrated object (e.g., a data connector or migrated KPI) right-click on it and open its properties. Scroll down and click Security to adjust its security privileges. For example, add the Everyone group and allow the Execute privilege. Note that the Inherit Privileges option is unchecked by default for migrated objects.
7.9. Check the migration in Dundas BI
Go to the Dundas BI main menu, click Projects, and then select the migrated project (e.g., Sonatica Performance) as the active project.
Create a new dashboard, go to the Explore window, and expand folders such as Data Connectors, Data Cubes, and Metric Sets to verify the migrated objects.
Drag one of the migrated KPIs (which will be a metric set) onto the dashboard canvas.
8. DD Migrator Limitations
DD Migrator has certain limitations because there is not a one-to-one match between objects in Dundas Dashboard and Dundas BI. Below is a detailed list of these limitations and other notes:
- For resources (shared or project) in Dundas Dashboard, only the images are migrated.
- Certain objects cannot be converted as is. For example, some data sources in Other (flat file) Data Connectors are migrated into a single Dundas BI data connector, while others need to migrate into a separate Dundas BI data connector for each.
- Fixed length columns data source in Other Data Connectors is not supported in Dundas BI and cannot be migrated.
- Custom plugin data connectors cannot be migrated.
- Migration of analytical objects requires live connection to the analytical data source used in corresponding analytical data connector (that is, the databases and cubes used in Dundas Dashboard must be online during the migration).
- Manual virtual tables based on flat files cannot be migrated because manual data cubes based on flat files are not supported in Dundas BI.
- Virtual tables based on another virtual table(s) migration is not supported.
- Stubbed KPI/dataset migration is not supported.
- Analytical virtual cube dimension filters migration is not supported. For a Dundas BI cube perspective, all dimensions will be selected.
- Virtual table columns empty/not set aggregator is not supported. Default supported aggregator is used instead.
- External filters on full dimensions are not supported. KPI/dataset column filter is not migrated.
- Metric sorting over multiple row hierarchies is not supported in Dundas BI. KPI/dataset column sorting rule is not migrated.
- Metric sorting with no row hierarchies is not supported. KPI/dataset column sorting rule is not migrated.
- Certain features of various migrated objects are not migrated:
- Functions in OLAP reports
- State groups in KPIs and datasets
- Not all system tokens have a match in Dundas BI, and not all can be migrated. Custom tokens are not migrated as well.
- If a base object is not migrated for any reason, the subsequent objects will not migrate either. For example, if a data connector is not migrated, all of the dependent objects such as virtual tables, dimension, KPIs, and datasets will not migrate.
- Migration of programmatic virtual tables from Dundas Dashboard to Dundas BI requires a live connection to the data source used in the corresponding data connector.
- In Dundas BI, SQL Server is the only data provider that supports datetime granularity functions such as DateTrim:Day, DateTrim:Month, etc. But in Dundas Dashboard, other providers (for example, flat files) also support these functions. Therefore, granularity functions from virtual tables based on providers other than SQL Server cannot be migrated.
- You may see differences in data results (numeric values) between Dundas Dashboard and Dundas BI where average calculations are involved. Dundas BI may use a combination of SQL and in-memory operations to do the calculations, which leads to the differences. To account for this, you may need to do further preparation in Dundas BI at the data cube stage (such as creating a count measure that can be used to calculate 'true' average).