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 keyboard shortcuts.  Using one of these shortcuts copies the command text into the current template cell.  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

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.

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.

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 the 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

Previous Command

In the Template Editor, 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 Freezer field, and the Previous Command is used for the next Freezer field, the value for Freezer will be ‘001’.

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, if entered manually. The keyboard shortcut is Ctrl + I.

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 default field is specimen.bsi_id.  The syntax for the Copy Command is @copy(“fid”), where “fid” refers to the name of the field id in quotes, if entered manually.  The keyboard shortcut is Ctrl + O.

The field id is in the format, 'table.name'. The name of the field can be found by selecting Properties... from the column header of interest and locating Field Name.  For instance, for Study Id, the field name is 'specimen.study_id'.

If the value '@copy(“specimen.study_id”)’ is typed into Current Label,  the value for the Current Label field would be the value from the Study 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), if entered manually. The argument is the name of the field and can be found by locating Field Name from the Properties of the column header.  The keyboard shortcut is Ctrl + U.

For instance, if '@concat( @copy("sample.sample_id"), "001") is typed into Current Label, the value for Current Label would be '[the Sample Id]001'.  Anything typed in quotes shows up as verbatim.

If the syntax '@concat( @copy("sample.sample_id"), " ", "001")' were typed into Current Label, the value for Current Label would be '[the Sample Id] 001' because of the space in quotations.

For the instances where two fields need to be copied and concatenated, the copy function would be needed. The syntax '@concat(@copy(“sample.sample_id”),”  “, @copy("vial.original_id”)’ would yield the Sample Id, followed by a space, and then the Original Id.

This formula is not calculated until after the vial has been committed. Also note that the Today command is not allowed as an argument for this command.

Today Command

In the Template Editor, the Today Command enters today’s date into the field. The syntax for the Today Command is @today(), if entered manually. The keyboard shortcut is Ctrl+T.

The command would be used for any Date fields. For instance, if '@today( ) is typed into Date Drawn, then today’s date would appear, in the format MM/DD/YYYY. 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 the field. The syntax for the Now Command is @now(), if entered manually. The keyboard shortcut is Ctrl + N.

The command would be used for any Date fields. For instance, if '@now( ) is typed into Date Frozen, then today’s date would appear, in the format MM/DD/YYYY, with the current time stamp.

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"), if entered manually. The shortcut is Ctrl+B. The sequence number starts at 0.