Quick Start Guide


Quick Start Guide

BSI is a powerful software system for biospecimen management that can be configured to accommodate countless specimen workflows. The workflow described in the step-by- step instructions provided offers a preview of BSI functionality and illustrates how easy it is to configure storage locations, add specimen data, track specimen distribution, and generate reports. These instructions were meant to be used in conjunction with your own BSI Demo database.

Create a Demo Database

  1. Use your browser to navigate to the BSI Demo Signup page at https://demo-engage.bsisystems.com/signup/.
  2. Enter required contact information: First name, Last name, Email and a Database name of your choice.
  3. Press the Create Demo Database button. It takes just few minutes to create your database.

Once the database is created, you are taken to the BSI Engage database selection page. Select Start to open the login page. There is a link to start the BSI client from this page. You will also receive an email explaining how to launch the BSI client for your database as well as logon and firewall information.BSI Demo login page.PNG

QUICK TIP: Bookmark the BSI Engage logon page to easily find it later

Installing the BSI Launcher will allow you to access the full featured desktop application BSI client.

Installing the BSI Launcher

For Windows installation:

  1. After selecting the Windows button, an .exe file will be downloaded.
  2. Once downloaded, locate the downloaded .exe file and double-click to open it. The installer wizard will open. To install BSI to the recommended location, simply select Next and Install.
  3. After selecting Finish, a BSI icon will be installed on your desktop and/or in the Start menu.

For Mac installation:

  1. After selecting the Mac button, a .zip file will be downloaded. Downloading this file may take a few minutes.
  2. Once download is complete, a .dmg file will be accessible in the Downloads folder. Open the .dmg file. It may take a few seconds for the file to open.
  3. An installation window will open. Drag and drop the BSI icon onto your desktop.

QUICK TIP: Passwords must be at least 8 characters long and contain at least one uppercase letter, one lowercase letter, one number, and one special character.

Launch and Login to the BSI Client

  1. Open the BSI Launcher by double clicking its icon on your desktop or in your start menu.
  2. Enter your database name and click the LAUNCH BSI CLIENT button. (The launcher will check for updates and open a login window.)
  3. Enter the login information sent in the confirmation email and click the Login button. Before the BSI Client opens, you are prompted to update your password.
  4. On the Expired Password prompt enter a New Password value and a Confirm Password value and press the OK. The BSI Client opens.

You are now logged into your new demo database, which means you have access to the full breadth of modules BSI has to offer. Your account is a local administrator, which means you can add new users and manage other accounts under the User Administration manager. Tabs for Data Entry, Locations, Reports, and Requisitions are shown by default but other managers can be accessed from the Manager menu. Under Locations, specimen storage locations were created for your repository. Two studies and a data entry template with default specimen values are also available.

Did You Know…?

BSI provides four interfaces:

BSI Client
A full-featured java client

BSI Engage
A web interface for the occasional user

BSI Connect
A web services interface for system-to-system communication

Example Workflow

In the following workflow, you will configure a 9x9 storage box, add new specimen data, track specimen distribution, and generate a report.

Configure a Storage Location

  1. Select the Locations tab to access the Locations manager.
  2. In the location hierarchy on the left, select the + to expand Building 1, Room 1, Freezer 1, Rack A until you see the five boxes located in the rack.
  3. Right-click on Rack A and select New Subcontainer from the menu. The New Container dialog opens.
  1. Select the Ellipsis (…) button in the General Container Type The Select Codes dialog opens listing container types that go in a rack.
  2. Select the listing for “Box 9x9” and press the OK On the New Container Type dialog, the General Container Type value updates to “Box 9x9”.Locations_manager.png
  1. Press the OK button on the New Container type The Location editor opens with box properties.
  2. Enter an ID value and select the Row Format and Column Format and press the Save. After closing the dialog, the 9x9 slot box is added to the location hierarchy under Rack A and is available for storing specimens.

Did You Know…?

The BSI Locations can be configured to track all manner of specimen storage hierarchies and containers including straw storage, ambient storage, LN tanks and slide storage.

Enter Specimen Data

  1. Click on your box in the location hierarchy. On the right side of the Locations manager are tabs that show Container Parameters, Box Layout, and Box Contents.
  2. Select the Box Layout tab to see the contents of the box laid out in a grid.
  3. Select several contiguous box slots and right-click on them. A menu opens.
  1. Select Add Specimen… from the menu. The Data Entry Batch editor opens with one specimen record for each box slot you selected. Default data is filled in from your default template and locations are filled in with the locations you selected in the box.

Did You Know…?

In order to support diverse workflows specimen data can be entered in various ways, including by importing. In addition, Data Entry Templates can be configured to generate records and add default data.

add batch.PNG

QUICK TIP: To quickly select all records in a table select the CTRL+A keys.

  1. Add a Subject ID for these records. To add the same Subject ID value for all records, select all records. Right-click anywhere in the Subject ID column and select Mass Change from the menu. The Mass Change dialog opens.
  2. Enter a Subject ID value of your choice in the Set Value field and press the OK button. Subject ID is updated for the selected records.
  3. Next, assign BSI IDs. First press the Save icon (or File menu/Save) to save the batch.Data_entry_add_batch.png


