TIBCO Spotfire Server Migration. Migration Manual

TIBCO Spotfire Server Migration Migration Manual Revision date: 26 October 2012

Important Information SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE. USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN LICENSE_TIBCOSPOTFIRESERVER.PDF) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE "LICENSE" FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME. This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc. TIBCO and Spotfire are either registered trademarks or trademarks of TIBCO Software Inc. and/or subsidiaries of TIBCO Software Inc. in the United States and/or other countries. All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only. This software may be available on multiple operating systems. However, not all operating system platforms for a specific software version are released at the same time. Please see the readme.txt file for the availability of this software version on a specific operating system platform. THIS DOCUMENT IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME. Copyright 1996-2012 TIBCO Software Inc. ALL RIGHTS RESERVED. THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES. TIBCO Spotfire is covered by U.S. Patent No. 6,014,661 and U.S. Patent No. 7, 216,116. Other patent(s) pending. TIBCO Software Inc. Confidential Information

Contents 1 Overview 4 2 Prerequisites 6 3 Prepare the Database Tables 7 3.1 Overview 7 3.2 Oracle 7 3.3 Microsoft SQL Server 9 4 Install the Migration Tool 13 5 Set Up the Database Connection File 14 6 Run the Migration Tool 15 6.1 Command Line Usage 16 6.2 Database Drivers 17 7 Upgrade the Database Tables 18 8 Import Library and Information Model 19 9 Log Files 20 10 Configuration Not Migrated 21 11 Reseting Database Tables 22

Overview 1 Overview If you are upgrading TIBCO Spotfire Server from version 3.0 or later to the latest version you can use the Spotfire Server Upgrade tool to upgrade the Spotfire database tables. However, if you have been running TIBCO Spotfire Analytics Server 10.1, this is not possible. Instead, you must migrate the information in the 10.1 database tables and 10.1 installation directory to new and empty 3.3 database tables and then upgrade these to the latest version. This manual will describe how to set up 3.3 database tables and migrate information from 10.1 database tables to them. This information includes users, groups, licenses, preferences, library content, and the information model. Users, groups, licenses, and preferences will be inserted directly into the 3.3 database. When you have done this, you can use the Upgrade tool to upgrade the database tables to the latest version. See the TIBCO Spotfire Server Installation and Configuration Manual for instructions on how to use the Upgrade tool. Library content and the information model will be exported to files that can later be imported into the library using the import function in the Library Administration tool in the latest version of TIBCO Spotfire. Note: The 10.1 library allowed for case sensitive item names if it was stored in an Oracle database. This meant that you could have two folders, one named folder and another named Folder on the same level of the library file tree. Version 3.0 and later treats Library item names as case insensitive, regardless of whether the library is stored in an Oracle or a Microsoft SQL Server database. Therefore, when you import a 10.1 library that was stored in an Oracle database, you must select to automatically change any such conflicting names by checking the option Automatically assign new name or GUID to imported item in the import dialog. The Migration tool is intended for migrating away from 10.1. Do not attempt to use it to keep different systems synchronized. This is an outline of the steps required to migrate from 10.1 For detailed instructions about each step, see the respective chapters in this manual: 1 Prepare Spotfire 3.3 database tables. 2 Install the Migration tool on the 10.1 server. 3 Run the Migration tool and perform the migration. 4 Install the latest version of the TIBCO Spotfire Server and run the Upgrade tool distributed with TIBCO Spotfire Server to upgrade the database tables. 5 Install TIBCO Spotfire and use the Import function in the Library administration tool to import library content and the information model from the 10.1 server. Test Run A test run of the Migration tool will perform all the migration steps, including exporting the library and the information model, except actually writing to the 3.3 database tables. It will however attempt to connect and log in to the 3.3 database. This can be useful in order to verify that your environment is set up properly. It is recommended that you perform a test run before you write to the 3.3 database tables. 4(22) TIBCO Spotfire Server Migration

Overview Full Migration vs. Partial Migration A full migration will insert users, groups, licenses, and preferences into the 3.3 database tables and export the library content and the information model to files that can later be imported to the 3.3 database. A partial migration will only export library content and the information model to files. It will not attempt to connect to the 3.3 database tables. TIBCO Spotfire Server Migration 5(22)

