INSTALLATION GUIDE BIOVIA INSIGHT 2019 Copyright Notice
©2018 Dassault Systèmes. All rights reserved. 3DEXPERIENCE, the Compass icon and the 3DS logo, CATIA, SOLIDWORKS, ENOVIA, DELMIA, SIMULIA, GEOVIA, EXALEAD, 3DVIA, 3DSWYM, BIOVIA, NETVIBES, IFWE and 3DEXCITE, are commercial trademarks or registered trademarks of Dassault Systèmes, a French "société européenne" (Versailles Commercial Register # B 322 306 440), or its subsidiaries in the U.S. and/or other countries. All other trademarks are owned by their respective owners. Use of any Dassault Systèmes or its subsidiaries trademarks is subject to their express written approval.
Acknowledgments and References
To print photographs or files of computational results (figures and/or data) obtained by using Dassault Systèmes software, acknowledge the source in an appropriate format. For example: "Computational results were obtained by using Dassault Systèmes BIOVIA software programs. BIOVIA Insight was used to perform the calculations and to generate the graphical results."
Dassault Systèmes may grant permission to republish or reprint its copyrighted materials. Requests should be submitted to Dassault Systèmes Customer Support, either by visiting https://www.3ds.com/support/ and clicking Call us or Submit a request, or by writing to:
Dassault Systèmes Customer Support 10, Rue Marcel Dassault 78140 Vélizy-Villacoublay FRANCE Contents
Chapter 1: Introduction 1 Documentation 1 Additional Information 1 Chapter 2: New Installation 2 General Requirements 2 Installation Steps 2 Installing BIOVIA Pipeline Pilot 2 Installing and Configuring BIOVIA Foundation Hub 2 Installing BIOVIA Insight 3 Configuring BIOVIA Foundation Hub Permissions 4 Installing MongoDB 4 Configuring Data Sources (IDS) for Query Service 4 Migrating Custom Authentication Data 5 Chapter 3: Migrating Data 6 Prerequisites for Migrating Data 6 Introduction to Data Migration 6 Admin Configuration Required Before Using Insight 7 Migrating in Place 7 Migrating from a Remote Database 7 Verifying the Data Migration 7 Chapter 4: Upgrading BIOVIA Insight 8 Upgrade Steps 8 Upgrading Pipeline Pilot 8 Installing and Configuring BIOVIA Foundation Hub 9 Upgrading BIOVIA Insight 9 Chapter 5: Configuring Your Databases for Backup and Recovery 10 Chapter 6: Final Validation 11 Searching 11 Developing Plugins 12 Chapter 7: Internationalization 13 Configuring Fonts 13
BIOVIA Insight • Installation Guide | Page i
Chapter 1: Introduction BIOVIA Insight allows scientists to query or browse their database, visualize the results and refine and share them as needed, and makes data available to other applications. This guide provides information on the installation of Insight.
Documentation The following documents are supplied with Insight: Insight Installation Guide Insight System Requirements Other useful guides that administrators can refer to are included with Pipeline Pilot: BIOVIA Pipeline Pilot Server Installation Guide BIOVIA Pipeline Pilot Client Installation Guide BIOVIA Pipeline Pilot Admin Portal Guide BIOVIA Foundation Hub Installation and Configuration Guide BIOVIA Query Service Administration Guide IMPORTANT!
Note: While this product contains features to facilitate GDPR compliance, you, the Customer, are solely responsible and liable for the access to and the use of this product. Therefore, it is your responsibility to ensure that the deployment is GDPR compliant, including provision of a suitable Data Privacy Policy.
Additional Information For additional information about BIOVIA Insight and other Dassault Systèmes applications, visit the Dassault Systèmes Support site: https://www.3ds.com/support/
Introduction | Page 1 Chapter 2: New Installation
General Requirements BIOVIA recommends using several servers within local network proximity for Insight: 1. A BIOVIA Pipeline Pilot 2019 server with the Insight 2019 application package installed 2. An Oracle Database server 3. A MongoDB server 4. (Optional) A BIOVIA machine for developing protocols or widgets. This development machine must be configured to connect to the Pipeline Pilot server if it is not on the same machine as Pipeline Pilot server.
Installation Steps Perform the following steps to install Insight: 1. Installing BIOVIA Pipeline Pilot 2. Installing and Configuring BIOVIA Foundation Hub 3. Installing BIOVIA Insight Application 4. Installing MongoDB 5. Configuring Data Sources (IDS) for Query Service 6. Migrating Custom Authentication Data 7. Migrating Data 8. Performing a Final Validation Note: If you are upgrading from a previous version of Insight, refer to the Upgrading to Insight 2019 section for more information.
Installing BIOVIA Pipeline Pilot To install Pipeline Pilot 2019, see the Pipeline Pilot Server Installation Guide. For a production install, see the Pipeline Pilot 2019 Installation and Configuration Guide. The Pipeline Pilot 2019 documentation is available with the Pipeline Pilot installation artifacts.
Installing and Configuring BIOVIA Foundation Hub Insight must be used with BIOVIA Foundation Hub. Foundation Hub enables interoperability between different BIOVIA applications, common resource management, and single-sign on. If you are installing Insight for the first time, install Foundation Hub before Insight. To install and configure BIOVIA Foundation Hub, see the BIOVIA Foundation Hub Installation and Configuration Guide.
Page 2 | BIOVIA Insight • Installation Guide At the end of the configuration process: The BIOVIA Foundation Hub server should be running as a service. The BIOVIA Foundation Hub should be connected to an Oracle database to store its data. The BIOVIA Foundation Hub should be connected to your Pipeline Pilot server for authentication. Your Pipeline Pilot server should have a Foundation Hub connection configured in the Pipeline Pilot Admin Portal.
Installing BIOVIA Insight Install the Insight 2019 application package. 1. Obtain the following: Documentation: Insight_2019_Documentation.zip Windows: Insight2019_Win64.zip Linux: Insight2019_Linux64.tgz 2. Extract the installation archive for your operating system: Windows: Insight2019_Win64.zip Linux: Insight2019_Linux64.tgz tar -xpvzf Insight2019_Linux64.tgz 3. Run the application installer: Windows: a. Verify there are no users in Pipeline Pilot 2019, and that there are no jobs running. b. In the bin folder of the unzipped directory, rght-click scitegicsetup.exe and choose Run As Administrator. c. Verify that the installer has located the installation of BIOVIA Pipeline Pilot 2019. d. Click Add/Remove Products. e. If the Confirm Your License screen does not display the message 'The existing license file is valid', browse to your license file. Click Next. f. In the 'Select product(s) to install' screen, ensure that Insight is checked. Click Next. g. Stop the Pipeline Pilot services if they are running. h. In the next screen, verify the HTTP and HTTPS ports are correct, and edit the ports if needed. i. Click Next to confirm the product(s) to install. The installation will proceed. j. If your Apache Web Server must be run under a named user account, enter that account in the 'Confirm Apache Login' screen. Alternatively, you can change it later, after the installation has finished. k. Click Next. You should see the message 'Completed', followed by 'The actions you have selected have been applied'. Optionally, you can open the BIOVIA Pipeline Pilot Server 2019 Home Page. Click Finish. Linux: a. Run the installer in the bin extracted folder as a non-root user by running sciinstall. b. When a message informs you that the operating system is supported, enter y to continue. c. At the prompt "Enter the target directory for the server installation", enter the directory where your Pipeline Pilot server is installed. This is the
New Installation | Page 3 d. Confirm the path for your Pipeline Pilot server installation. If the path is not correct, enter n, correct the path, then continue. e. You will be prompted regarding your license file. If the license file is valid, press Enter to continue. f. Verify that Insight is listed as an application to be installed, then press Enter to continue the installation. g. At the end of the installation, when prompted to start the Pipeline Pilot server service, press Enter. h. Verify that the Tomcat service started successfully and the installation has completed. 4. During installation, specify the location of your Pipeline Pilot 2019 server installation, and ensure that the Insight application is checked.
To propagate Insight-specific settings from Pipeline Pilot to the BIOVIA Foundation Hub: 1. Go to your BIOVIA Pipeline Pilot Server Home Page. 2. Under the Administrators section, go to the Admin Portal. 3. Under Admin Pages, go to Reports > Foundation Applications. 4. Under Registered Applications, click Update Applications.
Configuring BIOVIA Foundation Hub Permissions The user who runs the Insight data migration wizard must be a member of the following groups: Insight/Administrators List Management/Administrators Platform/Administrators Foundation/Administrators To manage a group in the BIOVIA Foundation Hub, see Administering users, external claims, groups, and permissions in the BIOVIA Foundation Hub Admin Guide.
Installing MongoDB To install MongoDB and configure Pipeline Pilot to use MongoDB, follow the Pipeline Pilot Help Center instructions: 1. Go to http://
Configuring Data Sources (IDS) for Query Service To customize the Query Service IDS, see Configuring Query Service data sources in the BIOVIA Query Service Administration Guide.
Page 4 | BIOVIA Insight • Installation Guide Migrating Custom Authentication Data After you have installed Insight 2019, any custom authentication data from previous Insight installations will not be immediately available. Once the Insight authorization groups are registered with the Foundation Hub, you can migrate any user or group assignments from your previous Pipeline Pilot instance to the Foundation Hub's authorization database. Follow the instructions under Migrating custom authentication data to Foundation Hub in the BIOVIA Foundation Hub Installation and Configuration Guide. You can use the Foundation Hub administration page to visually verify the results of the migration. Note: Unless users are auto-provisioned from LDAP or elsewhere, users need to authenticate with the Foundation Hub before any group assignments made in the Foundation Hub's administration panel are propagated to Pipeline Pilot applications like Insight. When users are manually created by administrators, they should visit the Foundation Hub landing page, http://
New Installation | Page 5 Chapter 3: Migrating Data
Prerequisites for Migrating Data The data migration process requires the target environment to be empty of Insight data. When you run the process, it clears the target environment of any existing Insight data. Because the original data in your source environment is not cleared, you can re-run the migration if needed. To prevent users from creating new data on the target environment before the data migration, your administrator must open the application for general use. The migration requires a global DefaultConnection for BIOVIA/MongoDB that you must define. This connection must be the same one used for the previous installation. If it is different, documents will not migrate correctly. For instructions on how to migrate users into Foundation Hub, see to "Migrating custom Pipeline Pilot authentication data to Foundation Hub" in the BIOVIA Pipeline Pilot Server Installation Guide. Migrate users before you migrate data. Data that belongs to users who have not been migrated to Foundation Hub will not be migrated. A list of missing users is logged when the Insight data migration completes. Refer to the BIOVIA Foundation Hub Installation and Configuration Guide for more information on upgrading from previous versions.
Introduction to Data Migration When you install or upgrade Insight 2019, an Administrator must set a flag on the database before any user can begin using Insight. Administrators opening Insight for the first time will see the following message: "Administrator Action Required - No Insight 2018 SP2 data has been detected. If this is your first time using Insight, or you have no data to wish to migrate from previous Insight installations, click 'Begin Using Insight'. You will not see this prompt again. If you would like to migrate data from a previous Insight installation, click 'Migrate'." If you do not need to migrate data, click Begin Using Insight to set the flag on the database that allows you and your users to begin entering data. If you do need to migrate data, click Migrate. You have two options: Migrating in Place Uses List Management and data sources from the previous installation on the current server. This option is disabled if no previous data is available on the current server. Migrating from Remote Database Use for installation on a new server. Input connection information for remote server. Note: Migration should complete quickly for small amounts of data. However, allow several hours or more if you are migrating hundreds or thousands of data items.
Migrating Data | Page 6 Admin Configuration Required Before Using Insight Until an admin user configures Insight 2019 for use, users see a dialog referring them to their administrator for action: "Before Insight can be used, an administrator is required to take action to configure it. If you are an administrator you can Sign Out and sign back in with an administrator account to prepare Insight for general use."
Migrating in Place Select Migrate in Place to migrate data from a previous installation on the current server to the new installation. It uses the List Management and data sources from the previous installation on the same server. 1. In the Insight 2019 Configuration Wizard, click Migrate in Place. 2. Click Next. When the migration completes, a log opens that lists any errors that occurred followed by a list of the successfully migrated data items. 3. Click Finish.
Migrating from a Remote Database Select Migrate from a Remote Database to import Data from an external server source. 1. Fill in the connection details in the Insight Database Connection Information form. 2. Click Migrate. When the migration completes, a log opens with a list of any errors that occurred followed by the successfully migrated data items. 3. Click Finish.
Verifying the Data Migration To verify if the data migration was successful, you can view the log that displays after the migration completes. This log is also available in
Page 7 | BIOVIA Insight • Installation Guide Chapter 4: Upgrading BIOVIA Insight Specific upgrade instructions are included in each of the installation steps described in this installation guide. BIOVIA strongly recommends that you read the entire installation guide before you start the upgrade process.
Upgrade Steps Perform the following steps to upgrade Insight you: 1. Upgrading Pipeline Pilot 2. Installing and Configuring BIOVIA Foundation Hub 3. Upgrading to Insight 2019 4. Post-upgrade
WARNING! BIOVIA recommends that you back up your saved documents, forms, and templates before you upgrade to Insight 2019. A backup protects your data in case you encounter problems. Back up both the project database stored in Oracle and the document data stored in MongoDB. See Configuring Your Databases for Backup and Recovery for more information on backing up your data.
Upgrading Pipeline Pilot Before you upgrade to Insight 2019, you must install Pipeline Pilot 2019. Your options for upgrading Pipeline Pilot are: Replace the old Pipeline Pilot server installation with the new installation. Automatically upgrade all protocols and pick up all server settings. Install Pipeline Pilot 2019 on the same computer as the old installation, but to a new disk location. This is called a side-by-side installation. Automatically copy protocols from the old location to the new location by the installer. Manually migrate server settings, data sources, users and groups using Pipeline Pilot Admin Portal tools. Install Pipeline Pilot 2019 to a different computer. Manually migrate all protocols and server settings from the existing Insight installation. Run scitegicsetup.exe on the computer where you want to install Pipeline Pilot 2019. Choose the appropriate installer option when prompted. IMPORTANT! If you replace an existing installation, all applications are uninstalled as part of the Pipeline Pilot installation process. The Pipeline Pilot installer displays a warning before it uninstalls applications. Your data and settings will not be affected, but these applications must be reinstalled using the appropriate standalone installers.
Upgrading BIOVIA Insight | Page 8 Installing and Configuring BIOVIA Foundation Hub Upgrade Pipeline Pilot following the BIOVIA Pipeline Pilot Server Installation Guide, then upgrade Foundation Hub following the BIOVIA Foundation Hub Installation and Configuration Guide.
Upgrading BIOVIA Insight Follow the upgrade instructions for one of the following situations: If you are upgrading from Insight 2017 R2 or later No data migration is needed. Follow the instructions under Installing BIOVIA Insight. If you are upgrading from Insight 2016 or 2017 You must first upgrade to 2017 R2, and then upgrade to 2019. When upgrading from 2016 to 2017 R2, you should perform a data migration. See Migrating Data for more information. When upgrading from 2017 R2 to 2019, no data migration is needed. Follow the instructions under Installing BIOVIA Insight.
Page 9 | BIOVIA Insight • Installation Guide Chapter 5: Configuring Your Databases for Backup and Recovery The backup and restoration documentation referenced here provides instructions for creating a complete, consistent copy of the data that you can use to bring a new or replacement database instance online. Logical backups created by exporting database objects such as tables and tablespaces are a useful supplement to physical backups, but cannot protect your entire database. An effective backup strategy must be based on physical backups. Oracle: This applies to Insight 2016 or earlier. See Performing Backup and Recovery, which describes backup and recovery methods that use Oracle Enterprise Manager Database Control. They describe how to implement a disk-based backup strategy and how to perform simple repairs to database files. MongoDB: See Backup and Restoration Strategies., which describes two ways to back up your MongoDB project data: 1. Use system-level tools, such as disk image snapshots. 2. Use various features in the mongodump tool.
Configuring Your Databases for Backup and Recovery | Page 10 Chapter 6: Final Validation
Searching To validate the installation (or upgrade) of your Insight database, run a search, transfer the results to Insight, and save the document. IMPORTANT! If you do not have data sources configured, do one of the following and then return to this validation step: Use the Query Service to configure the data sources you require. Install a BIOVIA product that automatically configures Insight data sources. Examples include Biological Registration and Chemical Registration. 1. Go to http://
The Search link name changes from Search: Unsaved Form* to Search: Ad Hoc Search, as shown in the next step. 4. The Fields panel at the left of the workspace displays all properties you can use in an Ad Hoc search for each selected root category of the data source that is defined. In the Fields panel, click Substance Registry Number. A form item associated with that field property appears at the right:
5. Set up the form item to perform the query Substance Registry Number < 500. 6. Click Search to run the query. 7. Click Visualize Data.
Final Validation | Page 11 8. In the Transfer Data to Insight dialog, leave Table Data selected and click OK. 9. Click Save > Save As..., enter a name for the document to save in the Save Document dialog, and click Save. This step checks the Project database. 10. Return to the Home page. 11. In the All Documents and Projects section of the Load Existing area, click your saved document to display it.
Developing Plugins Users in the Insight/PluginAuthors group can access the templates for plugin development from the Pipeline Pilot client. For more information, see the BIOVIA Insight Getting Started with Insight Plugins Guide.
Page 12 | BIOVIA Insight • Installation Guide Chapter 7: Internationalization
Configuring Fonts Note: The following information is relevant only for installations where the use of non-Latin characters is common. Insight property names and data may not be rendered properly in PDF or Excel documents or when generating charts unless a Unicode font containing all of the characters used in the data is available on the Pipeline Pilot server. When such a font is missing, non-Latin characters may not be rendered. The simplest way to ensure that an appropriate font is available is to install Microsoft Office on the Pipeline Pilot server. This includes the Arial Unicode font, which has representations of characters in most commonly used languages. If you cannot install Microsoft Office, you must configure a default Unicode font to enable these types of documents to be generated correctly. To do this, you configure a server file, Fonts.xml. IMPORTANT!
Internationalization | Page 13 3. For each font style, edit the value to use the location of the appropriate Unicode font file available on this Pipeline Pilot server, for example:
Page 14 | BIOVIA Insight • Installation Guide