Module-level properties can be specified in two places:
  • 1. module.properties
    • These are fixed property/value strings, shown in the Admin Console.
    • In source, this file is located in the module root at MODULE_ROOT/module.properties.
    • When deployed, this file transformed into XML and is copied to MODULE_ROOT/config/module.xml.
    • Reference link
  • 2. module.xml
    • These are developer-defined properties, where the values can be set by the user in a deployed module.
    • In source, this file is located at /resources/module.xml.
    • When deployed, this file is copied to MODULE_ROOT/module.xml.
    • Supports various user-input types, such as dropdowns, checkboxes, etc.
    • Settings can be applied site-wide or scoped to the current project or folder.
    • Supports permissions to have different values for a given property in different folders.
    • Support hover tool tips.
    • Defines module-level dependencies on libraries and other resources.
    • Reference link.
myModule
│ module.properties
└───resources
│ module.xml
├───...
├───...
└───...

module.properties

The following module.properties file is for a simple file-based module which contains no Java classes to compile:

Name: HelloWorld
ModuleClass: org.labkey.api.module.SimpleModule
Version: 1.0

Modules that contain Java classes should reference their main Java class. For example, the Issues module references the main controller class org.labkey.issue.IssuesModule:

ModuleClass: org.labkey.issue.IssuesModule
ModuleDependencies: Wiki, Experiment
Label: Issue Tracking Service
Description: The LabKey Issues module provides an issue tracker, a centralized workflow system for tracking issues or tasks across the lifespan of a project. Users can use the issue tracker to assign tasks to themselves or others, and follow the task through the work process from start to completion.
URL: https://www.labkey.org/wiki/home/Documentation/page.view?name=issues
Organization: LabKey
OrganizationURL: https://www.labkey.com/
License: Apache 2.0
LicenseURL: http://www.apache.org/licenses/LICENSE-2.0

module.properties Reference

Available properties for modules. Note that property names vary slightly between module.property and module.xml files.

Property Name
(in module.xml)
Property Name
(in module.properties)
Description
classModuleClassMain class for the module. For modules without Java code, use org.labkey.api.module.SimpleModule
nameNameThe display name for the module.
versionVersionThe module version.
requiredServerVersionRequiredServerVersionoooThe minimum required version for LabKey Server.
moduleDependenciesModuleDependenciesA comma-delimited list of other module names this module depends upon. This determines module initialization order and controls the order in which SQL scripts run. For example, suppose your module includes a foreign key to a table in the Experiment module. In this case you could declare a dependency on the Experiment module, so that you can be sure that the target table exists before you try to create your foreign key. LabKey Server will give an error if you reference a module that doesn't exist, or if there's a circular dependency, for example, if ModuleA depends on ModuleB, which itself depends on ModuleA.
supportedDatabasesSupportedDatabasesAdd this property to indicate that your module runs only on a particular database. Possible values: "pgsql" or "mssql".
labelLabelOne line description of module's purpose (display capitalized and without a period at the end).
descriptionDescriptionMulti-line description of module.
urlURLThe homepage URL for additional information on the module.
authorAuthorComma separated list of names and, optionally, email addresses: e.g. "Adam Rauch <adamr@labkey.com>, Kevin Krouse"
maintainerMaintainerComma separated list of names and, optionally, email addresses: e.g. "Adam Rauch <adamr@labkey.com>, Kevin Krouse"
organizationOrganizationThe organization responsible for the module.
organizationURLOrganizationURLThe organization's URL/homepage.
licenseLicenseLicense name: e.g. "Apache 2.0", "GPL-2.0", "MIT"
licenseURLLicenseURLLicense URL: e.g. "http://www.apache.org/licenses/LICENSE-2.0"
vcsRevisionVcsRevisionThis value is set internally by the build, and does not need to be provided by the developer in module.properties. The SVN revision number of the module. This will be displayed next to the module in the site admin console.
vcsUrlVcsURLThis value is set internally by the build, and does not need to be provided by the developer in module.properties. The URL to the SVN server that manages the source code for this module. This will be displayed next to the module in the site admin console.
buildOSBuildOSThis value is set internally by the build, and does not need to be provided by the developer in module.properties. The operating system upon which the module was built. This will be displayed next to the module in the site admin console.
buildPathBuildPathThis value is set internally by the build, and does not need to be provided by the developer in module.properties. The file path in which the module was built. This will be displayed next to the module in the site admin console.
buildTimeBuildTimeThis value is set internally by the build, and does not need to be provided by the developer in module.properties. The date and time the module was built. This will be displayed next to the module in the site admin console.
buildTypeBuildTypePossible values are "Development" or "Production". "Development" modules will not deploy on a production machine. To build modules destined for a production server, run 'gradlew deployApp -PdeployMode=prod', or add the following to your module.properties file: 'BuildType=Production'.
buildUserBuildUserThis value is set internally by the build, and does not need to be provided by the developer in module.properties. The name of the user that built the module. This will be displayed next to the module in the site admin console.
sourcePathSourcePathThis value is set internally by the build, and does not need to be provided by the developer in module.properties. The location of the module source code.
resourcePathResourcePathThis value is set internally by the build, and does not need to be provided by the developer in module.properties.
buildNumberBuildNumberThis value is set internally by the build, and does not need to be provided by the developer in module.properties. The build number.
enlistmentIdEnlistmentIdThis value is set internally by the build, and does not need to be provided by the developer in module.properties. Used to determine whether the module was built on the current server.

