BSI Engage

Topics:

BSI Engage

BSI Engage provides a web interface to the BSI database through a browser.  BSI users can search for vials, submit shipments & requisitions, and execute custom reports. Unlike BSI Web, BSI Engage users can also create & edit studies, save searches to their web Dashboard, and create frequency searches to add a count of specimens which meet their criteria to a Requisition.


Logging in

  1. To log into BSI Engage, first navigate to the unique URL for your database. If you do not know your database’s BSI Engage URL, contact BSI Technical Support.
  2. Enter your username and password, then select the Login button. If you cannot remember your password or your temporary password has expired, select the Forgot your password? You will be emailed a temporary password, which you can use to login.
  3. Select a repository you would like to login to from the dropdown menu if you have access to multiple repositories. This dialog is skipped for users with single repository or with no repository access.
  4. You will be directed to the Dashboard homepage of BSI Engage.

Logging Out

To log out of BSI Engage, select the Logout button from the upper right corner menu under your name. After 30 minutes of inactivity, you will automatically be logged off and be required to enter your user credentials again to access BSI Engage.engage logging out

Searching

There are four items for which you can search on BSI Engage: specimen, requisitions, shipments, and studies. Each search can be customized to show specific field values via the Columns button.

Any BSI ID, Requisition ID, Shipment ID, or Study ID displayed on any page in BSI Engage will be hyperlinked to the corresponding details page. Valid URLs stored in character fields are also displayed as hyperlinks. Selecting one opens the corresponding URL in a new tab. BSI Engage recognizes links as valid by the inclusion of one of the following prefixes:

  • http://
  • https://
  • www.

The Specimen search tab is the only place to add specimens to your cart. Here you can filter and select criteria to find ideal specimens for requisitioning.

To search:engage searching

  1. Navigate to the Search page, by selecting one of the buttons on the left side menu. Depending on which type of search you want to perform you can choose Specimens, Requisitions, Shipments, or Studies.
  2. Select the type of search you wish to perform using the available buttons: Listing or Frequency.
    • A keyword search can be performed by entering text into the search box then selecting Search.
    • Listing searches will return information for each specimen meeting the search criteria, including a link to more details on the specimen from the BSI ID.
    • Frequency searches will list the number of specimens meeting each possible combination of search criteria. At least 1 criteria must be displayed for a frequency search.
  3. Click in the Select a Field drop down menu. A drop-down list of available fields long with a text box to search on field names will appear.

    • Select values which will be included in your search or type into the text box to filter the available values.
    • A text box will appear for character, numeric, and ID fields. Additionally, ID fields will have a List button, which allows you to paste a delimited list of values to search on. BSI will attempt to normalize pasted values, if possible, and you may select any/all values to import as search criteria.
    • For date fields, two text boxes will allow you to enter a starting date and an ending date for the search.
  4. If desired, select a second field from the search criteria menu and repeat the process.
  5. Select the Columns button, then add, remove, and arrange the columns which are displayed in your search. Select OK when finished. Some options to help you display or hide columns include these options:
    1. Add all Columns – will add all available columns to the Select Display Columns field.
    2. Remove all Columns – will remove all columns from the Select Display field. Note that if no columns are chosen to display, a default set of columns will be displayed on the search page.
    3. Hide empty columns checkbox – when checked will remove any columns that do not have a value on the display page. Note that for exports, selecting Hide empty columns will only hide those columns for which no value is returned for any specimen.
Example – If you select “Material Type” as the field search criteria, you may select both “DNA” and “RNA” to return results with either material type. If you add a second criteria of “Study ID” and select both “Alpha Study” and “Beta Study”, then the results will only include specimens which are either DNA or RNA and which have a Study ID of Alpha Study or Beta Study.

After searching on the Specimen Search page, select any specimens you want to add to your Specimen Cart. The select the green Add to Cart button.

  • From a Listing search, mark the checkbox next to the specimens displayed on the page which you wish to include in your cart.
  • From a Frequency search, enter the number of specimens which meet the criteria you wish to add to your cart in the appropriate box.

Search operators