Prerequisites 2 Prerequisites In order to follow the instructions in this manual, you need a functional Spotfire Analytics Server 10.1. Stop the Spotfire Analytics Server 10.1 before proceding. You will create new database tables, so you will need access to a database server and permission to create database tables. The Migration tool needs access to the Spotfire Analytics Server 10.1 installation directory. It also needs access to both the 10.1 and the database tables you will create. It is recommended that you install the Migration tool on the 10.1 server, and make sure that the new database tables can be accessed from here. 6(22) TIBCO Spotfire Server Migration

3 Prepare the Database Tables 3.1 Overview Prepare the Database Tables Before you can run the Migration Tool, you must set up 3.3 database tables. This is done by running a number of scripts distributed with the Migration tool. However, these must first be modified to suit your system. You can use either an Oracle database server or a Microsoft SQL Server to hold your Spotfire Server Database. Depending on your choice, please continue to either: 3.2 Oracle Oracle on page 7 Microsoft SQL Server on page 9. 3.2.1 Prerequisites In order for the scripts to work, and for the Spotfire Server to be able to communicate with the databases once installed, the following settings must be configured on the Oracle Server: The Oracle Server must be configured to use username and password authentication. National Language Support (NLS) must be set to match the language in which you will store data (affects search). If the database server NLS cannot be set to match the language in which you will store data, Oracle provides other methods of setting NLS to a specific database or user, such as per session. Refer to the Oracle database documentation for more information. 3.2.2 Copy the Scripts to the Database Server 1 On the TIBCO Spotfire Server Migration Tool installation media, find the scripts directory: scripts/oracle_install 2 Copy the entire directory to your database server. Comment: The command-line database tools (sqlplus, sqlload, etc.) must be in the system path of the database server. TIBCO Spotfire Server Migration 7(22)

Prepare the Database Tables 3.2.3 Modify the create_databases Script In the folder you just copied, you will find a file called create_databases.bat (Windows) or create_databases.sh (Solaris/Red Hat Enterprise Linux/SUSE Linux Enterprise). 1 Open this file in a text editor. 2 Find the rows: set ROOTFOLDER=<ROOTFOLDER> set CONNECTIDENTIFIER=<SID> set ADMINNAME=system set ADMINPASSWORD=<ORACLEDB_PASSWORD> set SERVERDB_USER=<SERVERDB_USER> set SERVERDB_PASSWORD=<SERVERDB_PASSWORD> set SERVER_DATA_TABLESPACE=SPOTFIRE_DATA_33 set SERVER_TEMP_TABLESPACE=SPOTFIRE_TEMP_33 3 Specify the following variables. ROOTFOLDER. This is where the tablespaces will be created, thus it must be a directory that is writable for the Oracle instance, usually <oracle install dir>/ oradata/<sid>. CONNECTIDENTIFIER. This is the Oracle TNS name of the database. ADMINNAME. This is the name of a user with admin privileges on the database. If not set, the default system account. ADMINPASSWORD. This is the password of the above user. SERVERDB_USER. This is the user that will be created and used to set up the Spotfire database. SERVERDB_PASSWORD. This is the password of the above user. SERVER_DATA_TABLESPACE. This is the name of the tablespace that will be created. The default value should work for most systems. SERVER_TEMP_TABLESPACE. This is the name of the temporary tablespace that will be created. The default value should work for most systems. 4 Save the file and exit the editor. Note: If you are creating the Spotfire tablespaces on a database server that is already hosting Analytics Server 10.1 or Spotfire Server 3.0, 3.1, or 3.2 tablespaces, ensure that you do not select any names for the 3.3 databases and users that conflict with the 10.1 or 3.x tablespaces and users. 8(22) TIBCO Spotfire Server Migration

Prepare the Database Tables 3.2.4 Run the create_databases.bat/.sh Script Once the scripts have been properly set up, run the create_databases.bat (or create_databases.sh) script. Running this script will execute all of the other SQL scripts in the folder. 1 Open a command prompt window. 2 Navigate to the directory where you placed the scripts. 3 Type create_databases.bat and press Enter. Response: The scripts now set up the Spotfire Server 3.3 database. Note that this may take some time. A log file called log.txt will be created in the same directory as the create_databases file. Please examine this file to verify that no errors occurred. 3.3 Microsoft SQL Server 3.3.1 Prerequisites In order for the scripts to work the following settings must be configured on the Microsoft SQL Server: TCP/IP communication must be enabled. A TCP/IP listener port must be configured (The default is 1433). A case insensitive collation must be used (at least for the Spotfire database). Collation must match the language in which you will store data (affects search). 3.3.2 Copy the Scripts to the Database Server 1 On the installation media, find the scripts directory: scripts/mssql_install 2 Copy this entire directory to a temporary place on the local disk of your intended database server. Comment: The command-line database tools (sqlcmd, etc.) must be in the system path of the database server. 3.3.3 Modify the create_databases.bat Script In the folder you just copied you will find two files called create_databases.bat and create_databases_ia.bat. If you are using Windows Integrated Authentication (ia) on your Microsoft SQL Server, use the latter. Otherwise, use the former. TIBCO Spotfire Server Migration 9(22)

