INSTALL GUIDE BIOVIA INSIGHT 2016
Copyright Notice 2015 Dassault Systèmes. All rights reserved. 3DEXPERIENCE, the Compass icon and the 3DS logo, CATIA, SOLIDWORKS, ENOVIA, DELMIA, SIMULIA, GEOVIA, EXALEAD, 3D VIA, BIOVIA and NETVIBES are commercial trademarks or registered trademarks of Dassault Systèmes 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 using BIOVIA software, acknowledge the source in an appropriate format. For example: "Computational results obtained using software programs from Dassault Systèmes BIOVIA. The ab initio calculations and graphical displays were generated with BIOVIA Insight." BIOVIA may grant permission to republish or reprint its copyrighted materials. Requests should be submitted to BIOVIA Support, either through electronic mail to biovia.support@3ds.com, or in writing to: BIOVIA Support 5005 Wateridge Vista Drive, San Diego, CA 92121 USA
Contents Chapter 1: Introduction 1 Documentation 1 Further Information 1 Chapter 2: New Installation 2 General Requirements 2 Installation Steps 2 Install BIOVIA Pipeline Pilot 3 Install and configure BIOVIA Foundation Hub 3 Should you install Foundation Hub? 3 Install Insight application 4 Oracle Database 5 Configure Oracle Database to Support Insight 5 Configure Pipeline Pilot Permissions for Insight Installer 6 Install MongoDB 7 MongoDB versions 7 Configure Data Sources (IDS) for Query Service 7 Run the Insight Project Database Configuration Wizard 7 Final Validation 9 Searching 9 Plugin Development 10 Chapter 3: Upgrading Insight 11 Upgrade Steps 11 Upgrading Pipeline Pilot 11 Install and configure BIOVIA Foundation Hub 12 Should you install Foundation Hub? 12 Upgrading the Insight application 12 Post-upgrade 13 Chapter 4: Configuring your databases for backup and recovery 14 Chapter 5: Internationalization 15 Configuring Fonts 15
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 2016 Installation Guide BIOVIA Pipeline Pilot Client Installation Guide BIOVIA Pipeline Pilot server Admin Portal online help BIOVIA Foundation Hub Deployment Guide Query Service Administration Guide Further Information For more information about Insight and other BIOVIA software products, visit BIOVIA Support on the Web: https://community.3dsbiovia.com Page 1 BIOVIA Insight Install Guide
Chapter 2: New Installation General Requirements It is recommended that you use several servers for Insight within local network proximity. 1. A BIOVIA Pipeline Pilot server 2016 server with the Insight 2016 application package installed. 2. An Oracle Database account. Insight 2016 requires a dedicated schema. 3. A MongoDB Server. 4. (Optional) A BIOVIA machine for developing protocols or widgets. This should be configured to connect to the Pipeline Pilot server and could be on the same machine. Installation Steps To install Insight you should: 1. Install BIOVIA Pipeline Pilot 2. Install and configure BIOVIA Foundation Hub 3. Install Insight 4. Install and configure Oracle 5. Install MongoDB 6. Configure Data Sources (IDS) for Query Service 7. Run the Insight Project Database Configuration Wizard 8. Perform a Final Validation Note: If you are upgrading from a previous version of Insight, refer to the Upgrading to Insight 2016 section for more information. New Installation Page 2
Install BIOVIA Pipeline Pilot To install Pipeline Pilot 2016, see the Pipeline Pilot 2016 Server Installation Guide. For a production install, see the Pipeline Pilot 2016 Deployment Guide. You can find the Pipeline Pilot 2016 documentation and installer on the BIOVIA Download Center under the Pipeline Pilot link. When running scitegicsetup.exe for a new installation, you should see: Install and configure BIOVIA Foundation Hub BIOVIA Foundation is a collection of common services that provides application users a connected experience in laboratory and scientific informatics. Foundation implements key services such as single sign-on, service location, master data, information exchange, and application interoperability. In the simplest configuration, a Foundation deployment includes BIOVIA Foundation Hub and Pipeline Pilot server. Should you install Foundation Hub? If this is a new installation of Insight, you should install and configure the Foundation Hub. To install and configure BIOVIA Foundation Hub 2016, see the BIOVIA Foundation Hub 2016 Deployment Guide. Page 3 BIOVIA Insight Install Guide
At the end of the configuration process: 1. The BIOVIA Foundation Hub server should be running as a service. 2. The BIOVIA Foundation Hub should be connected to an Oracle database to store its data. 3. The BIOVIA Foundation Hub should be connecting to your Pipeline Pilot server for authentication. 4. You Pipeline Pilot server should have a Foundation Hub connection configured in the Pipeline Pilot Administration Portal. You can find the Foundation Hub documentation and installer on the BIOVIA Download Center under the Pipeline Pilot link. Install Insight application Install the Insight 2016 application package. 1. Log into the BIOVIA Download Center and locate the BIOVIA Insight 2016 release. 2. Download the documentation and the appropriate installer for your operating system. Documentation: Insight_2016_Documentation.zip Windows: Insight2016_Win64.zip Linux: Insight2016_Linux64.tgz 3. Run the application installer. Windows: Run scitegicsetup.exe in the bin folder of the unzipped directory. Linux: Extract the.tgz file to a staging directory, then run sciinstall as a non-root user. 4. During installation, specify the location of your Pipeline Pilot 2016 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 Administration Portal. 3. Under Admin Pages, go to Security folder > Hub Connection. 4. Under Registered Applications, click Refresh to update the list applications. New Installation Page 4
Oracle Database Insight requires an Oracle database (with at least the default options). Access to the Oracle database can be configured for multiple users. Thus, there can be a choice among the various users when configuring a specific connection, including the user <insight> in the procedures that follow. Each user owns all schema elements for the Insight database. It is created during installation before installing any example data, and the following privileges must be granted: Roles System privileges connect, resource unlimited tablespace The Insight databases will grow as new data is added. Because the size of data for individual entries may vary, it is not possible to determine how much storage will be needed upfront. Each user must have sufficient quota on their tablespaces to support application use. It is recommended that unlimited tablespace privilege is given until actual usage can be estimated for your data. If unlimited tablespace is not an option, it is recommended to set the limit to 100 MB and monitor usage. In addition to the Insight database, a List Management database is required. This can either use the same schema and tablespace as Insight, or a different tablespace, or a different Oracle instance. If you choose not to share the Insight schema and tablespace with List Management you will need to either set up a separate tablespace in the same instance or configure an instance dedicated to List Management. Configure Oracle Database to Support Insight IMPORTANT! If you wish to use a different schema (or the same schema but a different tablespace) to store your List Management database you should follow these steps again with the appropriate username, password, and tablespace name details. In the Oracle Database, create a new database or use an existing database instance for Insight persistent datastore in the directory containing the SQL files from the Oracle installation: 1. Start SQL*PLUS as a DBA user: sqlplus system/<password>@<database> Modify <password> and <database> for your system. 2. If this is the first time that Insight is being installed into a database instance you must first create the initial tablespace. This can be done from any DBA account. Run the following at the SQL*PLUS command prompt: SQL> CREATE TABLESPACE <tablespacename> DATAFILE '<location>/<datafile>.dbf' SIZE 20M REUSE AUTOEXTEND ON NEXT 10M EXTENT MANAGEMENT LOCAL ONLINE; Modify the <tablespacename>, <location>, and <datafile> for your system requirements. (Although the size of your tablespace can extend automatically, consider monitoring the size of your database periodically to be certain that the automatic extension parameter on your tablespace is enough to accommodate your needs.) 3. (Optional) You can choose to store indexes in a separate tablespace. In this case prepare a tablespace for this purpose: SQL> CREATE TABLESPACE <indextablespacename> DATAFILE '<location>/<indexdatafile>.dbf' SIZE 5M REUSE AUTOEXTEND ON NEXT 1M EXTENT MANAGEMENT LOCAL ONLINE; Page 5 BIOVIA Insight Install Guide
Modify the <indextablespacename>, <location>, and <indexdatafile> for your system requirements. Tip: When you run the Insight Project Database Configuration Wizard you should use this <indextablespacename> for the Index Tablespace. 4. Create a user under which the schema will be installed: SQL> create user <insight> identified by <insightpassword> default tablespace <tablespacename> temporary tablespace temp; The <insight> user will be created with access to the <tablespacename> and the TEMP temporary tablespace. 5. Grant the proper permissions. For example: SQL> GRANT create table, create view, create type, create session, create procedure, create sequence, alter session, create synonym, create trigger TO <insight>; The <insight> user will be granted the appropriate privileges. (User name and password values are case-sensitive when logging into Oracle databases.) Note: If you are setting up a separate List Management database, the user does not need all of these permissions, instead you should run: SQL> GRANT create table, create session, alter session TO <listmgmt>; The <listmgmt> user will be granted the appropriate privileges. (User name and password values are case-sensitive when logging into Oracle databases.) 6. Grant unlimited quota to the <insight> user: SQL> alter user <insight> quota unlimited on <tablespacename>; Note: If you are setting up a separate List Management database, you also need to specify that tablespace quota: SQL> alter user <listmgmt> quota unlimited on <tablespacename>; 7. (Optional) If you have created a separate tablespace for indexes, grant unlimited quota to the <insight> user for this: SQL> alter user <insight> quota unlimited on <indextablespacename>; Configure Pipeline Pilot Permissions for Insight Installer Only users who have sufficient privileges are permitted to run the Insight Installer: 1. Go to the Pipeline Pilot server Admin Portal: http://<servername>:<port>/admin where <servername> is the name of your Pipeline Pilot server and <port> is the port number ("9944" is the default). 2. Log in as an Pipeline Pilot administrator. If an administrator account was not previously configured, you can find the default administrator username and password in the "Administration Portal Overview" page of the Admin section of the Pipeline Pilot Help Center: http://<servername>:<port>/help/docs/?role=admin New Installation Page 6
3. Select the appropriate security permissions. The user who will be the Insight administrator should be granted the following permissions, which can be set using the Security > Permissions page in the Admin Portal: Platform Administration Logon Insight Administer ListMgmt Administer Tip: Alternatively, in the default configuration of Pipeline Pilot add the Insight administrator user to the Platform/Administrators group. Install MongoDB To install MongoDB and configure Pipeline Pilot to use MongoDB, follow the Pipeline Pilot Help Center instructions: 1. Go to http://<server>:<port>. 2. Click Help Center (Administrators). 3. Install MongoDB using the instructions at Server Maintenance > MongoDB > Installing and Deploying MongoDB. 4. Configure Pipeline Pilot to use MongoDB using the instructions at Server Maintenance > MongoDB > Configuring a Pipeline Pilot server to use a MongoDB Server. MongoDB versions If you are performing a new installation of Pipeline Pilot and Insight the installed version of MongoDB will be 2.6. If you are performing an upgrade of Pipeline Pilot and Insight where your MongoDB is installed on the same server as Pipeline Pilot the installed version of MongoDB will be upgraded to 2.6. If you are performing an upgrade of Pipeline Pilot and Insight where your MongoDB is installed on a different server from Pipeline Pilot the installed version of MongoDB will not be changed, it will remain version 2.2. Configure Data Sources (IDS) for Query Service To customize the Query Service IDS, see Configuring Query Service data sources in the Query Service Administration Guide. Run the Insight Project Database Configuration Wizard After installing Pipeline Pilot 2016, the Insight 2016 application package, and configuring the Pipeline Pilot permissions, start Insight to begin the Insight Project Database Configuration Wizard: 1. Open a web browser and navigate to http://<servername>:<port>/insight. Use an Insight Administrator account <insight-admin>. If you receive a prompt for the BIOVIA Plugin, click Install / More Information / Cancel. If the Insight Project Database has not been installed, a dialog will display. 2. To begin configuration, click Insight Configuration Wizard. 3. If needed, click Change Login and login as an <insight-admin> user who has the appropriate permissions assigned. Page 7 BIOVIA Insight Install Guide
Without administrative permissions, you are not given any further options and you cannot continue. 4. When the configuration wizard starts you will see these one of these messages: Create new Insight database. indicates that there is no data source on this Pipeline Pilot server named Insight. Tip: If you believe that Insight is already configured on this Pipeline Pilot server, check the Setup Data Sources tab in the Pipeline Pilot server Admin Portal and rename a data source to Insight if necessary, then click Refresh in the Configuration Wizard. An existing older version of the Insight database has been detected. indicates that your system contains an existing Insight database configuration. Note: If you are upgrading from a previous version of Insight, refer to the Upgrading to Insight 2016 section for more information. 5. Choose the installation type that you require: Create a new Insight Database Upgrade existing Insight Database Connect to another Insight Database 6. To configure the Insight connection information: a. Click Next, and then enter the following: Database: The type of database, always set to Oracle. Username: The database username, <insight> Password: The database password, <insightpassword> Database Server: Enter the hostname of the Oracle database. SID: Enter the service identifier (SID) for the Oracle instance on the server. Service Name: The name of the database service. Note: This is always required for Oracle 12c databases but for older versions of Oracle this is only necessary when no SID is entered. Port: 1521 For new installations select an option for each of Tablespace and Index Tablespace. This is not required for upgrades or when connecting to a different database. The Index Tablespace can be the same as the data Tablespace or separate if you have made the appropriate preparations. IMPORTANT! For upgrades, do not change the database connection details. Tip: Click the Help button to access installation instructions. b. If you are creating a new Insight database, choose whether to Use these details for List Management database? If you want to use the same schema but a different tablespace for the List Management database you should uncheck this option and specify the details in the next step. c. Click Install or Upgrade depending on your installation process. A progress report of the installation will display. 7. If you have not used the same details for the List Management database or you are performing an upgrade from Insight 2.2 or earlier you should configure the List Management connection New Installation Page 8
information: a. Click Next to continue to the List Management installer. b. Choose the installation type that you require: Create a new List Management Database Connect to another List Management Database c. Click Next, and then enter the following: Database: The type of database, always set to Oracle. Username: Oracle username, <listmgmt> (or <insight> if you wish to use the same schema) Password: Oracle password, <listmgmtpassword> (or <insightpassword> if you wish to use the same schema) Database Server: Enter the hostname of the Oracle database. SID: Enter the service identifier (SID) for the Oracle instance on the server. Service Name: The name of the database service. Note: This is always required for Oracle 12c databases but for older versions of Oracle this is only necessary when no SID is entered. Port: 1521 Enter the name for each of Tablespace and Index Tablespace. The Index Tablespace can be the same as the data Tablespace or separate if you have made the appropriate preparations. d. Click Install or Upgrade depending on your installation process. A progress report of the installation will display. 8. Click Finish. 9. Verify that http://<servername>:<port>/insight is accessible. 10. If you need to re-run the Configuration Wizard, go to Admin Portal > Setup > Data Sources, select the Insight data source and click Remove. Repeat this to remove the List Management data source. Return to http://<servername>:<port>/insight. Final Validation Searching In order to validate the installation (or upgrade) of your Insight database you should run a search, transfer the results to Insight, and save the document. IMPORTANT! If you do not have any data sources configured you should either: use the Query Service to configure the data sources you require proceed to install a BIOVIA product that automatically configures Insight data sources (for example, Biological Registration or Chemical Registration). The you should return to this validation step. 1. Go to http://<servername>:<port>/insight, where "servername is the name of your Pipeline Pilot server and port is the port number ( 9944 is the default). 2. Click Search in the Create New section of the home page, select a data source such as ACD_IDS (which checks Query Service IDS). Page 9 BIOVIA Insight Install Guide
3. Click the arrow at the right of the Search: Unsaved Form* link, and then select Ad Hoc Search: 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 the available properties that 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 that is associated with that field property appears at the right: 5. In the form item at the right, enter the query Substance Registry Number < 500 and run the query. 6. Click Search. The results are returned and a table is displayed. 7. Click Visualize Data. 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 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. Plugin Development Users in the Insight/PluginAuthors group can access the templates for plugin development from the Pipeline Pilot Client. Refer to the Getting Started with Plugins Guide for more information. New Installation Page 10
Chapter 3: Upgrading Insight Specific upgrade instructions are included in each of the installation steps described in this installation guide. We strongly recommend that you read through the entire installation guide before starting the upgrade process. Upgrade Steps To upgrade Insight you should: 1. Upgrade Pipeline Pilot 2. Install and configure BIOVIA Foundation Hub 3. Upgrade to Insight 2016 4. Post-upgrade WARNING! It is recommended that you back up your saved documents, forms, and templates before upgrading to Insight 2016 to protect your data in case problems are encountered. This involves backing 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 upgrading to Insight 2016, you must install Pipeline Pilot 2016. 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 2016 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 Administration Portal tools. Install Pipeline Pilot 2016 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 2016. Choose the appropriate installer option when prompted. IMPORTANT! If replacing an existing installation, all applications are uninstalled as part of the Pipeline Pilot installation process. The Pipeline Pilot installer displays a warning before uninstalling applications. Your data and settings will not be affected, but these applications must be reinstalled using the appropriate standalone installers. Upgrading Insight Page 11
Install and configure BIOVIA Foundation Hub Should you install Foundation Hub? If you are upgrading an existing instance of Insight that currently uses Pipeline Pilot server to manage users, groups, and permissions, we recommended that you do not install and configure Foundation Hub for this release. BIOVIA will provide enhanced identity management tools in the next release of BIOVIA Foundation. If your Pipeline Pilot 9.5 server was connected to a 9.5 Hub instance, upgrade Pipeline Pilot following the Pipeline Pilot Server Install Guide, then upgrade Foundation Hub following the BIOVIA Foundation Hub 2016 Deployment Guide. Upgrading the Insight application If upgrading from Insight 2.5 or 2.6: The Insight project database has not changed between Insight 2.5, 2.6, and 2016. If you are upgrading Insight to the existing location and are reusing your existing project database connection, you can skip running the Insight Project Database Configuration Wizard. You can verify this case by navigating to the Insight Visualize homepage and looking for saved projects in the project explorer. If upgrading from Insight 2.3 or earlier: After you have installed Insight 2016, run the Insight Project Database Configuration Wizard to upgrade your project database. This adds new fields to the database schema. This process does not change any of your existing saved documents, forms, templates, or MongoDB storing your data. IMPORTANT! Projects created in Insight 2.2, or migrated from Insight 2.1 to 2.2, are not editable by members of the Insight/Administrators group using the Project Explorer. If you are upgrading from Insight 2.2 and you require this functionality, a protocol is provided to correct this issue. 1. Verify that the Insight Configuration Wizard has run. 2. Open the Pipeline Pilot Client as a user in the Insight/Administrators group. 3. Open the Protocols\Utilities\Insight\Update Insight 2.2 Project Permissions protocol. 4. Run the protocol. All of your projects from Insight 2.2 are now available to members of the Insight/Administrators group using the Project Explorer. Page 12 BIOVIA Insight Install Guide
Post-upgrade After you have installed Insight 2016, 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 2016 Deployment 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://<server>/foundation/hub, before navigating to Insight. Upgrading Insight Page 13
Chapter 4: Configuring your databases for backup and recovery The backup and restoration documentation listed here gives you a full and consistent copy of the data that you can use to bring up a new or replacement database instance. Keep in mind that logical backups, such as exporting database objects such as tables or tablespaces, are a useful supplement to physical backups, but cannot protect your whole database. An effective backup strategy must be based on physical backups. Oracle: See 9 Performing Backup and Recovery, which describes backup and recovery methods with Oracle Enterprise Manager Database Control. You will learn how to implement a disk-based backup strategy and perform simple repairs to database files. MongoDB: See Backup and Restoration Strategies. You will learn how to back up your MongoDB project data in two different ways: 1. Use system-level tools, such as disk image snapshots. 2. Use various features in the mongodump tool. Install Guide: Configuring your databases for backup and recovery Page 14
Chapter 5: Internationalization Configuring Fonts Note: The following information is only relevant 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 define a default Unicode font in order for these types of documents to be generated properly - this is configured in a server file, Fonts.xml. IMPORTANT! <pps_install> is the root of the Pipeline Pilot server installation. On Windows this is typically: C:\Program Files\BIOVIA\PPS On Linux this depends on the location of your Pipeline Pilot server installation, but may be: [Home]/BIOVIA/PPS To define the default Unicode font: 1. Navigate to the <pps_install>/apps/scitegic/core/xml/objects/ directory on your Pipeline Pilot server and open the Fonts.xml file. If this file does not exist: Copy FontsTemplate.xml and rename it Fonts.xml. 2. Open Fonts.xml in a text editor and add your font information. Find the block of code that contains the default Unicode font entries. (often around line 20). The default Unicode font definition is composed of five values; the flag that this is the default and four font style locations in this order:!default_unicode_font! plain italic bold bold-italic 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: <sci:mpropval name="arial Unicode MS" type="stringtype"> <sci:value>!default_unicode_font!</sci:value> <sci:value>c:\windows\fonts\arialuni.ttf</sci:value> <sci:value>c:\windows\fonts\arialuni.ttf</sci:value> <sci:value>c:\windows\fonts\arialuni.ttf</sci:value> Page 15 BIOVIA Insight Install Guide
<sci:value>c:\windows\fonts\arialuni.ttf</sci:value> </sci:mpropval> 4. Save Fonts.xml. Tip: You can also add custom font definitions in Fonts.xml, refer to the Report Design Essentials Guide for further information (available through the Pipeline Pilot Help Center on your Pipeline Pilot server). Install Guide: Internationalization Page 16