Templates

Topics:

Data Entry Templates

The Templates tab allows users to utilize a manager and editor to create data entry templates that provide default values for new vials. Templates can contain single or multiple lines to handle sets of vials that are expected to arrive together. In addition to storing literal text, there are several template commands or functions which can also be used for providing default values for fields. Users must have permission to access this module. A Standard Template History report is available in the History folder, including visible/hidden columns, default values, Limit Selection, and other changes made. 

Templates are stored in a hierarchical directory structure. All users can view and use any other user’s templates. Users can save templates in their own directory or the institution directory, depending on role permissions. A local administrator can also save templates in any directory belonging to their institution. Templates can be used for several purposes in BSI, including:

  • Defaulting data and arranging field order in a shipment or a Data Entry add batch
  • Arranging field order in a Data Entry modify batch or a Modify requisition task
  • Setting a Requisition Column View Template
  • Generating Sample Data
  • Generating Specimens
  • Fresh processing when transferring specimens from a shipment to a Data Entry batch prior to committing them
  • Generating children in an Aliquot, Process, or Pool task.

The manager consists of a directory control on the left side and action buttons on the right. Using this interface, you can:

  • Create a new template by pressing the New button to open the Template editor.
  • View an existing template by selecting the template and pressing the View button.
  • Edit an existing template by selecting the template and pressing the Edit button. After making any desired changes, click the editor’s Save button. Users will be prompted for the template’s name. Leaving the name the same will overwrite the existing template (this will not be allowed if it belongs to someone else). Entering a new name will save the template as a new template with the given name.
  • Delete a template by selecting a template and pressing the Delete button.

The Template editor allows you to create new templates and edit existing ones. Users can create a template of a single line or of multiple lines. Shortcuts specific to adding new commands are listed in the dialog. Required fields are noted in the column header via red text and an asterisk in front of the field name. Requisition-specific fields are noted with "(req)" at the end of the field name.

The editor contains the following sections and buttons:

  • Description - This optional, free-text field can contain any description a user finds useful.
  • Commands - Lists common template commands and their purposes.  Clicking on the Syntax value copies the command text, which can be pasted into the cells in the Template table.  Users can also type the value by hand. The following commands are available:
    • Previous Command
    • Increment Command
    • Copy Command
    • Concatenate Command
    • Today Command
    • Now Command
    • Next BSI Id Command

Example: Marie is a BSI user responsible for data entry. She found that the process of entering data for each sample to be very tedious and worried that she might make errors. Fortunately, her coworker Antoine knew how to make Marie’s job easier by showing her how to create and use templates. Since Marie gets three specimens per subject and each have several qualities in common such as Material Type, Study ID, and Volume, these fields could be defined in the template. When Marie starts a new Data Entry batch, she selects her template and sees that the pre-defined values are correctly auto-populated under the field headings.

Value table - The main component of the editor, this shows the template’s lines. These fields are edited much like those in the Data Entry editor.

Close button - Closes the template. If a user has made changes, they will be prompted to save.

Save button - Saves the template without closing the editor.

Insert button - Inserts a row above the currently selected row in the template.

Delete button - Deletes the currently selected row or rows from the template.

Print button - Prints the contents of the template.

Select Rows button - Opens the Specify Rows to Select dialog that can be used to select rows in the Value table.

Hide/Show Columns button - Opens the Standard Selection Dialog to allow users to choose the default field display for batches using this template. This has no effect on the data that the template provides; default values can be (and often are) given for fields that are hidden.

Limit Selection - For fields that have an associated code list, this option will exist in the right mouse button menu. It allows users to specify which items from the code list will, by default, be shown for the chosen column when using the template. Users can view all codes in the associated code list by unchecking the checkbox labeled Show Limited Selection on the Select Codes dialog.

Automatically Assign Locations - This checkbox will automatically save new Data Entry batches and open them to reserve locations after batch properties have been confirmed.

Multi-line Templates

A multi-line template generates multiple specimen records for each record brought into a Data Entry or Shipment batch. For example, if the template contains 5 lines and 20 records are imported into a batch, 100 specimen rows are generated.

Like single line templates, multi-line templates can contain literal text as well as template commands or functions which to provide default values for each of the records generated.