Prepare the Database Tables Note: If you are using Windows Integrated Authentication, the create_server_user_ia.sql script will create a database user (SERVERDB_USER) for the server database (SERVERDB_NAME). The database user is then tied to the SQL Server login named WINDOWS_LOGIN_ACCOUNT. 1 Open this file in a text editor. 2 Find the rows: set CONNECTIDENTIFIER=<SERVER>\<MSSQL_INSTANCENAME> set ADMINNAME=sa set ADMINPASSWORD=<MSSQL_SAPASSWD> set SERVERDB_NAME=spotfire_server33 set SERVERDB_USER=<SERVERDB_USER> set SERVERDB_PASSWORD=<SERVERDB_PASSWORD> set WINDOWS_LOGIN_ACCOUNT=<WINDOWS_LOGIN_ACCOUNT> 3 Specify the following variables. CONNECTIDENTIFIER. Set this by replacing <SERVER> with the name of the server running the SQL Server instance, and replacing <MSSQL_INSTANCENAME> with the name of the SQL Server instance. ADMINNAME. This is the name of a user with admin privileges on the database, most often sa. This is not used if you are using Windows Integrated Authentication. ADMINPASSWORD. This is the password of the above user. This is not used if you are using Windows Integrated Authentication. SERVERDB_NAME. This is the name of the database that will be created. SERVERDB_USER. This is the user that you wish to create and use for this database. SERVERDB_PASSWORD. This is the password for the above user. This is not used if you are using Windows Integrated Authentication. WINDOWS_LOGIN_ACCOUNT. This is the Windows Login Account that is used to authenticate with the database server. This is not used if you are using database authentication. Note: When using Windows Integrated Login, the create_server_user_ia.sql script will create a database user with the name specified in the WINDOWS_LOGIN_ACCOUNT. By default, it is assumed that a Windows login with this name already exists. If it does not and you wish to create such a login, open the script in a text editor and uncomment the section that reads /* use master GO CREATE LOGIN [$(WINDOWS_LOGIN_ACCOUNT)] FROM WINDOWS WITH DEFAULT_DATABASE=[$(SERVERDB_NAME)], DEFAULT_LANGUAGE=[us_english] GO ALTER LOGIN [$(WINDOWS_LOGIN_ACCOUNT)] ENABLE GO 10(22) TIBCO Spotfire Server Migration

Prepare the Database Tables DENY VIEW ANY DATABASE TO [$(WINDOWS_LOGIN_ACCOUNT)] */ 4 Save the file and exit the editor. Case Sensitive Collation If your database server is set to use a case sensitive collation by default, you must also specify that the Spotfire database be case insensitive. To do this, edit the SQL script create_server_db.sql: 1 Open this file in a text editor. 2 Find the commented out line --create database $(SERVERDB_NAME) collate Latin1_General_CI_AS; 3 Remove the leading --. Set the collation to the collation of your preference, and make sure it is case insensitive (CI), for example Latin1_General_CI_AS. (Refer to the Microsoft SQL Server documentation for more information about available collations). 4 Comment out the line below it by inserting leading -- : create database $(SERVERDB_NAME) 5 Save the file and exit the editor. 3.3.4 Run the create_databases Script Once the scripts have been properly set up, run the create_databases.bat or create_databases_ia.bat script. Running this script will execute all of the other sql scripts in the folder. 1 Open a command prompt window. 2 Navigate to the directory where you placed the scripts. 3 Type create_databases.bat or create_databases_ia.bat and press Enter. Response: The scripts now set up the Spotfire Server 3.3 database tables. Note that this may take some time. A number of log files will be created in the same directory as the create_databases file. Please examine these files to verify that no errors occurred. TIBCO Spotfire Server Migration 11(22)

Install the Migration Tool 4 Install the Migration Tool You must install the migration tool on the Spotfire Analytics Server 10.1, as it requires file system access to the 10.1 installation folder. To install the migration tool: 1 Copy the migration folder of the Spotfire Server distribution, and place it on the Spotfire Analytics Server 10.1. 2 Run the install.exe (or install.bin) found in this folder. 3 Proceed through the steps of the installer wizard. When prompted for a destination folder, specify a folder in which to install the migration tool. Click Finish when the installer finishes. TIBCO Spotfire Server Migration 13(22)