The following operators are available for character fields:

  • Equals – Returns results which match the search term exactly.
  • Not Equals – Returns all results which do not match any specified search term exactly.
  • Keyword – Returns results which include the keyword and grammatically related terms. (Example: a search on a keyword of ‘Aliquots’ will return data including ‘aliquots’, ‘aliquot’, ‘aliquotting’, etc.)
  • Exclude Keyword – Returns results which do not include the keyword or grammatically related terms. (Example: a search excluding a keyword of ‘Aliquots’ will return data that doesn’t have any of the following: ‘aliquots’, ‘aliquot’, ‘aliquotting’, etc.)
  • Contains – Returns results which contain, but are not limited to, the exact search term entered.
  • Does Not Contain – Returns results which do not contain the exact search term as part of the value.
  • Starts With – Returns results which begin with the entered characters.
  • Ends With – Returns results which end with the entered characters.
  • Has a Value – Returns results where the field has any value.
  • Has No Value – Returns results where the field is blank.

Advanced searching techniques

The following advanced methods can be used when searching on BSI Engage:

  • Field Names – Keyword search on a specific field by typing the field name (This is the table name where the field is found, followed by an underscore and the underscore field name) followed by a colon and the search parameters into the Keyword search box. For example, searching on the term ‘ vial_mat_type:Serum ’ will search for specimens with a Material Type of "Serum".
  • Exact Phrases - Enclose a phrase in double quotes to search for all words in the phrase in the same order. Operators in double quotes are ignored. For example, searching on “ Whole Blood ” will return items which include the entire phrase, not values with partial matches or which aren’t in the same order.
  • Wildcards - Use ? to replace a single unknown character and * to replace zero or more unknown character(s).
  • Fuzziness - Use ~ to search for terms that are similar to, but not exactly like, the search term. For example, ‘ quik~1 ’ matches any term similar to quik with a maximum of 1 change (insertion, deletion, or substitution).
  • Ranges - Use square brackets to search for inclusive ranges and curly brackets to search for exclusive ranges. For example, ‘ vial_thaws: [1 TO 4} ’ will search for specimens with a Thaws value of 1, 2, or 3.
  • Boolean Operators - Use + before a term to require it. Use - before a term to indicate it must not be present. For example, searching on ‘ vial_bsi_id:+AAA000001 -0001 ’ will return all specimens in sample AAA000001 except for the one with sequence 0001
  • Reserved Characters - If you are using reserved characters as part of your search term, you must escape them with a leading backslash. For example, when entering a search for a Subject ID value of ‘ SUB05689-d ’, you would instead need to enter ‘ SUB05689\-d ’  The following are reserved characters:

Engage allows users to retrieve search results for specimen and non-specimen searches with all possible code list values available to search on. This includes the ability to create or save a search and display all search criteria values even if there are no results within that specified search. Carried throughout all related searches, if a value exist but has no data associated with it, it would still be displayed in the search criteria. Users would not see any search results that they are not authorized to see.

By default, this functionality is turned off but can be turned on after contacting IMS to ask for values without corresponding data to be shown.


engage dashboard display

Dashboard

The BSI Engage Dashboard displays relevant news items and any saved searches which you choose to display. Each saved search shows the type of search and the name given to the search, which if selected will open the search in the correct tab.

Selecting the Refresh icon refreshes data in the corresponding search widget. The Delete icon on a search widget will prompt you to specify what will happen to the search: if you want to Remove From My Dashboard – Do NOT Delete, if you want to Delete This Search or if you want to Cancel.

If not all saved searches are displayed on the Dashboard, the Add to Dashboard option is available to add those saved searches, as well as the Show Search option which opens the search in the appropriate tab.


Engage save search

Saving a Search

Initially navigating to a page during a session the default search page will load. After that if you go back to the page, it will reload the previous search from the same session including display fields, sorting, and search criteria. To save your search for later sessions:

  1. Once all search criteria have been added and columns have been arranged, select the Save Search
  2. Enter a name for the search and mark checkboxes, as desired.
    • Show this search on your Dashboard – This will display the search on your BSI Engage dashboard home page, below any previously added saved searches.
    • Make this default search for this page – Each time you navigate back to this search page, either the Specimens, Requisitions, Shipments, or Studies tab, this search will populate.
    • Overwrite an existing search if one with this name exists – This will overwrite an existing search with your current search if it has the same name.
  3. Select Save Search

Once you have at least one saved search for a tab, the Load Search dropdown option will become available in the top right corner of the window. This option allows you to load any previously saved search for the tab. When viewing a saved search, the Edit Search dropdown option will also be displayed, allowing you to rename or delete any saved search for the tab.


Specimen Cart

After adding specimens to your cart from a specimen search, you can view or requisition them by selecting the Specimen Cart button on the left side menu.specimen cart

