INSTALL GUIDE BIOVIA INSIGHT 2.6
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: Installation 2 General Requirements 2 Installation Steps 2 BIOVIA Pipeline Pilot and Insight Application Installer 2 Oracle Database 4 Configure Oracle Database to Support Insight 4 Configure Pipeline Pilot Permissions for Insight Installer 5 Install MongoDB 6 MongoDB versions 6 Configure Data Sources (IDS) for Query Service 6 Run the Insight Project Database Installer Wizard 6 Initial Insight Configuration 9 Set permissions for users and groups 9 Define the default settings for each data source 9 Final Validation 11 Searching 11 Plugin Development 12 Chapter 3: Upgrading to Insight 2.6 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 9.5 Installation Guide BIOVIA Pipeline Pilot Client Installation Guide BIOVIA Pipeline Pilot Server Admin Portal online help Web Services Guide Further Information For more information about Insight and other BIOVIA software products, visit BIOVIA Support on the Web: https://community.accelrys.com/index.jspa Page 1 BIOVIA Insight Install Guide
Chapter 2: Installation General Requirements It is recommended that you use several servers for Insight within local network proximity. 1. A BIOVIA Pipeline Pilot Server 9.5 server with the Insight 2.6 application package installed. 2. An Oracle Database account. Insight 2.6 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 Pipeline Pilot 9.5 and Insight 2. Install and configure Oracle (not required for upgrades) 3. Run the Insight Install Wizard 4. Install MongoDB 5. Configure Data Sources (IDS) for Query Service 6. Perform a Final Validation 7. Configure Insight Note: If you are upgrading from a previous version of Insight, refer to the Upgrading to Insight 2.6 section for more information. WARNING! It is recommended that you back up your saved documents, forms, and templates before upgrading to Insight 2.6 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. BIOVIA Pipeline Pilot and Insight Application Installer IMPORTANT! After you have installed Pipeline Pilot with Insight 2.6 users will not be able to access the web client until the Installer Wizard has been run. 1. Install Pipeline Pilot 9.5 using the document Pipeline Pilot 9.5 Server Installation Guide. At the BIOVIA Download Center, log in and locate version 9.5 under the Pipeline Pilot link. Install Guide: Installation Page 2
2. Install the Insight 2.6 application package. a. At the BIOVIA Download Center, log in and locate version 9.5 under the BIOVIA Insight link. b. Download and unzip the appropriate installer archive: Windows: Insight2.6_Win64.rar Linux: Insight2.6_Linux64.tgz c. Run scitegicsetup.exe in the bin folder of the unzipped directory. d. When the installation starts, ensure that the Insight application is checked, and specify the location of your Pipeline Pilot 9.5 install when prompted. The Insight installer will also install List Management. e. Proceed through the installer, using the Pipeline Pilot 9.5 Server Installation Guide if required. IMPORTANT! You may get a warning about Insight and related packages being uninstalled during upgrades from previous versions of Pipeline Pilot. Click OK in this warning dialog and proceed with the upgrade, Insight 2.6 will be installed during the upgrade and your data will not be affected. 3. If you connected the BIOVIA Hub to your Pipeline Pilot 9.5 Server before installing the Insight application, you will need to update your Hub connection after installing Insight. a. Go to your BIOVIA Pipeline Pilot Server Home Page. b. Under the Administrators section, go to the Administration Portal. c. In the Admin Pages menu, expand the Security folder, and then go to Hub Connection. d. On Registered Applications, click Update to update the list applications. Page 3 BIOVIA Insight Install Guide
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; Install Guide: Installation Page 4
Modify the <indextablespacename>, <location>, and <indexdatafile> for your system requirements. Tip: When you run the Installer 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 Page 5 BIOVIA Insight Install Guide
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 Installer Wizard After installing Pipeline Pilot 9.5, the Insight 2.6 application package, and configuring the Pipeline Pilot permissions, you can then start Insight to begin the Insight Project Database Installer Wizard: 1. Open a web browser and navigate to http://<servername>:<port>/insight. Use an Insight Administrator account <insight-admin>. If you get Java warnings due to the Chemistry Sketcher applet, click Install / Run / Always Allow. If the Insight Project Database has not been installed, a dialog will be displayed. 2. To begin installation, click Insight Installation Wizard. Install Guide: Installation Page 6
3. If needed, click Change Login and login as an <insight-admin> user who has the appropriate permissions assigned. Without installation permissions, you are not given any further options and you cannot continue. 4. When the installer starts you will see these one of these messages: New Insight database installation. 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 Installer 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 2.6 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. The progress of the installation will be reported. Page 7 BIOVIA Insight Install Guide
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 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. The progress of the installation will be reported. 8. Click Finish. 9. Verify that http://<servername>:<port>/insight is accessible. 10. If you need to re-run the Installer, 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. Install Guide: Installation Page 8
Initial Insight Configuration Set permissions for users and groups A platform administrator can set permissions for specific users and groups. On the Security Permissions page of the Pipeline Pilot Administrator Portal, set the following security permissions: Insight Administer. Permission to administer Insight. Insight AuthorPlugins. Permission to see additional debugging information in the client for Insight plug-in developers. Insight Logon. Permission to log into Insight. Insight ManageProjects. Insight Users with elevated privileges. Define the default settings for each data source Only an Insight administrator can define the default settings for each data source, as follows: 1. From the Search workspace, click the arrow at the right of the data source (such as DataSource: ACD_IDS), and choose Settings... from the dropdown list. For example: 2. In the Default Settings for Data Source dialog, you can do any of the following: To set a Search form as the default, click Form in the Search Defaults panel at the left, and then choose the public form to use by default from the dropdown list. In the following example, the Search form is also named Search Form : Tip: Only public forms can be used for the default search form. When a user opens the data source, this Search form appears by default. The user can switch to a different Search form for this or another data source at any time. To set the Ad Hoc search as the default, click Ad Hoc Search in the Search Defaults panel at the left, and choose the root category for the data source. For example: Page 9 BIOVIA Insight Install Guide
When a user opens the data source, the Ad Hoc Search appears by default. The user can switch to a Search form at any time. To set a Browse form as the default for a particular root category of the data source, choose the category from the For root dropdown list. For example: Then select a form in the Browse Defaults panel. For example: After a search, this Browse form appears. The user can switch Browse forms for any of the root categories or get the Table View of the data at any time. To set Table View as the default, choose your root category from the For root dropdown list. For example: Then click Table: 3. Click OK. The user can switch to a Browse form for that data source at any time. Install Guide: Installation Page 10
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). 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. Page 11 BIOVIA Insight Install Guide
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. Install Guide: Installation Page 12
Chapter 3: Upgrading to Insight 2.6 If you have an existing Insight 2.5, 2.2, or 2.1 installation you can upgrade this using the Installer Wizard to Insight 2.6. The following changes will be made automatically when the Insight 2.6 application package is installed and the Install Wizard runs the upgrade: The Pipeline Pilot packages will be updated to 2.6.000. The database version will be updated to 2.6. All existing saved documents, forms, and templates will remain unchanged. The MongoDB storing your data will remain unchanged. WARNING! It is recommended that you back up your saved documents, forms, and templates before upgrading to Insight 2.6 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. IMPORTANT! After you have installed Pipeline Pilot with Insight 2.6 users will not be able to access the web client until the Installer Wizard has been run. IMPORTANT! An issue in Insight 2.2 means that Insight projects migrated from Insight 2.1 to 2.2 (or created using 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. Ensure that the Insight upgrade wizard has been run 2. Open the Pipeline Pilot Client as a user in the Insight/Administrators group. 3. Open the Utilities\Accelrys\Insight\Update Insight 2.2 Project Permissions protocol. 4. Run the protocol. All of your projects from Insight 2.2 will be available to members of the Insight/Administrators group using the Project Explorer. Page 13 BIOVIA Insight Install Guide
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