Set Up the Database Connection File 5 Set Up the Database Connection File In order for the migration tool to be able to communicate with the 3.3 database tables, you need to provide it with an xml file that contains connection information. Installed with the migration tool are two xml files, database-mssql.xml and databaseoracle.xml, located in the migration tool installation folder. Select the one matching your 3.3 database type. Copy it and rename the copy to database.xml. 1 Open database.xml in a text editor. 2 Find the line that reads <url>jdbc:tibcosoftwareinc:sqlserver://[hostname]:1433;databasename=[database-name]</ url> or <url>jdbc:tibcosoftwareinc:oracle://[hostname]:1521;sid=[sid]</url> and change it so that it matches your 3.3 database, that is enter the hostname, port and database name or sid. Note: If your database server is using Windows Integrated Authentication, make sure to use a database URL that reflects this. See the TIBCO Spotfire Server Installation and Configuration Manual for examples of database URLs. 3 Find the lines that read <username>[username]</username> <password>[password]</password> and change them to reflect the database username and password of your Spotfire database. This is the username and password referred to as SERVERDB_USER and SERVERDB_PASSWD in the TIBCO Spotfire Server Installation and Configuration Manual. Note: If your database server is using Windows Integrated Authentication, the username and password variables are not used. You can safely leave them as they are. 4 Save the file and exit the text editor. 14(22) TIBCO Spotfire Server Migration

Run the Migration Tool 6 Run the Migration Tool The migration tool is run from a command line or shell: <migration tool installation directory>migrationtool.bat or <migration tool installation directory>./migrationtool.sh When run without any options the application will start in GUI mode. Doing so, you are then presented with this window: The values prompted for are the following: 10.1 directory The installation folder of the 10.1 server, for example C:\TIBCO\tsas101 or /opt/tsas101. Output directory The directory where the configuration and library will be exported to as files. Make sure this directory is capable of storing all the library information. This could easily be several Gigabytes. Note: You must create this directory before you run the migration. Target database connection file The path to the database.xml you have prepared. TIBCO Spotfire Server Migration 15(22)

Run the Migration Tool Include passwords Type of migration Test run This option controls whether to include passwords for the data sources stored in the information model. Specifies whether to perform a full or a partial migration. A partial migration only exports the Library content and the information model to export files, while a full migration also exports the 10.1 database information and inserts it to the 3.3 database tables. If this box is checked, nothing will be written to the 3.3 database tables. It is recommended to always begin by running a test run. Note: The Library and information model will still be exported to files. When you have entered all the information above, you can perform the migration by clicking the Migrate button. The output of the migration tool will be presented in the text field below the heading Migration Log. When you have performed a migration, the Library content and the information model will be stored on disk in export files. You can then import the content of these files to your 3.3 database. See the TIBCO Spotfire Server Installation and Configuration Manual for more information about how to do this. Note: It is recommended that you perform a test run before you write to the 3.3 database tables. 6.1 Command Line Usage If you wish to run the migration tool from the command line, you can do so by entering the migration options as command line options to the.bat or.sh file. For example: C:\migration>migrationtool.bat -s C:\tsas101 -d C:\output -x C:\migration\database.xml -t or $./migrationtool.sh -s /opt/tsas101 -d /tmp/output -x /opt/migration/database.xml -t The above command will perform a test run of the migration and place the Library and information model export files in the directory C:\output\ or /tmp/output/ respectively. For a complete list of command line arguments, run the tool with the option -h: usage: migrationtool.bat (or migrationtool.sh) -d <dir> destination directory (required) -h help -n no passwords migrated 16(22) TIBCO Spotfire Server Migration

Run the Migration Tool -p partial migration (only library content and information model) -s <dir> 10.1 server base directory (required) -t test run (run migration without writing to the target database) -v version -w set up and run migration via GUI -x <file> target server configuration file (database.xml) (required) 6.2 Database Drivers The migration tool will automatically scan the 10.1 installation directory for any database drivers used to connect to the Spotfire database. If possible, these drivers will be used by the migration tool to connect to the 3.3 database. However, in some situations, this is not possible, such as when the 10.1 server uses a database driver not compatible with 3.3 (such as an old vendor database driver provided by Oracle). When this happens, the migration tool will stop with an error message saying that the database driver cannot be used. If this happens, you need to manually install a compatible database driver by acquiring them from the database server manufacturer. Place them in the directory <migration tool installation directory>/lib Any database drivers used to connect to the Spotfire database or to any information sources set up in the 10.1 server will also be reported by the migration tool in the log area or on standard output. TIBCO Spotfire Server Migration 17(22)

