Extending SND Tables

2024-03-28

Extending SND Tables

Each Structured Narrative Dataset (SND) table is created as an extensible table, meaning additional columns can be added to customize the table for particular use cases. For example, for a Primate Research Center a USDA code is needed with each package. This column is not in the base SND table but can be added as a virtual column for the PRC’s implementation of the SND module.

Setup

Adding additional columns is done by defining the columns in XML format, then calling an action to upload and create those columns. To do the initial setup, keep reading, otherwise you can skip to step 5 to add or adjust the columns.

There is not currently a general-purpose UI trigger to call that action and identify which XML file to upload, so each implementation will have to add a button or some kind of trigger to initiate the action. Here are the steps to set up the action and XML file.

1. Declare a module dependency on the SND module in <module_root>/module.properties.

2. Create a <module_root>/resources/domain-templates directory in your module.

3. Create an XML file in the domain-templates directory to define the extensible columns. The file must have the name format <file name>.template.xml, where name can be any valid file name and should be unique for the .template.xml files in that module.

4. The action that will need to be called to upload and create the additional columns is LABKEY.Domain.create. In the module using the SND module, create a button or some other event trigger and set the action to call LABKEY.Domain.create. The JavaScript function should look something like this.

createDomain: function () {
LABKEY.Domain.create({
module: <name of your module>,
domainGroup: <file name>, // This is the name defined in step three.
domainKind: "SND",
importData: false, // Not importing data into new columns
success: this.successFn, // Function called after columns successfully uploaded.
failure: this.failureFn, // Function called if there is an error in the upload.
// Exception passed as parameter
});
}

5. Add your column definitions to the template XML file. The XML for this file is defined in domainTemplate.xsd and tableInfo.xsd. See test.template.xml in the SND module and snd.template.xml in the SNPRC module for examples. Template documentation can be found here.

6. When your column definitions are ready, click the button to create the domains. The entire XML file (may include multiple tables) will be uploaded and the virtual columns will be added, removed or edited based on the prior state of the tables.

Technical Details

Each SND table has a DomainDescriptor, which provides table level metadata about the SND table and allows it to be linked to a set of PropertyDescriptors. The PropertyDescriptor table contains the column level metadata which can define new columns or supplement existing columns. While the actual data stored in these columns can be stored in any table, this implementation stores the data in an existing table, ObjectProperty. This table is a generic data storage table in the exp schema which essentially just stores the name, value and data type for each row of data.

Related Topics