The Mass Change tool is available on all editable BSI tables and is a great way to update many rows of data at once. Mass change has options for setting a value as well as incrementing, adding a range of values, and appending to values.

  1. Select all batch rows and select Tools menu/Assign BSI IDs. The Assign BSI IDs dialog opens with default parameters which are set in your user profile.
  2. Press the OK button on the Assign BSI IDs dialog. Unique BSI IDs are assigned to the specimen records in your batch.
  3. Prior to commit, data must be in the correct format and not violate any edit checks. Most formatting errors will display instantly in the Data Entry Batch editor. However, to check that the new data does not conflict with existing data, press the Save icon and then press the Check L1 &L2 Errors icon (or select Tools menu/Check L1&L2 Errors).Add_batch_without_errors.png

Did You Know…?

BSI IDs are used as unique identifiers for specimen records and must be assigned. BSI IDs consist of a Sample ID, which represents a collection event and a Sequence, which uniquely identifies a specimen with in the collection event.

Have your own specimen identifiers?

The Current Label field is used to track the barcoded value on the specimen label. Also, you can add custom fields, as needed, to track other specimen IDs. Data Entry Templates can be configured to assign BSI IDs automatically.

  1. If there are no errors in the batch, the data can be committed to the database. Press the Commit icon (or select Tools menu/Commit Batch). The Committing Data dialog will open with a summary of the batch.
  2. Press the OK button and then the OK button on the Committing Batch…notification.

Did You Know…?

Verifiers are configured to ensure batch data are valid, in the correct format and do not conflict with existing data. Verifiers return warnings, to alert the user of a potential issue, or errors to prevent commit.

You will receive a pop-up message and a message in the Messages manager notifying you of the successful commit. The specimen records will appear in the selected Box Layout slots.



The specimen data shown in these box cells are configured for each user from the main Tools menu/User Profile/ Preferences tab. Many other preferences, including default shipping destination or report output type can be set.

Ship Specimens

  1. To record that specimens were shipped out, select the specimens in the box location and right-click on the selection. The RMB menu opens.Ship_speicmens_menu_option.png

Did You Know…?

From the Box Layout or anywhere a BSI ID is listed, right-mouse-button (RMB) shortcuts are available so that you can easily perform tasks on specimens.

  1. Select Ship Specimen… The Ship Task Specification dialog opens with default properties, such as Task Destination, filled in.
  2. Update or fill in additional shipment properties and press the OK button.
  3. Press the OK button on the Ship Successful notification.

The specimens’ Vial Status will be updated to “Out”. If you wish to see the updated box layout immediately, refresh your screen (F5 on the keyboard) and the specimens will be cleared from the box location, making room for additional specimens. A Requisition record is created in the background for later reference.

Did You Know…?

Specimen records are not deleted or retired in BSI. Vial Status values are used to indicate the current specimen status. Some common Vial Statuses include:

  • In – in storage and available
  • Out – shipped out
  • Empty - depleted

Generate a Report

  1. Select the Reports tab to navigate to the Reports manager and press the New button. The Select Report Type dialog opens.
  2. Select User-Defined Listing and press the OK The Report Editor opens.
  3. On the General tab, select an Output Type and enter a Title.

Did You Know…?

BSI offers several canned reports as well as user-defined listing and frequency reports. User defined report output can be displayed on the BSI Client Dashboard.

  1. On the Display tab, select fields to display in the report output. Select the BSI ID, Current Label, Date Entered, Material Type and Vial Status fields by either highlighting the field on the left and pressing the single arrow or double-clicking on a field. The selected fields are added to the Selected Field list.user_defined_report.png
  1. On the Sort tab, specify how the data is sorted by moving fields to the Selected Fields list the same way you selected display fields.
  2. On the Search tab, create search lines to add to the search statement. For this report select Date Entered, the Equals operator, and enter or use the calendar widget to select today’s date in the Value(s) fields.
  1. Once you have constructed a search line, press the Add to Search Criteria button to add the line to the search statement at the button on the editor. Multiple search lines can be added.report_search_criteria.png


This Report Editor Display tab is showing Select Vial Fields. Many other field sets can be chosen from the field list drop-down menu including Shipment, Requisition, Study, User, Subject and Consent fields. Fields from different sets can be displayed and used as search criteria in the same report. Audit history fields are also available for reporting on changes made in BSI.

  1. Press the Run Report button to generate the report output.report_output.png
  2. Save report by pressing the Save Icon on the Report The Save Report dialog opens.
  3. Enter a Name and press the OK The report specification is saved to your report directory so that you can edit and run it later.


Reports can be output to several formats including PDF and comma-delimited formats and saved locally. Each report output contains:

  • The report Title in upper left corner
  • The date generated in upper right corner
  • The BSI Database name
  • The page number in the lower right corner

Creating User Accounts

When you begin exploring BSI, you may want to investigate the various security measures in place to manage what system users can and cannot do or see. You can do that by creating other accounts.

  1. Navigate to the User Administration manager.
  2. Select New.


A few important factors that limit the access of users in BSI include: role permissions, study permissions, repository access, and Access Level.

  1. On the General tab, enter the username for the new account. Manually enter a new password for the account.

  2. On the Contact tab, enter required contact information: First name, Last name, and Email. Enter any other known contact information.
  3. On the Security tab, choose the new account's access privileges: Status, Accessible Repositories, Current Repository, and Role(s).creating_a_new_user_account.png

Did You Know…?

You can assign a random password to a user account when setting it up. Normally, the randomized password will be emailed to the user, but in your demo database this email is not sent.

  1. When assigning roles, use the Privileges button to view the permissions associated with each role assigned to the account.
  2. On the Study Permissions tab, assign the user permissions to complete actions on vials in a specific study. To complete the action a user will need both the study-specific permission and the role permission.


Role permissions in BSI are additive. A user can be assigned multiple roles and will be able to perform a privileged action so long as at least one of their roles grants the corresponding permission.