The extensive use of LSIDs in LabKey Server requires a system for generating
unique LSIDs for new objects. LSIDs must be unique because they are
used as keys to identify records in the database. These generated LSIDs
should not inadvertently clash for two different users working in
separate contexts such as different folders. On the other hand, if the
generated LSIDs are too complex – if, for example, they
guarantee uniqueness by incorporating large random numbers –
then they become difficult to remember and difficult to share among
users working on the same project.
LabKey Server allows authors of experiment description
files (
xar.xml
files) to specify LSIDs which include substitution
template values. Substitution templates are strings of the form
${<substitution_string>}
where
<substitution_string> is one of the
context-dependent values listed in the table below. When an experiment
description file is loaded into the LabKey Server database, the substitution
template values are resolved into final LSID values. The actual values
are dependent on the context in which the load occurs.
Unless otherwise noted, LSID substitution templates are supported in a
xar.xml file wherever LSIDs are used. This includes the following
places in a xar.xml file:
- The LSID value of the rdf.about
attribute. You can use a
substitution template for newly created objects or for references to
objects that may or may not exist in the database.
- References to LSIDs that already exist, such as
the ChildProtocolLSID
attribute.
- Templates for generating LSIDs when using the ExperimentLog
format (ApplicationLSID,
OuputMaterialLSID, OutputDataLSID).
A limited subset of the substitution templates are also supported in
generating object Name values when using the ExperimentLog format
(
ApplicationName,
OutputMaterialName,
and
OutputDataName).
These same templates are available for generating file names and file
directories (
OutputDataFile
and
OutputDataDir).
Collectively
these uses are listed as the Name/File ProtocolApplication
templates in the table below.
Note:
The following table lists the primitive, single component
substitution templates first. The most powerful and useful substitution
templates are compound substitutions of the simple templates. These
templates are listed at the bottom of the table.
Table: LSID
Substition Templates in LabKey Server
${LSIDAuthority}
|
|
Expands to
|
Server-wide value set on the Customize Site
page
under Site Administration. The default value is localhost.
|
|
Where valid
|
|
|
${LSIDNamespace.prefix}
|
|
Expands to
|
Base object name of object being identified by the LSID;
e.g.,
Material, Data, Protocol, ProtocolApplication,
Experiment, or ExperimentRun
|
|
Where valid
|
|
|
${Container.RowId}
${Container.path}
|
|
Expands to
|
Unique integer or path of project or folder into which
the
xar.xml is loaded. Path starts at the project and uses periods to
separate
folders in the hierarchy.
|
|
Where valid
|
- Any LSID
- Name/File ProtocolApplication templates
|
|
${XarFileId}
|
|
Expands to
|
Xar- + unique integer for xar.xml
file being loaded
|
|
Where valid
|
- Any LSID
- Name/File ProtocolApplication templates
|
|
${UserEmail},${UserName}
|
|
Expands to
|
Identifiers for the logged-on user initiating the
xar.xml
load
|
|
Where valid
|
- Any LSID
- Name/File ProtocolApplication templates
|
|
${ExperimentLSID}
|
|
Expands to
|
rdf:about value of the Experiment
node at the top
of the xar.xml being loaded
|
|
Where valid
|
- Any other LSID in the same xar.xml
- Name/File ProtocolApplication templates
|
|
${ExperimentRun.RowId}
${ExperimentRun.LSID}
${ExperimentRun.Name}
|
|
Expands to
|
The unque integer, LSID, and Name of the ExperimentRun
being loaded
|
|
Where valid
|
- LSID/Name/File ProtocolApplication templates that
are
part of that specific ExperimentRun
|
|
${InputName},${InputLSID}
|
|
Expands to
|
The name and lsid of the Material or Data object that is
the input to a ProtocolApplication being generated using ExperimentLog
format.
Undefined if there is not exactly one Material or Data
object that is
input.
|
|
Where valid
|
- LSID/Name/File ProtocolApplication templates that
have exactly one input, e.g., MaxInputMaterialPerInstance +
MaxInputDataPerInstance = 1
|
|
${InputLSID.authority}
${InputLSID.namespace}
${InputLSID.namespacePrefix}
${InputLSID.namespaceSuffix}
${InputLSID.objectid}
${InputLSID.version}
|
|
Expands to
|
The individual parts of an InputLSID, as defined above.
The
namespacePrefix is defined as the namespace
portion up to but not
including the first period, if any. The namepsaceSuffix
is the
remaining portion of the namespace after the first period.
|
|
Where valid
|
- LSID/Name/File ProtocolApplication templates that
have exactly one input, i.e., MaxInputMaterialPerInstance +
MaxInputDataPerInstance = 1
|
|
${InputInstance},${OutputInstance}
|
|
Expands to
|
The 0-based integer number of the ProtocolApplication
instance within an ActionSequence. Useful for any ProtocolApplication
template that includes a fractionation step. Note that InputInstance
is > 0 whenever the same Protocol is applied multiple times in
parallel. OutputInstance
is only > 0 in a fractionation step in which multiple outputs
are
generated for a single input.
|
|
Where valid
|
- LSID/Name/File ProtocolApplication templates that
are
part of that specific ExperimentRun
|
|
${FolderLSIDBase}
|
|
Expands to
|
urn:lsid:${LSIDAuthority}:
${LSIDNamespace.Prefix}.Folder-${Container.RowId}
|
|
Where valid
|
|
|
|
|
${RunLSIDBase}
|
|
Expands to
|
urn:lsid:${LSIDAuthority}:${LSIDNamespace.Prefix}
.Run-${ExperimentRun.RowId}
|
|
Where valid
|
|
|
${AutoFileLSID}
|
|
Expands to
|
urn:lsid:${LSIDAuthority}
:Data.Folder-${Container.RowId}-${XarFileId}:
See Data object in next section for behavior
and usage
|
|
Where valid
|
|
Common Usage
Patterns
In general, the primary object types in a Xar file use the following
LSID patterns:
Experiment, ExperimentRun, Protocol
These three object types typically use folder-scoped LSIDs that look
like
${FolderLSIDBase}:Name_without_spaces
In these LSIDs the object name and the LSID’s objectId are
the same except for the omission of characters (like spaces) that would
get encoded in the LSID.
ProtocolApplication
A ProtocolApplication is always part of one and only one ExperimentRun,
and is loaded or deleted with the run. For ProtocolApplications, a
run-scoped LSID is most appropriate, because it allows multiple runs
using the same protocol to be loaded into a single folder. A run-scoped
LSID uses a pattern like
${RunLSIDBase}:Name_without_spaces
Material
Material objects can be divided into two types: starting Materials and
Materials that are created by a ProtocolApplication. If the Material is
a starting material and is not the output of any ProtocolApplication,
its scope is outside of any run. This type of Material would
normally have a folder-scoped LSID using ${FolderLSIDBase}. On the
other hand, if the Material is an output of a ProtocolApplication, it
is scoped to the run and would get deleted with the run. In this case
using a run-scoped LSID with ${RunLSIDBase} would be more appropriate.
Data
Like Material objects, Data objects can exist before any run is
created, or they can be products of a run. Data objects are also
commonly associated with physical files that are on the same file share
as the xar.xml being loaded. For these data objects associated with
real existing files, it is important that multiple references to the
same file all use the same LSID. For this purpose, LabKey Server provides the
${AutoFileLSID} substitution template, which works somewhat differently
from the other substitution templates. An ${AutoFileLSID} always has an
associated file name on the same object in the xar.xml file:
- If the ${AutoFileLSID} is on a starting Data object, that
object also has a DataFileUrl element.
- If the ${AutoFileLSID} is part of a
XarTemplate.OutputDataLSID parameter, the XarTemplate.OutputDataFile
and XarTemplate.OutputDataDir specify the file
- If the ${AutoFileLSID} is part of a DataLSID (reference),
the DataFileUrl attribute specifies the file.
When the xar.xml loader finds an ${AutoFileLSID}, it first calculates
the full path to the specified file. It then looks in the database to
see if there are any Data objects in the same folder that already point
to that file. If an existing object is found, that object’s
LSID is used in the xar.xml load. If no existing object is found, a new
LSID is created.