Each sample in the system must have a unique name/id within it's Sample Type. The unique sample names can be provided by the user, or can be generated by the system. When you ask the system to generate names, you specify a naming pattern to use. For each type of sample, you will choose one of these two options. If you already use a unique naming structure outside the system, you will want to ensure those names are carried in to LabKey Sample Manager.

Unique Sample Names are Provided

If your data already includes the unique sample names to use, identify the column name that contains them.

Naming Column is "SampleID" or "Name"

If the name of this column is "SampleID" or "Name", these default column names are automatically recognized as containing sample names. To confirm that they are used, be sure to Delete the default naming pattern that is provided in the user interface (and ignore the grayed out placeholder text that remains).

Naming Column is Something Else

If the column containing unique sample names is named something else, you provide that column name using a simple naming pattern expression that specifies the name of the column to use, rather than an expression to generate one.

For example, if the sample names are in a column named "Identifier", you would enter the naming pattern:


Note that while this is entered as a naming pattern, it does not generate any portion to make the sample names unique.

Generate Names with Naming Patterns

If your data does not already contain unique names, the system can generate them upon import using a naming pattern that contains tokens, including counters to ensure names are unique. The system can build a unique name from syntax elements, such as:

  • String constants
  • Incrementing numbers
  • Random numbers
  • Dates and partial dates
  • Values from columns in the imported data, such as tissue types, lab names, subject ids, etc.
  • Separators such as '_' underscores and '-' hyphens
    • Note that if you use a hyphen '-', you will want to use double quotes when you later search for your samples. An unquoted search for Sample-11 would interpret the hyphen as a minus sign and seek pages with "Sample" without "11".

Default Naming Pattern

The default naming pattern in Sample Manager generates names from two elements: the prefix "S-" plus an incrementing integer.


The first few names would be:

and so on...

Date Based Naming

Another possible naming pattern for samples is:


This three-part pattern will generate an incrementing series of samples for each day.

  1. The S- prefix is simply a string constant with a separator dash. Using separators like "-" and "_" is optional but will help users parse sample names.
  2. The now:date token will be replaced by the date of sample creation.
  3. The dailySampleCount token will be replaced by an incrementing counter that resets daily.
In this example, samples added on November 25, 2019 would be "S-20191125-1, S-20191125-2, etc.". Samples added on November 30 would be "S-20191130-1, S-20191130-2, etc".

Incorporate Column Values

If you want to use a column from your data as part of the name, but it does not contain unique values for all samples, you can incorporate it in the pattern by using the column name in token brackets. For example, if you want to have an incrementing series of samples for each participant, and the participant identifier is in a "ParticipantID" column, you would use the pattern:


Multiple column names can be included in a naming pattern.

Naming Pattern Elements/Tokens

The following elements, or "tokens" are available for building naming patterns.

Name ElementDescriptionScope0000000000000000000000000
genIdAn incrementing number starting from 1. This counter is specific to the individual Sample Type.Current Sample Type
dailySampleCountAn incrementing counter, starting with the integer '1', that resets each day.All Sample Types in the current folder
weeklySampleCountAn incrementing counter, starting with the integer '1', that resets each week.All Sample Types in the current folder
monthlySampleCountAn incrementing counter, starting with the integer '1', that resets each month.All Sample Types in the current folder
yearlySampleCountAn incrementing counter, starting with the integer '1', that resets each year.All Sample Types in the current folder
randomIdA four digit random number for each sample row. Note that these random numbers are not guaranteed to be unique.Current Sample Type
batchRandomIdA four digit random number applied to the entire set of incoming sample records. On each import event, this random batch number will be regenerated.Current Sample Type
nowThe current date, which you can format using string formatters.Current Sample Type
InputsA collection of all DataInputs and MaterialInputs for the current sample. You can concatenate using one or more value from the collection.Current Sample Type
DataInputsA collection of all DataInputs for the current sample. You can concatenate using one or more value from the collection.Current Sample Type
MaterialInputsA collection of all MaterialInputs for the current sample. You can concatenate using one or more value from the collection.Current Sample Type
<SomeDataColumn>Loads data from some field in the data being imported. For example, if the data being imported has a column named "ParticipantID", use the element/token "${ParticipantID}"Current Sample Type

Formatting Values

You can use formatting syntax to control how the tokens are added. For example, "${genId}" generates an incrementing counter 1, 2, 3. If you use a format like the following, the incrementing counter will have three digits: 001, 002, 003.


Learn more about formatting numbers and date/time values in this topic: Date and Number Formats Reference

Additional string modifiers are available. Find a list in this topic: String Expression Format Functions

Default Values

When you are using a data column in your string expression, you can specify a default to use if no value is provided. Use the defaultValue modifier with the following syntax. The 'value' argument provided must be a String in ' single quotes.


Incrementing Sample Counters

The sample counters are incremented for the date when the sample is inserted, but can use a different date by attaching the counter to a date column. For example, ${SampleDate:dailySampleCount} will use the date found in the row's "SampleDate" column or today's date if the column has no value.

Some auto-incrementing counters calculate the next value based on all samples in a given container, while others calculate based on only the current Sample Type. See the Scope column for the specific incrementing behavior. When the scope is container-based, within a given Sample Type, values will be sequential but not necessarily contiguous.


Naming PatternExample OutputDescription
S- + a simple sequence
The originating Lab + a simple sequence. If the Lab value is null, then use the string 'Unknown'.
S- + the current date + "-" + daily resetting incrementing integer
Create an id from the letter 'S' and two values from the current row of data, separated by dashes.

Example String Modifiers

The following naming patterns show usage of string modifiers.

Naming Pattern00000000000000000000000000000000000000000000000Example Output000000000000000000Description
${Column1:defaultValue('S')} means 'Use the value of Column1, but if that is null, then use the default: the letter S'
${DataInputs:first:defaultValue('S')} means 'Use the first DataInput value, but if that is null, use the default: the letter S'
${DataInputs:join('_'):defaultValue('S')}-${Column1}Nucleotide1_Nucleotide2-1${DataInputs:join('_'):defaultValue('S')} means 'Join together all of the DataInputs separated by undescores, but if that is null, then use the default: the letter S'

Related Topics

expand all collapse all