Upgrade the Database Tables 7 Upgrade the Database Tables When the Migration tool is finished, the next step is to install the new TIBCO Spotfire Server. When this is done, run the Upgrade tool distributed with it to upgrade the database tables to the latest version. For more information on how to do this, see the TIBCO Spotfire Server Installation and Configuration Manual 18(22) TIBCO Spotfire Server Migration

Import Library and Information Model 8 Import Library and Information Model When the new Spotfire Server is in place, you need to install a Spotfire client and import the Library content and Information Model exported from the 10.1 database tables by the Migration tool. This is performed using the Library Administration tool in TIBCO Spotfire. For more information about this, see the TIBCO Spotfire Server Installation and Configuration Manual and the TIBCO Spotfire Deployment and Administration Manual. TIBCO Spotfire Server Migration 19(22)

Log Files 9 Log Files In the migration tool installation directory, there is a folder called logs. This folder contains four different log files: debug.log sql.log warn.log migration.log Debug.log holds verbose information about exactly what happened, step by step, in the migration process. Sql.log holds information about every SQL command that was executed during the migration. Warn.log contains any warnings received during migration. Migration.log contains a summary of the migration and a list of any database drivers used by the 10.1 server that you may need to acquire anew from your database vendor. If something goes wrong during the migration, these files may contain important information about the source of the problem. You should keep these log files. 20(22) TIBCO Spotfire Server Migration

10 Configuration Not Migrated Configuration Not Migrated Single sign-on authentication and database authentication configuration from a 10.1 server is compatible with the new server. If you use any such authentication, any configuration files, such as spotfire.keytab, krb5.conf, etc., are put in a subfolder of the export folder, java-mods. You need to manually move these files to the new server(s). Refer to the TIBCO Spotfire Server Installation and Configuration Manual for details on where to put these files, or how to set up authentication again. Starting with version 3.2, TIBCO Spotfire Server supports NTLMv2. You should consider switching to "NTLM v1/v2" that supports both v1 and v2. If you wish to continue using "NTLM v1 only" you must copy the files jcifs.jar and jcifsext.jar from <old installation directory>/tomcat/webapps/spotfire/web- INF/lib to <new server installation directory>/tomcat/webapps/ spotfire/web-inf/lib. Database drivers are not migrated and need to be copied manually from a 10.1 installation or acquired anew from your database vendor. In the 10.1 installation, these drivers are located in the folder <10.1 installation directory>/server/webapps/spotfire/web-inf/lib. Copy the drivers used to <new server installation directory>/tomcat/lib Note: Do not copy any other files from the 10.1 installation directory.you can also check the log file migration.log for more information about database drivers used by the 10.1 server. TIBCO Spotfire Server Migration 21(22)

Reseting Database Tables 11 Reseting Database Tables If the migration fails for some reason and you need to perform it again, you need to restore the Spotfire 3.3 database before you can do this. Distributed with the Migration tool are scripts that will do this, located in the folder scripts/mssql_install/ utilities and scripts/oracle_install/utilities. Select the folder appropriate for your database type. In the Microsoft SQL folder, you will find the scripts restore_databases.bat and restore_databases_ia.bat. In the Oracle folder, you fill find the scripts restore_databases.bat and restore_databases.sh. Select the one appropriate for your platform and database configuration. Before you run it, you must open it in a text editor and edit a number of variables. Find the lines that contains the following text: Microsoft SQL Server set CONNECTIDENTIFIER=<SERVER>\<MSSQL_INSTANCENAME> set SERVERDB_NAME=<SERVERDB_NAME> set SERVERDB_USER=<SERVERDB_USER> set SERVERDB_PASSWORD=<SERVERDB_PASSWORD> Note: If you use Windows Integrated Authentication, the variables SERVERDB_USER and SERVERDB_USER will not be present. Oracle CONNECTIDENTIFIER=<CONNECTIDENTIFIER> SERVERDB_USER=<SERVERDB_USER> SERVERDB_PASSWORD=<SERVERDB_PASSWORD> Replace these values with the information valid for your database server. See the TIBCO Spotfire Server Installation and Configuration Manual for more information about this information. When you have entered the information required, you can run the scripts from a command prompt. 22(22) TIBCO Spotfire Server Migration