Specimens selected via a frequency criteria search will be displayed under the Grouped Specimens table. This includes the quantity of requested specimens and the criteria used to request them. Specific specimens selected via a listing search will be displayed under the Individual Specimens table, along with any vial/sample level data the user chooses to display.

An X button is available next to each specimen and specimen criteria group, which will remove that item from the cart entirely. Users may manually update the quantity of specimens to request for a criteria group by entering a new Quantity value and selecting Update Quantities.

Available options include:

  1. Clear Cart – This option removes all specimens from the cart.
  2. Create Requisition – Opens the new requisition page and marks the checkbox to include specimens from the cart by default.
  3. Export CSV – Exports a .csv file listing the individual specimens included on the user’s cart. The file will contain the same columns displayed in the Individual Specimens table of the cart.
  4. Columns – This button allows the user to select which vial and sample fields they want to be displayed for individual specimens listed in their cart. Selected fields and order will be remembered and displayed to the user automatically the next time they view their cart.
    • To set a default arrangement of columns for new users, contact IMS.

Creating a Shipment

engage create shipment
  1. Select the New Shipment (+) button on the left side menu.
  2. Fill in shipment properties, making sure to fill in any required fields, which are marked with an asterisk and shown in red. Custom errors are also shown in red. Warnings will be displayed in blue.
  3. You can select a Data Entry template to associate with the shipment. Select the code list button next to the Template Path field, then select the appropriate template from the available options. The selected template will default fields display order and may default some field values.
  4. You can upload a manifest to the shipment, if desired, by selecting the Browse button and choosing the file to upload.
    • In addition to manifests, you can also upload other attachments via another available field.
  5. Select the Submit Shipment button.
  6. The shipment details page for the newly submitted shipment will open.

There may be a link next to the manifest field which will download a file from BSI Engage. This field can be renamed and the file to download can be specified by administrators. If an additional form must be filled out, or a template should be used for the upload, that document can be attached here.


Shipment Details

engage shipment attachments

From the details page of a particular shipment on BSI Engage, the user has access to 2 tabs which show information specific to the shipment and specimens included in it.

  1. Properties – On this tab, you can view all available properties for the shipment, including the number of vials in the requisition.
  2. Discrepancies – On this tab, you can view all discrepancies associated with the requisition. Discrepancies can be displayed in order by the discrepant field, or by the BSI ID of the discrepant specimen. Here you can submit a suggested resolution to discrepancies by following the steps below:
    1. First, mark the checkboxes next to the specimen(s) or discrepant field which your suggested resolution is for.
    2. Then, enter your suggested resolution in the appropriate text box and select the Save Suggested Resolutions
    3. The resolution will be displayed in the selected items’ “Suggestion” column.
  3. Attachments – On this tab, you can view or download previously uploaded attachments, or upload new attachments.

Shipment Manifests

When creating a new shipment via BSI Engage, a manifest field may be available. Manifests are a special type of attachment field used to submit shipment manifests with an incoming shipment batch. Once submitted, users in the BSI client application may choose to import the manifest to automatically add rows to the shipment batch for each entry in the manifest.

Any type of file may be uploaded to this field, however only .csv, .xlsx, and .txt files may be imported in the BSI client.