Properties Surfaced in the Admin Console

Module properties are surfaced in the user interface at Admin > Site > Admin Console, under the heading Module Information. Click an individual module name to see its properties. If you having problems loading/reloading a module, check the properties Enlistment ID and Source Path. When the server is running in devMode, these properties are displayed in green text if the values in module.xml match the values found the on the server; they are displayed in the red text if there is a mismatch.

The properties for deployed modules are available in the table core.Modules, where they can be accessed by the client API.

Generation of config/module.xml

When you run the standard targets to build LabKey Server, the property/value pairs in module.properties are extracted and used to populate a config/module.xml file (via string substitution into module.template.xml). The resulting config/module.xml file is copied to the module's config subdirectory (MODULE_NAME/config/module.xml) and finally packaged into the built .module file. At deployment time, the server loads properties from config/module.xml, not module.properties (which the server ignores). Note that modules that contain Java code must be built using the standard build targets in the open source project.

module.xml

Properties defined here can be set by users at Admin > Folder > Management > Module Properties tab. This tab is only displayed if an active module has setable properties.

Supported input types are:

  • Text field (Width can be specified.)
  • Checkboxes
  • Dropdowns (Either select from a set list, or a combination that allows either user input or a selection.)
    • Options can either be a static list set at startup, or dynamic at module properties page load.
    • The dynamic list can be container dependent.
    • Other than dynamic dropdowns, all functionality is available to file based modules.
The description can be set to display on the tab and in a hover-over tooltip.

Example module.xml

<module xmlns="http://labkey.org/moduleProperties/xml/">
<properties>
<propertyDescriptor name="TestProp1">
<canSetPerContainer>false</canSetPerContainer>
</propertyDescriptor>
<propertyDescriptor name="TestProp2">
<canSetPerContainer>true</canSetPerContainer>
<defaultValue>DefaultValue</defaultValue>
<editPermissions>
<permission>UPDATE</permission>
</editPermissions>
</propertyDescriptor>
<propertyDescriptor name="TestCheckbox">
<inputType>checkbox</inputType>
</propertyDescriptor>
<propertyDescriptor name="TestSelect">
<inputType>select</inputType>
<options>
<option display="display1" value="value1"/>
<option display="display2" value="value2"/>
</options>
</propertyDescriptor>
<propertyDescriptor name="TestCombo">
<inputType>combo</inputType>
<options>
<option display="comboDisplay1" value="comboValue1"/>
<option display="comboDisplay2" value="comboValue2"/>
</options>
</propertyDescriptor>
</properties>
<clientDependencies>
<dependency path="/simpletest/testfile.js" />
</clientDependencies>
<requiredModuleContext>
<requiredModule name="Core" />
</requiredModuleContext>
</module>

User Settings

A folder or project administrator can see and set module properties by opening the Admin > Folder > Management > Module Properties tab. This page shows all properties you can view or set. If the property can have a separate value per folder, there will be a field for the current folder and each parent folder. If you do not have permission to edit the property in the other containers, the value will be shown as read-only. To see more detail about each property, hover over the question mark in the property name bar.

Related Topics

Discussion

previousnext
 
expand all collapse all