LabLynx KB:LabLynx system installation and maintenance manual

Introduction

Overview

This document details the process of installing and maintaining a LabLynx Web application. A LabLynx Web application consists of ASP files and components. We will refer to the components (DLLs, EXEs, etc.) collectively as iServer. iServer will be packaged as a setup.exe and will install all the required components needed by the Web application. After iServer is installed, iServerManager will be used to configure and upgrade the Web application. iServerManager can be run from any workstation that has access to the database and Web folder. Before running an upgrade with iServerManager, please make a full backup of your database and/or Web files.

Architecture

The basic installed system architecture is represented by the following diagram:

System requirements and settings

Before proceeding with the LabLynx install please validate the following system requirements:

Web server

• Windows 2000 (Service Pack 4 or higher), Windows 2003, Vista
• MDAC 2.6 or higher

Database server

For Oracle versions of the product:

Oracle requirements on the Web server (where iServer is installed)

• Oracle9i Client 9.2 or higher
• Oracle Provider for OLE DB 9.2.0.4.0 or higher
• Oracle ODBC Driver 9.2.0.5.4 or higher

Oracle requirements on the database server

• Oracle9i Database 9.2.0.1.0 or higher

For SQL Server versions of the product:

• SQL Server 2000 or higher

Client Web browser

• Microsoft Internet Explorer 5.5, 6.x or 7.x

• the addition of the application's Web site to trusted sites (On the menu go to Tools/Internet Options…, click the Security tab, and then click the Sites… button next to "Trusted Sites".)
• See the following link for more detailed client settings: [1]

iServerManager workstation

• Windows 2000 (Service Pack 4 or higher), WindowsXP/Windows 2003, or Vista

Installation of the software

Before the install

Before proceeding with the install:

1. Validate the system requirements and settings in the first section of the system install instructions. Also validate that a printer has been installed on the Web server.
2. Get all users off the LIMS application and reset IIS. (From the Web server select Start/Run/iisreset.)
3. If doing a system replacement, make sure you backup the Web files and folders and the database of your existing system before proceeding with the system replacement.

IServer Install

All programs/files are contained in the .zip file provided. Unzip to a folder and follow instructions contained therein. To set up iServer properly you must be logged into the web server as an administrator. If you have previously installed iServer, please run the uninstall exe from the Start/All Programs/LABLynx iServer/Uninstall menu item. Then run the latest version of the iServer setup on your Web server.

IServerManager

Open the iServerManager_Install.zip file. Extract it to a folder on your Web server and run the setup.exe included. This will install iServerManager, which will be used later in the process. In most cases if errors occur during the install process, it is due to the fact that certain .dll files may be in use while the install tries to replace them. It is ok to ignore these errors.

Making the install

Web site Creation:

1. Copy the Web folder included in the install package to the web server.

2. If you are doing a new install copy the contents of the Web folder (The LIMS folder) where you would like your web folder to reside. (usually c:\inetpub\wwwroot\). Then skip to step three. If you are doing a system replacement you can simply copy this directory over your existing LIMS directory on the web server. If the name of your web folder is not LIMS, rename the LIMS folder that was included in the replacement package to your actual Web folder name and proceed with coping over your existing folder. You can now skip to step four to validate your IIS settings.

3. Using Internet Services Manager, create a new virtual directory on your Web site. (Accept the defaults when setting it up.) Point the virtual directory to the new Web location (e.g. c:\inetpub\wwwroot\lims).

a. Right click on the default Web site under IIS Console and choose New/Virtual Directory.

b. Hit the Next button.

c. Alias your website as "LIMS" and hit Next.

d. Browse to where you copied the Web folder contents above at step two and hit Next. (Usually c:\inetpub\wwwroot\)

e. Select all the options for virtual directory access permissions except Execute. Leave Execute unchecked and hit Next.

f. Click Finish.

4. Special instructions:

Special Instructions for Windows 2003

a. In IIS, click the nodes on the left and navigate to the Web site.

b. Right click on the Web site and choose the Properties option.

c. On the Virtual Directory tab click the Configuration button.

d. Click the the Options tab.

e. Check the option "Enable Parent Paths for the Web application". Then click OK twice.

f. In IIS, select the Local Computer node. Right click, click properties, click the MIME Types ... button and enter this new MIME type:

            File Extension: .*
            MIME Type: application/octet-stream

(This is especially necessary for the .vs file extension. The LABLynx application will not function correctly if the .vs file extension is not included in the MIME types. If your security settings prevent you from adding the .* MIME type you must at a minimum add the .vs file extension to the MIME types)

g. Right click on the Web Server Extension node in IIS and hit the Properties option.

