Modules: Domain Templates

 2024-04-18
A domain template is an xml file that can be included in a module that specifies the shape of a Domain, for example, a List, Sample Type, or DataClass. An example template xml file can be found in our test module:

test/modules/simpletest/resources/domain-templates/todolist.template.xml - link to source

A domain template includes:

  • a name
  • a set of columns
  • an optional set of indices (to add a uniqueness constraint)
  • an optional initial data file to import upon creation
  • domain specific options
The XML file corresponds to the domainTemplate.xsd schema.

While not present in the domainTemplate.xsd, a column in a domain template can be marked as "mandatory". The domain editor will not allow removing or changing the name of mandatory columns. For example,

<templates
    xmlns="http://labkey.org/data/xml/domainTemplate"
    xmlns:dat="http://labkey.org/data/xml"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <template xsi:type="ListTemplateType">
        <table tableName="Category" tableDbType="NOT_IN_DB" hidden="true">
            <dat:columns>
                <dat:column columnName="category" mandatory="true">
                    <dat:datatype>varchar</dat:datatype>
                    <dat:scale>50</dat:scale>
                </dat:column>
            </dat:columns>
        </table>
        <initialData>
            <file>/data/category.tsv</file>
        </initialData>
        <options>
            <keyCol>category</keyCol>
        </options>
    </template>
</templates>

All domains within in a template group can be created from the template via JavaScript API:

LABKEY.Domain.create({
  domainGroup: "todolist",
  importData: false
});

Or a specific domain:

LABKEY.Domain.create({
  domainGroup: "todolist",
  domainTemplate: "Category",
  importData: false
});

When "importData" is false, the domain will be created but the initial data won't be imported. The importData flag is true by default.

When "createDomain" is false, the domain will not be created, however any initial data will be imported.

A domain template typically has templates with unique names, but it is possible to have a template with the same name of different domain kinds -- for example, a DataClass template and a Sample Type template named "CellLine". In this situation, you will need to disambiguate which template with a "domainKind" parameter. For example,

LABKEY.Domain.create({
  domainGroup: "biologics",
  domainTemplate: "CellLine",
  domainKind: "SampleType",
  createDomain: false,
  importData: true
});

Related Topics