Records can be added to a multi-line template batch by importing a file, by transferring records from a Shipment batch, and via the Generate Through tool.

Multi-line templates are used to generate data under various circumstances such as when receiving fresh specimens that are to be processed prior to storage, or when entering specimens with an electronic file containing only Sample data.

For instance, multi-line templates could be used for whole blood samples that are collected for a study and are routinely processed into certain component material types prior to storage.

The template can be used to transfer received vials from a shipment batch into a data entry batch. The shipment batch contains records for the whole blood specimens and the data entry batch contains the generated data for all possible specimens created from the whole blood. Once generated, the specimen records can be modified or deleted as needed. The template contains commands and text to generate default values for the specimen records as well as defines what columns are visible in the Data Entry Editor.

Template Commands

Choose one of the tabs below to learn more about each template command:

Previous Command

The Previous Command copies values from the previous row. The syntax for the Previous Command is ‘@prev()’, if entered manually. The shortcut is Ctrl+P.

For instance, if the value '001' is typed into the Subject ID field, and the Previous Command is used for the next Subject ID field, the value for that Subject ID will be ‘001’.

Previous command used in a template

previous command used in a data entry batch

In a single line template, the value for the field with Previous Command in the first row is blank but as more rows are added after entering value in first row, the value is copied down.

This command is useful in muti-line templates where the value may be entered for first row in the batch and previous command will copy it down to other rows.

Increment Command

In the Template Editor, the Increment Command increments the value from the previous row by the specified number. If no number is added, the default value is 1. The syntax for the Increment Command is @incr(#), where # refers to how much of an increment is needed.

For instance, if the value '001' is typed into Row, and the Increment Command is used for the following Row field as @incr(2), the value for the second Row field would be ‘003’.

Copy Command

In the Template Editor, the Copy Command copies a value from a sample or specimen field (fid) from this specimen. The example listed in the Description is @copy( "vial.bsi_id" ).  The syntax for the Copy Command is @copy(“field name”), where “field name” refers to the name of the formal name of the field in quotes.

The field name is in the format, "table.name". The name of the field can be found by hovering over the column header of interest and locating Field Name.  For instance, for BSI ID, the field name is 'vial.bsi_id'.

If the value '@copy(“vial.bsi”)’ is typed into Current Label, the value for the Current Label field would be the value from that row's BSI ID.

Concatenate Command

In the Template Editor, the Concatenate Command concatenates all the arguments into one value. The syntax for the Concatenate Command is @concat(arg1, arg2, …, argn). Arguments can include BSI field names, text, or other template commands. BSI field names can be found by hovering over the column header of interest and locating the Field Name.

Arguments will not include spaces or other punctuation unless it is specified within the template. For instance, if @concat( @copy("sample.sample_id"), "ABC") is typed into Current Label, the value for Current Label in a row where the Sample ID is "AAA000000" would be "AAA000000ABC".  Anything typed in quotes shows up verbatim.

If the command @concat( @copy("sample.sample_id"), " ", "ABC") were typed into Current Label, the value for Current Label would be "AAA000000 ABC" because of the space in quotations. 

For the instances where two field values need to be copied and concatenated, the copy function would be needed. The command @concat(@copy(“sample.sample_id”),”  “, @copy("sample.subject_id”) would yield the Sample ID, followed by a space, and then the Subject ID.

This formula is not calculated until after the batch has been committed. Also note that certain commands, such as Today and Now, are not allowed as an argument for the Concatenate command.

Today Command

In the Template Editor, the Today Command enters today’s date into a date field. The syntax for the Today Command is @today().

For instance, if @today( ) is typed into Date Drawn, then today’s date would appear. If the Date field normally has a time stamp, then '00:00' would follow the date.

Now Command

In the Template Editor, the Now Command enters today’s date and the current time into a date field. The syntax for the Now Command is @now().

BSI ID Command

In the Template Editor, the Next BSI ID Command automatically generates the next BSI ID for the Sample ID in the command. The command will not show up in Incoming Shipment batches. The syntax for the Next BSI ID Command is @nextbsiid("sample ID"). The sequence number starts at 0 when no value is specified in the Sequence field.