h. Make sure that "Active Server Pages" and "Server Side Includes" are both allowed on the Web server. Highlight the extension and hit the Allow button to activate. If "Active Server Pages" are not allowed the application will return a "404 Page Cannot be Found" error.

Special Instructions for Setting up Oracle 9i for ASP

a. Reboot the server at least once after installing either IIS or Oracle.

b. Add the following entries to sqlnet.ora (typically c:\oracle\ora92\network\admin\sqlnet.ora) and save:

            SQLNET.AUTHENTICATION_SERVICES = (none)
            SQLNET.AUTHENTICATION = (none)

c. Give the Internet guest user account (IUSR_MachineName), IWAM_MachineName, the Authenticated User account and if using iis 6.0 or higher the IIS_WPG User account full security rights to the Oracle Home folder (typically c:\oracle). Also, be sure to check the Reset Permissions on all child folders.

d. Reboot the machine. (Refer to Microsoft knowledge base article for more information: http://support.microsoft.com/default.aspx?scid=kb;EN-US;Q255084)

5. Create a new printer. (Note, this is used by the reporting engine to format reports. It does not have to be an actual physical printer, just a setup of a printer so the reporting engine can use the drivers.) You might have one setup and can use it, but if it does not work, follow these steps:

a. Go to Start/Settings/Printers.

b. Click Add Printer.

c. Click Next, select Local Printer and uncheck "Automatically detect and install my plug and play printer."

d. Click Next, select "Use the following port," and then select File: for the port.

e. Click Next, select HP for the manufacturer and HP LaserJet 8000 Series PCL for the printer.

f. Use the default settings, but you do not have to print a test page.

g. Right click the new printer, which should be named "HP LaserJet 8000 Series PCL." Be sure to name it or update the default setting for the printer name. Make sure everyone has access to this printer. Important note: share the printer as the same name (HP LaserJet 8000 Series PCL). If you are using a different printer, make sure to share it as the same name.

6. Once the database has been created you will need to link your Web application to the database. Instructions are below.

Set File Folder Permissions:

We now need to set permissions on two folders on the Web server. Depending upon your security procedures you will need to make sure the Internet Guest User account (IUSR) and or the Authenticated User accounts are in the list of eligible users and have Full Control (or at least read, write, modify, read & execute and list folder contents) to the folders listed below and their children. If you are using IIS 6.0 or higher you will need to do the same for the IIS_WPG User account. To change permissions on child folders and files right click on the parent folder. Hit the advanced button on the security tab. Choose the "reset permissions on all child objects and enable propagation of inheritable permissions" option, then hit ok.

C:\iServer (Or the alternate location you chose of your iServer folder)

C:\inetpub\wwwroot\LIMS (Or the alternate location you chose of your web folder)

Database Creation:

The install package will include a database directory. In that directory you will find the database backup that can be restored. Copy the database directory included in the install package to your database server. **Note: Database names and passwords cannot contain any of the following special characters: "?" , "#", "&".

For SQL Server

Note that if the Web application user is not in the db_owner role, the application user will need to be in the db_dataread, db_datawrite roles and granted execute permissions on all non-system stored procedures and user-defined functions. Your dba will need to make sure these permissions are granted.

1. You will need to create a new (or replace an existing) SQL Server Database.

2. From the Database Server select Start / All Programs / Microsoft SQL Server / Enterprise Managers.

3. Click and open the nodes on the left until you have navigated to the list of databases. (Note that if you are doing a database replacement instead of a clean install skip to step eight.)

4. Right click on any database in the list and select New Database.

5. Use "LIMS" for the name of your new database.

6. If you would like to modify where the actual data files reside you can modify the datafile locations under the Datafile and Transaction Log tabs

7. Click Ok to create the database.

8. Now find your new (or previously installed) database in the list and right click on it.

9. Choose All Tasks and click Restore Database.

11. Choose the From Device radio button.

12. Hit the Select Devices button.

13. Hit the Add button.

14. Hit the ... button and browse for the backup file included in the replacement package.

15. Hit OK three times

16. Select the Options tab.

17. Check Force Restore Over Existing Database. (Make sure the Restore As file names and paths match the data files created with the new database. e.g. If your database is named LIMS, your data files under the Move to Physical File name column should be LIMS_Data.mdf and LIMS_Log.ldf. You do not need to modify the Logical File name column.)

18. Click OK. It should now restore the new database over the existing one.

Note that the restore of the backup file must be performed from a Windows machine (preferably the Web server). We have experienced character interpretation issues when restores have been performed from UNIX machines. LabLynx also requires the use of the WE8MSWIN1252 character set. Failure to use this character set could cause the system to fail in certain areas.

If you are doing a new install you will need to create the lablynxuser schema in your database. See the Example script below. If you are doing a system replacement place, you will need to drop the existing user first before creating it. From the database server login to SQLPlus as sys. Here is a sample script to help create the schema:

            drop User lablynxuser Cascade;   --Only used on system replacements
            create user lablynxuser
            identified by lablynxuser
            default tablespace T_LABLYNX
            temporary tablespace T_LABLYNX_TEMP
            quota unlimited on T_LABLYNX;
            /
            GRANT CONNECT, RESOURCE TO lablynxuser;

Once the above script has been run and the lablynxuser has been created you can restore the backup over it.

Included in the database directory along with the backup file of the database is a LIMS_RESTORE_DB.bat file. This file is used to do the db restore and will need to be modified. To edit the LIMS_RESTORE_DB.bat file right click on it and select edit. (Notepad is fine.) You should...

• Replace the ??? with the system password. (set UserPass=system/???)
• Replace the ??? with the TNS name. (set TNSNAME=???)
• Replace the ??? with the Location of the backup file. (set DMPLocation=C:\???\)
• In most cases the from user and to user can stay the same (lablynxuser). If lablynxuser is not the name of your schema then please change the to user name setting. (set TO_USER=???)

After you have finished editing the LIMS_RESTORE_DB.bat file save it. You can now double click the file to restore the database.

Set LIMS connection to the database

1. From the Web server open the iServerManager.exe.
2. From the menu choose File / Open.
3. Browse for the setting.isv file stored under the LIMS Web directory. Select it and hit Open. (If no setting.isv file is available, skip to step eight.)
4. You will need to modify the server entry. (This is the database server name for SQL server systems and the TNS name for Oracle systems.)
5. You will also need to modify the database name, user, and password entries to match your settings.
6. You will also need to set the Current App value to a value provided by LabLynx. See your readme file for this value.
7. Once those settings have been changed you should hit the Save Encrypted button.
8. If the setting.isv file is not available the global.asa file can be edited manually. To do this open the global.asa file in Notepad. Scroll down the file until you see the following text:

            '*************** Setup of Database Connection *************
            strDatabase = "????" 'Name of database
            strServer = "????" 'Blank string if database is on the webserver, IF NOT IP address of database server
            strUser = "????" 'Database user
            strPwd = "????"  'Database user password
            '**********************************************************

Replace the ???? with the applicable values:

• strDatabase = This is the name of the database. It is not used in Oracle systems.
• strServer = This is the name or IP of the server for SQL Server systems. It is the TNS name for oracle systems.
• strUser = This is usually sa for SQL Server systems and lablynuser for Oracle systems.
• strPwd = This is the database password.

Afterwards, save the global.asa file.

9. Reset iis. (From the Web server hit Start/Run/iisreset.)

Additional Instructions

If you are currently using the Active Reports functionality and are installing the application for the first time or moving the application to a new directory, it will be necessary to modify the template location of all the active reports saved in the application. If a script was provided to do this operation, you can run it now. If no script was provided, you can log into the application and do this manually (the login information is below under the install complete heading). In the application under the LabLynx Menu go to System / Reporting Tools / Reports Management. Click on each report that has a Report Type of Active. For each report resave the record and it will automatically update the report template location to match the new directory. You will need to trigger the save button by modifying the record.

If any additional scripts or directions were included you can proceed with them now.

The system should now be functional. You can login to the application with the sysadmin / lablynx user password combination.

Database restore or install

Restoring a database

SQL server

1. Restore the database file using SQL Server Enterprise Manager.

2. If the Web application user is not in the db_owner role, the application user will need to be in the db_dataread and db_datawrite roles and granted execute permissions on all non-system stored procedures and user-defined functions. Your DBA will need to make sure these permissions are granted.

Oracle

1. Log in as sys and create a user, granting the connect and resource privileges. The following is a sample script that does this (creates a user called lablynxuser with password lablynxuser):

            create user lablynxuser
            identified by lablynxuser
            default tablespace T_LABLYNX
            temporary tablespace T_LABLYNX_TEMP
            quota unlimited on T_LABLYNX;
            /
            GRANT CONNECT, RESOURCE
            TO lablynxuser;

2. Restore the backup file. Again, a sample script:

            @ECHO OFF
            set UserPass=system/llx
            set TNSNAME=LLX
            set DMPLocation=d:\Share\DataBackup\
            set DMPName=llx_rel_03-08-05.bak
            set FROM_USER=lablynxuser
            set TO_USER= lablynxuser
            set IgnoreVar=N
            REM DMPLocation
            ECHO YOU ARE ABOUT TO RESTORE %DMPName% TO THE USER %TO_USER% IN THE DATABASE %TNSNAME%!!!!!!!!!!!!!!!PAUSE
            imp %UserPass%@%TNSNAME%  FROMUSER=%FROM_USER% TOUSER=%TO_USER% IGNORE=%IgnoreVar% file='%DMPLocation%%DMPName%' log='%DMPLocation%%TO_USER%RESTORE.log'  grants=N 
            pause

Creating a new database application

1. First, create the Web folder where the Web files will reside. (e.g. c:\inetpub\wwwroot\mywebsite)

2. You will use iServerManager to create new iServer applications. Open iServerManager:

To create a new application go to File/New:

Enter the settings to connect to your database and click Save. Choose a name for your settings file, and save it to the folder you created in step one. (e.g. c:\inetpub\wwwroot\mywebsite\Settings.isv)

3. Run the .aip file. After saving the settings file, click the Install/Upgrade tab. Then click the … button to browse for the .aip file and open it:

4. Click Execute and wait for successful completion.

Additional setup requirements of the Web application

1. Give the Internet guest account user (IUSR) full control (read, write, modify, and delete) to these folders and their contents:

• …\lims\elab\documents
• …\lims\elab\Excel
• …\lims\elab\llx_reports
• …\lims\elab\uploads

2. Using Internet Services Manager, create a new virtual directory on your Web site. (Accept the defaults when setting it up.) Point the virtual directory to the new Web location (e.g. c:\inetpub\wwwroot\lims).

Special instructions for setting up ASP on Windows 2003

1. Open IIS and enable parent paths for the Web application. (You access this by clicking the Configuration button and clicking the Options tab.)

2. Upon opening IIS, select the Computer Node. Right click, click Properties, click the MIME Types ... button and enter this new MIME type:

            File Extension: .*
            MIME Type: application/octet-stream

Special instructions for setting up Oracle 9i for ASP

1. Reboot the server at least once after installing either IIS or Oracle.

2. Add the following entries to sqlnet.ora (typically c:\oracle\ora92\network\admin\sqlnet.ora) and save:

            SQLNET.AUTHENTICATION_SERVICES = (none)
            SQLNET.AUTHENTICATION = (none)

3. Give the users IUSR_MachineName and IWAM_MachineName full security rights to the Oracle home folder (typically c:\oracle). Also, be sure to check the reset permissions on all child folders.

4. Reboot the machine.

Refer to this Microsoft knowledge base article for more information: Microsoft Knowledge Base: How To Troubleshoot an ASP-to-Oracle Connectivity Problem

3. Create a new printer. (Note, this is used by the reporting engine to format reports. It does not have to be an actual physical printer, just a setup of a printer so the reporting engine can use the drivers.) You might have one setup and can use it, but if it does not work, follow these steps:

a. Go to Start/Settings/Printers.

b. Click Add Printer.

c. Click Next, select Local Printer and uncheck "Automatically detect and install my plug and play printer."

d. Click Next, select "Use the following port," and then select File: for the port.

e. Click Next, select HP for the manufacturer and HP LaserJet 8000 Series PCL for the printer.

f. Use the default settings, but you do not have to print a test page.

g. Right click the new printer, which should be named "HP LaserJet 8000 Series PCL." Be sure to name it or update the default setting for the printer name. Make sure everyone has access to this printer. Important note: share the printer as the same name (HP LaserJet 8000 Series PCL). If you are using a different printer, make sure to share it as the same name.

4. The setup of the new Web application is complete.

Installing iServerManager

iServerManager consists of one .exe file. There is no setup required.

System upgrades

Once you have installed the Web application, you can use iServerManager to run the upgrades to the Web application (Web files and database). All upgrades to the product are packaged in a .zip file that has an “aip” extension. You will use iServerManager to open one of these files and run the upgrade. The contents of the .aip file consists of several XML and/or script files used to upgrade the product.

Contents of the .aip file

An .aip file is simply a .zip file that contains the instructions and data the iServerManager will use to update the database and/or Web files. When iServerManager runs the .aip file, it will first open the AIPInstructionFile.xml to get the list of operations it will perform. Below is an example of an .aip file:

.aip file (Opened using WinZip)

AIPInstructionFile.xml

As you can see, the AIPInstructionFile is an XML file that contains a list of instructions to perform. All files referenced in the instructions must be in the .aip file.

Below, is a description of each instruction:

<Instruction name="ImportWeb" filename="llxs_rel.zip"/>

This instruction will copy the Web files contained in “llxs_rel.zip” to the Web folder. It will overwrite files that are older.

<Instruction name="Connect" databasetype="SQL" connectionstring1="Provider=SQLOLEDB.1;Persist Security Info=True;User ID={USER};Password={PASSWORD};Initial Catalog={DATABASE};Data Source={SERVER}" />

This instruction will make the database connection to be used throughout the processing of the .aip.

<Instruction name="ExecuteScript" scriptfilename="llxs_PreUpgradeMain.sql"/>

This instruction will run the script in the file llxs_PreUpgradeMain.sql.

<Instruction name="ImportDatabase" schemafilename="ExportSchema.xml" metafilename="ExportMeta.xml" databasetype="SQL" connectionstring1="Provider=SQLOLEDB.1;Persist Security Info=True;User ID={USER};Password={PASSWORD};Initial Catalog={DATABASE};Data Source={SERVER}" connectionstring2="Provider=SQLOLEDB.1;Persist Security Info=True;User ID={USER};Password={PASSWORD};Initial Catalog={DATABASE};Data Source={SERVER}" tableindex="T_LABLYNX_INDEX" options="124927"/>

This considerable bit of instruction will upgrade the database. It will apply the schema objects (tables, views, stored procedures, etc.) contained in ExportSchema.xml to the database. This schema file is a complete representation of the database with all the tables, views stored procedures, functions, constraints, etc. defined using XML. The iServerManager will compare the objects in the XML file to the existing objects in the database and apply the changes so that the existing database is brought to the same version of the database represented by the XML.

The upgrade is additive for table structure changes meaning existing columns will not be dropped or downsized (e.g. int to smallint), existing columns will be upsized (e.g. varchar(20) to varchar(50)), and new columns and tables will be added. All other objects will replace existing objects or be added to the database if not there. After iServerManager processes the schema file, it will process the meta file. All metadata is contained in the XML file ExportMeta.xml. The process of updating the metadata is to replace the existing metadata in the database with the metadata contained in this file. Below are sample snapshots of each of the files (only displaying a tiny portion due to space):

ExportSchema.xml

ExportMeta.xml

<Instruction name="ExecuteScript" scriptfilename="llxs_6_06_PostScript.sql"/>

This instruction will run the script contained in llxs_6_06_PostScript.sql.

<Instruction name="ExecuteScript" scriptfilename="llxs_PostUpgradeMain.sql"/>

This instruction will run the script contained in llxs_PostUpgradeMain.sql.

<Instruction name="UpdateReleaseInfo" release="llxs_6_10" />

This instruction will mark the database as version 6.10.

Running the .aip

1. You run an .aip file using iServerManager. Open iServerManager.exe.

2. From the File menu click Run AIP. This should bring up the following screen:

3. If the .aip file contains Web files, you will need to browse to (or enter) the name of the Web application folder so that iServerManager knows where to copy the Web files. This is not necessary if the .aip file does not contain Web file updates. The folder will be the root folder of the Web application (e.g. D:\Inetpub\wwwroot\lims).

4. Browse for and open the .aip file.

5. Click Execute and the iServerManager should begin processing the .aip file. If that file contains database upgrades, iServerManager will prompt the user for database login information. Be sure to login as the appropriate database user (needs to be in the db_owner role). When the iServerManager has finished, it will display “Finished AIP at [Current Time]”.

Viewing the log files

After running an .aip file, iServerManager will produce a set of three log files in the same directory as the .aip file. The naming convention for these files is [AIP Filename]_[Timestamp]_flow.log, [AIP Filename]_[Timestamp]_error.log, [AIP Filename]_[Timestamp]_sql.log. The [Timestamp] for all three files will be the same. The flow log is a high-level log of what occurred. This information is the same as what the user will see on the screen while the upgrade is running. The error log will contain detailed information about any errors that occurred during the upgrade. The SQL log will contain all SQL DDL statements that were executed. The log files can be deleted at any time. They are used to help the user diagnose problems with the upgrade. Below are sample snapshots of these files:

llxs_6_10_clean_20050311102116_flow.log

llxs_6_10_clean_20050311102116_error.log

The error file above contains the ErrorInfo which is the error message and the payload, which is the statement(s) that caused the error.

llxs_6_10_clean_20050311102116_sql.log

These are the DDL SQL statements that were executed against the database. You can use this file to verify what changes iServerManager made to the database.

Related questions

• LabLynx KB:System install
• LabLynx KB:Installing the LabLynx report engine MTS component
• LabLynx KB:System replacement
• LabLynx KB:Setting up ASP on Windows 2003
• LabLynx KB:JOB Manager install