LSID Substitution Templates: /Documentation

LSID Substitution Templates

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	Any LSID

${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	Any LSID

${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	Any LSID

${RunLSIDBase}
	Expands to	urn:lsid:${LSIDAuthority}:${LSIDNamespace.Prefix} .Run-${ExperimentRun.RowId}
	Where valid	Any LSID

${AutoFileLSID}
	Expands to	urn:lsid:${LSIDAuthority} :Data.Folder-${Container.RowId}-${XarFileId}: See Data object in next section for behavior and usage
	Where valid	Any Data LSID only

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.

LabKey Support

LabKey Support