Template Files Associated With Automations

When Clarity LIMS is running scripts via the External Program Plugin mechanism, it is not uncommon for these scripts to rely upon a file that contains information germane to the script. A common example would be using the sample input file generator script that is part of the Lab Instrument Toolkit. This script merges runtime information within a Clarity step into a file whose format is directed by a 'template' file.

Old Methods (all versions)

Under the old method, template files must be saved to a folder accessible to the automation worker node. Typically

/opt/gls/clarity/customextensions/folderName/templateFileName

If a script needs a template file, the file is specified by including its full path in the syntax that invokes the script.

Advantages

A single template file might be associated with many automations. If the template file needs a minor update, the update can be made in one place. You do not need to update the individual automations.

Disadvantages

Creating a template file is typically an iterative process: create the file, run the script, examine the output, tweak the template file, run the script, examine the output, tweak the template file, and so on.

The file must live on the server to be accessed by the script. Therefore, the developer needs access to the server filesystem—or must go through a trusted party to get the file to the server. This process inhibits rapid development and testing.

Methods (Clarity LIMS v5.1 and later)

As of Clarity LIMS v5.1, template files can (optionally) be attached directly to an automation via the GUI.

Advantages

The iterative process—create file, run script, examine output, tweak template file, run script, examine output, and so on— is much faster because the template file can be replaced via the GUI in a matter of seconds.

If the workflow is being validated, the validator can download and inspect the template file directly from the GUI. There is no need to gain access to the server filesystem.

Disadvantages

Because a single template file is associated with a single automation, a template file with common contents can be duplicated and associated with many automations. If the template needs modification, it must be modified in many places.

When configuration that involves template files is migrated from one Clarity LIMS system to another using the config-slicer tool, the template files themselves are not migrated. After the config-slicer has done its work, the administrator must update the automations in the Clarity LIMS GUI, reuploading and associating the template files. If these steps are not done correctly, the syntax invoking the scripts breaks because the required files are not present on the destination system.

Because a template file is associated with a specific automation, the system allows for multiple automations associated with template files that all have the same name for the template file. While this configuration is not a problem in itself, it can cause problems. For example, if converting from the new method to the old method, you might have multiple template files with the same name but different contents. These files cannot be copied to /opt/gls/clarity/customextensions/ because they overwrite each other. Instead, each one needs to be placed in a distinct folder: /opt/gls/clarity/customextensions/folderName/. (See later why you might want to convert from new method to old.)

Template files can be easily edited and overwritten by an administrator. This interaction might be undesirable in a validated environment. It might be safer if the templates files are harder to reach, and thus not available for inadvertent modification.

Which Method to Use

We recommend that you use a combination of both methods, as follows.

Use the embedded template while developing the template. During this process, having the template file easily available for editing is helpful. After the template is finalized, move it to the server and adjust the automation command line to use the server path/filename instead of the file token.

This method allows for easy, iterative testing and precise traceability for production work. This method also facilitates reliable migrations involving the config-slicer tool and coordinated movement of associated /customextensions/ files.

Config-slicer does not currently migrate automations that need template files without additional manual manipulation after the configuration migration. Regardless of method, you must manipulate the system manually to complete the migration of the template files.