Creating a New Requisition

  1. Select the New Requisition (+) button on the left side engage new reqmenu.
    • If any exist, you may be prompted to select from a list of available Requisition Property Templates. These templates determine the property fields available when submitting a new requisition.
  2. Fill in requisition properties, making sure to fill in any required fields which are marked with an asterisk and shown in red. Custom errors are also shown in red. Warnings will be displayed in blue.
  3. You can select a Requisition Task Template to associate with the requisition. Select the appropriate template from the Template ID field’s menu. The selected template will default tasks added to the requisition and default the vials those tasks are applied to by default.
  4. Select one of the following buttons:
    • Save Requisition - the request will be saved for later submission with a status of Pending. A Requisition ID will be assigned. Pending Requisitions will not reserve any specimens from the user’s cart and tasks may not be completed in them. Users can later search for, edit, and submit the requisition.
      1. Submit Requisition - The requisition is submitted to the repository for processing. The user can no longer edit property data. If the checkbox to include specimens from cart was selected, then cart specimens will be reserved for processing in this requisitions.
    • The requisition details page for the newly submitted requisition will open.

    There may be a link next to the attachment field which will download a file from BSI Engage. This field can be renamed and the file to download can be specified by administrators. If an additional form must be filled out or a template should be used for the upload, that document can be attached here.

    Study PIs receive a notification upon requisition submittal and completion of tasks. This notification contains a link to the BSI Engage requisition properties page for that requisition which the PI will be able to view if they have access to BSI Engage and to view requisitions.


    Including Cart Specimens in a New Requisition

    When creating a new requisition, by default the checkbox to include specimens which are currently in your cart is marked. Deselect the checkbox if you don’t want to include those specimens.

    Saving a requisition as Pending does not save the specimens in your cart as

    Note – As in a requisition submitted via the BSI client, if there are no specimens included, then the requisition must have instructions before it can be submitted.


    Requisition Details

    From the details page of a particular requisition on BSI Engage, the user has access to 6 tabs which show information specific to the requisition and specimens included in it.

    Requisition tabs:

    • Properties – On this tab, you can view req detailsall available properties for the requisition, including the number of vials in the requisition.
    • Tasks – On this tab, you can view the properties of each task that has been added to the requisition.
    • Specimens – On this tab, you can view the task statuses of each specimen. There is a task status legend available for reference at the bottom of the page.
      • This tab also includes a Columns button, which allows you to customize the vial, sample, and requisition level fields displayed and the field order. These settings are automatically saved and used each time you visit this tab in a requisition.
      • An Export button is available to export the data displayed into a .csv file.
    • Discrepancies – On this tab, you can view all discrepancies associated with the requisition. Discrepancies can be displayed by the discrepant field or by the BSI ID of the discrepant specimen. Here you can submit a suggested resolution to discrepancies by following the steps below:
      • First, mark the checkboxes next to the specimen(s) or discrepant field which your suggested resolution is for.
      • Then, enter your suggested resolution and select the Save Suggested Resolutions button.
    • Approvals – This tab is only displayed if the user has permission to approve specimens and if there are any approvals needed in the requisition.  You can view all specimens included in the requisition which are pending approval. For each specimen, if you have the appropriate study permission you can enter an Approval Comment value and either approve or deny the specimen’s use in this requisition.
    • Attachments – On this tab, you can view or download previously uploaded attachments or upload new attachments.

    Other tools:

    • Duplicate - This button will allow you to create a new requisition from the existing one. The following options are available
      • Duplicate Entire Requisition – All properties, tasks, and specimens from the highlighted requisition will be copied to the new requisition.
      • Duplicate Properties – All properties and tasks from the highlighted requisition will be copied to the new requisition.
      • Duplicate Specimens – All specimens from the highlighted requisition will be copied to the new requisition.
    • Edit Requisition - This option is only available for pending requisitions. Users may edit the requisition properties and submit the requisition for processing.

    Requisition Manifests

    When creating a new requisition via BSI Engage, a manifest field may be available. Manifests are a special type of attachment field used to submit manifests of existing specimens in BSI to be processed. Once submitted, users in the BSI client application may choose to import the manifest to automatically add existing specimens which match each entry in the manifest.

    Any type of file may be uploaded to this field, however only .csv, .xlsx, and .txt files may be imported in the BSI client.


    Creating a Study

    engage create a study
    1. Select the New Study (+) button on the left side menu.
      • A Study Property Template may need to be selected. The template chosen will default some data and display relevant property fields.
    2. Fill in study properties, making sure to fill in any required fields, which are marked with an asterisk and shown in red. Custom errors are also shown in red. Warnings will be displayed in blue.
      • Toggle the Show/Hide Fields button to see all property fields.
    3. Attachments can be uploaded to the study by selecting Browse and locating the file which you need to upload.
    4. Select the Submit Study button.
    5. The study details page for the newly submitted study will open.

    There may be a link next to the attachment field which will download a file from BSI Engage. This field can be renamed and the file to download can be specified by administrators. If an additional form must be filled out, or a template should be used for the upload, that document can be attached here.


    engage study details attachments

    Study Details

    From the details page of a particular study on BSI Engage, the user has access to 2 tabs which show information specific to the study.

    1. Properties – On this tab, you can view all available properties for the study, including the PI name.
    2. Attachments – On this tab, you can view or download previously uploaded attachments, or upload new attachments to the study.

    Additionally, there is an Edit Study button in the top right corner, if you have permissions to edit the study. There is a View Specimens button next to the Edit Study button. This will open the specimen search page, searching on specimens in the selected study.

    Customization Panel

    The Customization Panel can be used to configure user experiences on the BSI Engage site. Possible customizations include custom site branding, hiding/showing fields for subsets of users, and creating default search displays.

    Detailed instructions on the features available in the Customization Panel are available here:

    Customization Panel Guide