Technical Bulletin: Use and Configuration of Quanterix Database Document No: Page 1 of 11 1. PURPOSE Quanterix can provide a set of scripts that can be used to perform full database backups, partial database backups, and database queries on a Simoa HD-1 Analyzer database. The scripts are written using Microsoft PowerShell and are heavily commented to aide users who may want to modify their behavior. This technical bulletin describes their installation and how to configure the scripts. The intended audience of this document is users with programming or IT experience. 2. REFERENCES Document number Document title USER-104-01 Simoa HD-1 Analyzer User Guide 1.3 3. PREREQUISITES 3.1. REQUIRED There is no required additional software to run the backup scripts. This document corresponds to version 1.8.2 of the backup scripts. The backup scripts use the free and open-source compression utility 7zip for creating compressed ZIP files. The command line version of this utility, 7za.exe, is included with the backup scripts. The backup scripts themselves are obtained from Quanterix. The scripts are typically distributed by Dropbox using a link that is emailed upon request. Alternatives to Dropbox distribution will be worked out with Quanterix Service () where necessary. 3.2. OPTIONAL ADDITIONAL SOFTWARE A text editor that highlights sections of the configuration files (which are in XML format) is highly recommended. Notepad++ is a free, open-source text editor that can be installed either on the HD-1 PC or on a separate PC to edit the configuration files. Notepad++ is available at: http://notepad-plus-plus.org/
Technical Bulletin: Use and Configuration of Quanterix Database Document No: Page 2 of 11 4. INSTALLATION AND EXECUTION 4.1. LOCATION The standard installation location for the scripts is this folder, which should be created if necessary: C:\DatabaseBackup\Quanterix Database The main script that is executed is Procedure_DB_Backup.ps1. This file contains a hardcoded path to the installation folder on line 7: These scripts can be executed by the HD-1 Analyzer software as a combined task with the HD-1 Analyzer database maintenance procedure. If running as an HD-1 Analyzer task (see section Error! Reference source not found.) the scripts must be installed in this folder. Due to limitations on the way the script is executed it is not possible for PowerShell to detect the script s installation directory. If an additional copy of the scripts is installed in an alternate location, for example to setup a set of database queries that are periodically run, then this hardcoded path in Procedure_DB_Backup.ps1 must be modified in that copy to contain the alternate location. 4.2. EXECUTION $dir = "c:\databasebackup\quanterix Database " The main script to execute is Procedure_DB_Backup.ps1. This can be executed by right-clicking the file and choosing Run with Powershell, from the Windows Task Scheduler, or from a PowerShell command line window. A batch file in the same directory as the main script, Quanterix Backup Script.bat, can also be used as a convenience to start the main script by double-clicking the file. If using a shortcut to run the main script, ensure the shortcut points to the batch file since Powershell scripts will not run from a shortcut. 4.3. WHAT IS BACKED UP The backup scripts create a ZIP format archive file containing the full or partial backup of the QuanterixDb database used by the HD-1 software, a backup of the SQL Server master database, a directory containing instrument calibration files, and a directory containing instrument firmware configuration files. An example of the contents of the ZIP format file is shown here in a screenshot from Windows Explorer:
Technical Bulletin: Use and Configuration of Quanterix Database Document No: Page 3 of 11 5. CONFIGURATION 5.1. BACKUP_CONFIG.XML A single file, backup_config.xml, is used to configure all options for the backup scripts. Editing Options Each configuration option is stored in the XML format as a key/value pair. The key is used by the script to identify the options and must not be modified. The following example uses a fictitious key option1 with a value of 123 : <add key="option1" value="123"/> The value can be edited by changing the contents inside the quotes, for example, value= 456. Comment lines are designated by a special set of characters at the beginning and end of a line, shown in boldface: <!-- This is a comment between the special comment characters. --> 5.2. CONFIGURATION OPTIONS The following table lists all of the configuration options in backup_config.xml by listing the key and default value. Refer to backup_config.xml for detailed explanations on how each effects the operation of the script. Key Value Description backup_folder c:\temp\testbackup Destination for backup files. temporary_dir c:\databasebackup\quanterix Database Backup Scripts\db_temp Location of temporary files generated by script. remove_older_than_days 5 Maximum age of temporary files (in temporary_dir) before being autodeleted. If this is set to 0 then the auto-
Technical Bulletin: Use and Configuration of Quanterix Database Document No: Page 4 of 11 Key Value Description log_file_dir C:\DatabaseBackup\Quanterix Database \Logs deletion will be disabled. Location of script logs. use_backup_folder_authentication False Option to use a username/password to access the backup_folder. user_backup_folder_autologin False If use_backup_folder_authentication is set to True and this is set to False then a popup window asking for credentials will appear before the backup folder is accessed. If set to True then the configured username and password will be used automatically (see below). backup_folder_username username Optional username for backup folder access. backup_folder_password encrypted_password_here Optional password for backup folder access. See section 5.3. db_size_multiplier 2.0 Minimum free space multiplier for backups, see file for details. SQL_connection.\SQLEXPRESS Default SQL Server address. Do not change. database QuanterixDb Default database used by HD-1 Analyzer. Do not change. query_subfolder Queries Location for SQL queries to be run, if any. Query results will be copied to the folder specified by backup_folder. database_query <blank> Comma separated list of SQL query files, if any. query_tags <blank> Tags used as output filenames for SQL queries. databasetoolpath C:\Program Files\Quanterix\Simoa HD- HD-1 Analyzer tool for generating partial backups. Do not change.
Technical Bulletin: Use and Configuration of Quanterix Database Document No: Page 5 of 11 Key Value Description 1\bin\DatabaseTool.exe run_query False Run database queries? run_backup False Run full database backups? run_partial_backup True Run partial database backups? 5.3. ENCRYPTING PASSWORDS A utility, EncryptPW.ps1, is supplied that is used to create an encrypted password if the username and password authentication is required for access to the backup folder. Running this utility will produce a file, encrypted_pw.txt that will contain the entire XML line for the backup_folder_password key that can be pasted into backup_config.xml. This is the only way to store passwords for the backup scripts. The password is encrypted as a Microsoft.NET SecureString. 5.4. FULL VS. PARTIAL BACKUPS A full backup of the QuanterixDb database file contains the database and includes the C:\FILESTREAM folder. This folder contains the raw microscopy images from the HD-1 instrument. This folder can easily be several hundred GB in size. This type of backup is not usually performed due to the long backup time and size of the output backup file. A partial backup contains the QuanterixDb database file and excludes the C:\FILESTREAM folder. This partial backup can be restored to an HD-1 install on a separate PC and it contains a complete record of all instrument activity. The default configuration is to perform partial backups. 6. LOG FILES 6.1. ARCHIVE AND FORMAT Log files are created as the scripts execute. Each time the scripts run the previous log will be timestamped and moved into a subfolder of the configured log director called archives. The log format for a successful backup will look like the following example: Messages for successful compression, queries, and backups will all be printed. If an error has occurred, it will be described in the log file.
Technical Bulletin: Use and Configuration of Quanterix Database Document No: Page 6 of 11 ******************************************************** Quanterix Database Backup and Restore Scripts Version 1.8.2 ******************************************************** Backup started at 05/11/2015 10:38:07. 2015-05-11 10:38:12 -- Checking free space on drive C:\ 2015-05-11 10:38:12 -- Checking free space on drive c:\ 2015-05-11 10:38:12 -- Partial backup started. 2015-05-11 10:38:30 -- Compression of partial backup started. 2015-05-11 10:38:40 -- Compression of partial backup finished. 2015-05-11 10:38:43 -- SQL Server, calibration, and coordinate files added to backup ZIP file. 2015-05-11 10:38:43 -- Partial backup finished. 2015-05-11 10:38:43 -- Checking existence, size, and MD5 hash of c:\temp\testbackup\2710000016\2710000016-date-2015-05-11-partial.bak.zip 2015-05-11 10:38:43 -- No errors occurred during script execution. 2015-05-11 10:38:43 -- Cleaning up backup copies older than 5 days in temporary directory. Backup complete at 05/11/2015 10:38:43. ##################################################### 7. INTEGRATION WITH THE HD-1 DATABASE MAINTENANCE TASK The backup script can be integrated with the Database Maintenance task in the HD-1 software. When configured in this way, a user would run an integrated task called Database Backup and Maintenance that first executes the backup scripts followed by the HD-1 database maintenance procedure. Refer to USER-104-01 for details on the Database Maintenance task.
Technical Bulletin: Use and Configuration of Quanterix Database Document No: Page 7 of 11 It is possible to add a new task that combines the execution of the database backup scripts with the Database Maintenance Procedure. This task will ensure that the backup has completed before any data is removed from the database. Note: It is not possible to use the combined task with manual entry of network share credentials. 7.1. INSTALLATION OF COMBINED TASK The procedure to install the combined task is as follows: Install and setup the backup scripts as described in this document. For the combined task it is required that the backup scripts be placed in the directory specified in section Error! Reference source not found..
Technical Bulletin: Use and Configuration of Quanterix Database Document No: Page 8 of 11 Test the backup scripts by running the Powershell script as described in section Error! Reference source not found.. An empty window will appear on the screen while the backup executes and nothing should be printed to the window. When the script finishes the window will close. Check the log file (section Error! Reference source not found.) to verify that the backup executed correctly. Verify that a ZIP file is located in the backup script folder. The ZIP file is called Integrated Procedure 1.3.1412.zip. This should have been packaged with the backup scripts and the file name should match the version of the HD-1 software in use. If it is missing please contact Quanterix support. Open the HD-1 software and navigate to the Maintenance tab. At the bottom left of the screen click on the Import button: A directory browsing window will open. Navigate to the script directory and select the ZIP file that matches the version of the HD-1 software in use and click Open. A message will display that should state the import was successful. If it states there was an error please contact Quanterix service. Click OK in the message window. Next, click the Add button in the lower left to create a task in the Maintenance window. In the New Task window that appears click on the Procedure menu and select the Database Backup and Maintenance option. Select a run interval for the task (typically weekly) and click Save.
Technical Bulletin: Use and Configuration of Quanterix Database Document No: Page 9 of 11 The combined task will now be listed in the Maintenance tab:
Technical Bulletin: Use and Configuration of Quanterix Database Document No: Page 10 of 11 The Database Maintenance task can now be removed if desired by clicking the box next to it followed by clicking the Delete button. The combined task can now be run provided the instrument is in the Ready state as described in the HD-1 User Guide (document USER-104-01).
Technical Bulletin: Use and Configuration of Quanterix Database Document No: Page 11 of 11 8. REVISION HISTORY Revision Detailed description Date Originator 1 Initial Release 17Feb2015 B. Gregor 2 Update with instructions on the integrated backup and maintenance task and the added backup files. 21May2015 B. Gregor