Turning Container Name Uniqueness ON

This constraint is set at the database level. Container Uniqueness can be turned ON by using the migrator tool, and running the optional migration step called "ContainerNameUniqueConstraints". This can be done by calling this command:

Notes:

• Of course, edit the migrator.properties file to ensure that the mode is set to "migrate" not just "validate".

• If the migrator has carried out its work successfully, the database should now have a new index present called 'unique_cnt_name'. (In psql, do \di to see indexes)

• You do not need to restart Tomcat services in order for this change to take effect

Turning Container Name Uniqueness OFF

Container Uniqueness can be turned OFF by running this SQL command:

Copy

This statement will fail if there are already any non-unique container names in the database. If it fails, you can find all non-unique names with this statement:

Copy

For each non-unique name found, you can iterate through all instances of it, and rename them so that they will be unique.

Copy

Copy

Resolving Non-Unique Container Names

When you run the above query and determine there are too many containers to hand-edit, what now?

1. Are any of the containers that have non unique names in a depleted or discarded state? If so, you can probably delete them once the customer gives the all clear:

Copy

now, what do the values for the container stateid mean? You won't find them in the database, they are hard coded as follows

Copy

Copy

Copy

Copy

Copy

Copy

Copy

Copy

Copy

Armed with this knowledge, we can refine the query to highlight containers that may be deleted with little consequence:

Copy

Copy

Copy

Notes:

1. Containers can only be deleted if they are empty

2. SQL 'IN' statements normally have a limit of 255 records, so if the the sub-select - the one in parenthesis - returns more than 255 records, your mileage may vary

This section provides information and instructions to support Clarity LIMS and administration tasks. Topics covered include

• Database Cleanup

• LDAP Integration

If you require assistance with Clarity LIMS administration, contact the Illumina Support Team.

You can configure an alias for the short and long, singular, and plural forms of the term Project, as displayed in the Clarity LIMS interface.

Configuration Tool and Properties

Renaming is achieved by configuring the following properties, using the omxprops-ConfigTool.jar tool at:

Copy

/opt/gls/clarity/tools/propertytool 

Properties

• clarity.alias.project.short.singular - The short term for "Project"

• clarity.alias.project.short.plural - The short term for "Projects"

• clarity.alias.project.full.singular - The full term for "Project"

• clarity.alias.project.full.plural - The full term for "Projects"

Rules for alias

• clarity.alias.project.short.singular—Maximum of eight characters.

• clarity.alias.project.short.plural—Maximum of nine characters.

• If multiple words are used, capitalize each word (eg, Test Requests).

If you use, or would like to use, an LDAP server to consolidate directory services, it is possible to integrate LDAP with Clarity LIMS.

The Clarity LIMS LDAP solution allows for the following features:

• User name and password authentication against LDAP to govern access to Clarity LIMS.

• Ongoing unidirectional synchronization of user information (such as first name, last name, title, phone, fax, and email) from LDAP to Clarity LIMS. For example, if your telephone number is changed in the LDAP directory, the information is pushed down to Clarity LIMS, keeping contact information current.

After initial user training, but before the lab starts to use Clarity LIMS in production, a database cleanup is recommended.

This process removes any projects, samples, workflows, protocols, steps, and other artifacts from the system that were created during training but are not needed for production.

Contact the Clarity LIMS Support team to schedule a time for this cleanup procedure.

Preparation

This section explains how to use the LDAP Checker tool a script (ldap-checker.jar) that checks and reports on an LDAP configuration. Instructions for use are also provided in the README.txt file that accompanies the tool.

The ldap-checker script is included with the Clarity LIMS installation and is available at the following location:

/opt/gls/clarity/tools/ldap-checker

The ldap-checker script performs numerous checks of the LDAP configuration and reports on any incorrect items found.

Script Properties

Point the script to one or more files containing (at a minimum) the database connection properties. Alternatively, set these properties from the command line.

The script loads properties from the following sources and in the following order:

1. Any JDBC properties files specified with -f (see the table for options).

   If multiple properties files specify the same property, the last file is used.

2. Any Java system properties specified on the command line using

   Properties specified on the command line are only checked if they do not appear in the properties files.

After the script has the basic database connection properties, it loads further settings from the corresponding Clarity LIMS database.

The following JDBC properties are required:

• jdbc.driverClassName

• jdbc.url

• jdbc.username

• jdbc.password

Options:

Run the Script

1. Change to the directory containing ldap-checker tool:

2. Run the script. To specify a properties file, use the following example:

Example Properties File

The tool includes an example database.properties file. This example shows a properties file that is specified with the -f option.

The following options are available:

• Edit this file and use it.

• Provide properties on the command line, using: -D.

  For example:

Examples

Example 1: Using SSL

Specify and provide the path to the keystore:

Example 2: Checking Users

To check a set of specific users (even those that have not been provisioned), use the following script:

Overriding Properties

To override properties that are typically loaded from the properties table, use command-line system properties or one or more properties files.

Using system property ( -D options must be specified before the -jar option):

Using multiple properties files:

• In this example, Custom-ldap.properties might resemble the following:

If running Config Slicer v3.0.x against a configuration package or manifest file that was generated with a pre-3.0 version of Config Slicer, an error message displays.

Scenario 1: Out-of-Date Configuration Package

In this scenario the error message will resemble the following:

Copy

SOLUTION:

Upgrade the configuration package file by running upgrade-config-slice.jar against it.

Clarity LIMS provides Audit Trail, a robust data-tracking system that allows for tracking of the following:

• All user activity (ie, who did what, and when).

• Every action that is written to the database.

Audit Trail has two capture systems, Event Log and Detail Log.

• Event Log—Records familiar BaseSpace Clarity LIMS user actions and presents this information in a format that is easy to read and understand.

• Detail Log—Records exacting information about changes resulting from actions recorded in the Event Log. This includes both updated values and previous values.

Enabling Audit Trail may result in a small performance hit due to the overhead of writing the entries to the database. It is recommended that you periodically archive the Audit Trail database so that it does not become too large.

NOTE: Audit Trail is enabled by default.

Introduction

Clarity LIMS creates various log files to help with the resolution of issues. During support request investigation, the Support team may ask for the following types of log files:

• Automation Worker Log File

Automation Worker log file

Automation Worker creates history and log files, and stores them on laboratory computers in the logs folder of the Automation Worker installation directory.

Windows

If Automation Worker is installed on a Windows machine using the program default, find the logs folder at the following location:

Linux

If Automation Worker is installed on a Linux server, find the \logs folder at the following location:

The following log files are available:

• wrapper.log - This log file outputs information on the starting, running, and stopping of the Automatic Informatics service.

• automatedinformatics.log - This log file outputs messages from installed plug-ins, such as automation commands and ADC directory scans.

To monitor the automatedinformatics.log:

• Log on to the server using the glsai user ID and run the following command:

If the Automation Worker is installed on a server other than the Clarity LIMS server, use the appropriate user credentials.

Browser HTML and JavaScript Logging

In the web browser, if the LIMS interface does not display items/elements correctly, provide the information and error messages to the Clarity LIMS Support team.

Instructions for finding error messages within the browser console are described in the following sections.

Google Chrome

To Start the Chrome Console:

1. Right-click on an element in the browser and select 'inspect element.'

   A sub window opens below the main window in Chrome, showing the source HTML.

2. Select the Console tab, and reload the troublesome page - any JavaScript errors will be reported there. Include these errors in the Support Request ticket.

NOTE: Between stages in a protocol step you may see errors of the following type:

Such messages are expected. This is the EPP trigger checking that there is no EPP transition to fire on the page change. (This can be annoying for debug purposes, but feel free to include these in the Support Request ticket.)

To Get the JavaScript version:

1. Open up the Console as described in the previous section.

2. Go to the Network tab.

3. Select 'scripts' from the options listed at the bottom of the tab.

   A script named isis-all.js?v=XXXXX displays.

FireFox

To Start the FireFox Console:

1. Right-click on an element in the browser and select 'inspect element.'

   A sub window opens below the main window in Firefox, showing the source HTML

2. Select the Console tab, and reload the troublesome page - any JavaScript errors will be reported there. Include these errors in the Support Request ticket.

NOTE: Between stages in a protocol step you may see errors of the following type:

Such messages are expected. This is the EPP trigger checking that there is no EPP transition to fire on the page change. (This can be annoying for debug purposes, but feel free to include these in the Support Request ticket.)

To Get the JavaScript version:

1. Open up the Console as described in the previous section.

2. In the Filter options Search box and type 'isis'.

   A script named isis-all.js?v=XXXXX appears.

3. Hover over this script with your mouse to find the V (version) build number.

Using Log Files for Troubleshooting Purposes

If you are experiencing problems and need to submit a support request, use the following guidelines to determine which log files to send to the Clarity LIMS Support team:

• basespace-lims-*.log: Include if experiencing slowness in the application. (Default path: /opt/gls/clarity/tomcat/current/logs/)

• automatedinformatics.log: Include if you are experiencing problems with an integration or if a process using an EPP string does not work as expected. (Default path: /opt/gls/clarity/automation_worker/)

• wrapper.log: Include if the Automation Worker is unable to start (rarely needed).

Saving passwords in encrypted format is recommended. Use the omxprops to do this action.

To encrypt a password:

Use the following command:

# java -jar /opt/gls/clarity/tools/propertytool/omxprops-ConfigTool.jar encryptPassword <password>

This command returns a text string resembling the following example:

RqHL5XpY0NStVRjd+BngRQ==  

To set an encrypted password:

Set the password by enclosing the text string in the ENC() wrapper.

Consider the following examples:

• When setting an encrypted password in a configuration file:\

• When using the property tool to set an encrypted password:\

• Using ENC() is not needed when setting the password in Automation Worker:\

The Config Slicer tool is used to move small incremental configuration changes, contained in a configuration set, between Clarity LIMS systems. For example, it moves changes between a test system and a production system.

This configuration tool provides granular export/import functionality that allows the management of configurations that support experimental workflows.

Use this tool to back up, copy, deploy, and restore configuration sets. By making small incremental changes, make sure that the modifications made to the production system are minimal.

Review the following key concepts:

• Configuration set—This item may be created by the Illumina Support team or by the customer. It comprises the items (know as entities) that are added to a Clarity LIMS system to allow for customization for a particular scientific experiment or workflow. The Illumina NGS Extensions Package is a good example. See

If there is an API version mismatch, Config Slicer will log a message at the beginning of an import:

Copy

Generally, this message is not a cause for concern.

However, if there are warnings about configuration differences during the import, changes that have been made to the API in between the package version and the server version may be responsible.

In addition, if the package being imported is from v4.x, a log message may appear at the beginning of an import:

Detected package is from a pre-5.0 Clarity system. The package will be upgraded to match new configuration requirements.

Enforcing Unique Sample Names Within a Project

By default, Clarity LIMS allows duplicate sample names within the same project. If you would like to enforce sample name uniqueness within a project, you can do so.

Two scripts have been developed to support this requirement:

• SampleNamePerProjectUniqueConstraintStep: Apply this uniqueness constraint to enforce unique sample names within a project.

• CleanupDuplicatedSampleNamesPerProjectStep: Prior to running the uniqueness constraint, use this optional cleanup script to clean up a database that already contains duplicate sample names.

Both scripts are available via the clarity-migrator.jar tool.

Cleaning up the database

If your database contains projects in which duplicate sample names exist, run the CleanupDuplicatedSampleNamesPerProjectStep script to clean up sample names that would violate the sample uniqueness constraint property. The cleanup script searches the database for sample names that are not unique and renames them.

The cleanup script also renames the corresponding original submitted sample name - since there is a one-to-one correspondence between submitted sample and derived sample names in the LIMS interface.

To clean up the database:

1. As the glsjboss user, change to the clarity-migrator directory:\

   Copy

2. Run the clarity-migrator.jar tool, providing the name of the cleanup step as a parameter:\

   Copy

Once cleanup has been performed successfully, you can apply the sample uniqueness constraint.

Enforcing sample uniqueness

After you have cleaned up the database (if this step was required), you can apply the uniqueness constraint.

Applying the sample uniqueness constraint results in a change at the LIMS database / schema level. Once you have applied this change, there is no script available to revert it.

If you need to remove the uniqueness constraint, you will need to submit a request to the Illumina Support team.

To enforce sample uniqueness:

1. As the glsjboss user, change to the clarity-migrator directory:\

   Copy

2. Run the clarity-migrator.jar tool, providing the name of the uniqueness constraint step as a parameter:\

   Copy

Results

After enforcing sample uniqueness, if a user attempts to accession or update sample names that already exist in the project - via the user interface or the API - an error message displays. The message describes the problem and advises the user to rename the duplicate samples.

The following sections describe and illustrate what happens if an accessioned or updated sample name conflicts with an existing sample name within the same project.

Postgres database

If an accessioned or updated sample name conflicts with an existing sample name within the same project:

Upload/modify via a sample sheet will result in the error shown below.

The sample with duplicate name is named within the parenthesis of the Detailed error message.

The quoted string in the Detailed error is the database name of the constraint being violated (uk_sample_name_per_project = unique key on sample table for name and project).

Sample management accession/modify will result in the error shown below.

If a user attempts to accession/modify a sample name under similar circumstances via an API operation, the results received would be similar to the content of this error message.

If necessary, the Clarity LIMS Support team can provide a backup of your Clarity LIMS data. The data are contained in an encrypted file, which can be downloaded from a secure SFTP server.

Prerequisites

To receive the backup data file, provide the Clarity LIMS Support team with a GNU Privacy Guard (GPG) public key.

For instructions on generating a GPG public key, see the following documentation:

Use the following steps to help troubleshoot the installed Automation Worker framework. A flowchart is provided as a reference.

Flowchart Reference

1. Verify Connection Between LIMS Server and Automation Worker Node

1.1 Checking the connection

The first step is to check the connection between the Clarity LIMS server and the Automation Worker node.

Use the -n option of the ai-monitor.jar tool script to see if the Clarity LIMSserver is currently able to communicate with the AI node.

To check the status of ai-monitor.jar:

1. As the glsjboss user open a SSH session to the Clarity LIMS server.

2. Run the following command:

   Copy

   • If the Clarity LIMS server cannot connect to any of the AI nodes the response will be as follows:

2. Verify Windows Service or Linux Daemon

Determine if the Windows service or Linux daemon for the Automation Worker is running.

2.1 Starting and stopping the Windows service / Linux daemon

To start, stop, or restart the Windows service:

1. From the Start menu, select Run.

2. In the Open text field, type ‘services.msc’ and select OK.

3. In the Services dialog, locate the Automation Worker service.

To start or stop the Automation Worker Linux daemon:

• To verify current status:

  Copy

• To restart a running daemon:

  Copy

• To stop a running daemon:

Once Started/Restarted:

• Wait for a minimum of three minutes, and then check if the AI node is communicating with the Clarity LIMS server by running the ai-manager.sh script with the status argument, as described in Step 1.

If the daemon is not recognized, list out the contents of the /etc/init.d directory and determine the exact name of the Automation Worker daemon.

The name typically contains 'automation_worker', but may vary—particularly if there is more than one daemon on the same Linux server, or if the Automation Worker is installed on a server other than the Clarity LIMS application server.

3. Automation Worker Log Files

Automation Worker creates history and log files and stores them on laboratory computers in the logs folder of the Automation Worker installation directory.

3.1 Reviewing Automation Worker log files

After performing the steps described above, reviewing these log files may help to determine the cause of the issue.

For details on the Automation Worker log files, and instructions on how to view them, refer to .

3.2 Turning on debug logging

After reviewing the log files, if the cause of the issue is not evident, the next stage is to turn on debug logging. This outputs DEBUG messages to the log files.

Contact the Clarity LIMSsupport team for instructions on turning on DEBUG mode.

Review the log files to determine if the DEBUG messages help to find resolution.

After turning on debug logging, ensure that you restart the Windows service or Linux daemon.

All Clarity LIMS installations include the installation of a separate component known as an Automation Worker (AW) node (formerly known as Automated Informatics (AI) node).

When writing automation-based triggers, the code invoked by an automation runs on the AW node.

While the AW node is a critical component, it typically does not require much attention. However, there are many other options that must be considered. These options include how many AW nodes a Clarity LIMS system uses, and where they are placed. This section discusses some of these options.

Automation Worker Nodes and Remote Computing

The AW node is installed adjacent to the Clarity LIMS application. Its original purpose was to enable remote computing.

To illustrate these features, assume that a need requires Clarity LIMS to produce a file in a specific location. The file is then processed and an action occurs.

A good example is label printing via the BarTender application. The BarTender application picks up the new file, associates it with a printer and a template, and causes a label to be printed.

The infrastructure for this file storage and processing likely occurs on a separate server from the one that contains the Clarity LIMS application and the AW node.

The Clarity LIMS application invokes the command to create the file on the AW node. After the file is in the file store, it is processed by the file processing application.

How does the AW node get the file to the file store, even if it is on a different server and possibly on a different network? The solution is to install an AW node on the external server.

The addition of the second AW node, which is local to the external server but remote as far as Clarity LIMS is concerned, provides a solution to the problem. This demonstrates how AW nodes can support remote computing..

1. Clarity LIMS invokes the production of the file via the remote AW node.

2. The remote AW node copies the file to the local file store.

3. The file processing application processes the file.

Automation Worker Properties

An AW node is a Java-based application and can run on most PCs/servers.

• The AW node and the Clarity LIMS application must be able to communicate through networking firewalls.

• When the Clarity LIMS application has the choice of sending the task to multiple AW nodes, the channel name property is used to determine which one receives the job. For example, the AW node installed on the Clarity LIMS server has the default channel name of limsserver. This is why you must specify the limsserver value when defining an automation command.

• When defining the automation, the following two items are defined:

Automation Workers in the Cloud

Consider the AW node that is installed on the Clarity LIMS server for a cloud-based implementation.

Although cloud-based Clarity LIMS servers contain an AW node, the best practice is not to run your code on it.

Why not? It is a question of security policies for both Illumina and our cloud-hosting provider. If we provide customers with command-line access to the AW node, we are allowing them command-line access to the Clarity LIMS server and, as a consequence, the Clarity LIMS application itself. If using Clarity LIMS in a clinical environment, this makes it more difficult to pass security and access audits.

If the Clarity LIMS instance is cloud-hosted, and you need to run custom code via an AW node, there is a solution.

You could install an AW node on your local architecture and have it interact seamlessly with Clarity LIMS, as illustrated in Figure 1. You can control access to the remote AW node, the infrastructure of the Clarity LIMS server is safely hidden behind firewalls, and security policies remain intact.

However, for some customers, part of the attraction of a cloud-based system is not having to maintain mission-critical hardware. To address this, we can offer an external AW node that does not live on local hardware but is also in the cloud.

Thus, we can provide an external AW node that lives on a separate machine, known as the Automation Worker host. This Software-as-a-Service (SaaS) model gives access to only those parts of the system that require it. You can access the Automation Worker host, and its AW node can interact with Clarity LIMS. However, you cannot access the Clarity LIMS server.

Because the AW node is running on a separate machine to the Clarity LIMS server, it needs its own copy of the toolkit JAR files. For some, this feature has an additional bonus in that the Automation Worker host hardware supports Python 3 for scripting.

For customers who are cloud-based and need a true local AW node, this is not a problem. They can have an AW node in the Automation Worker host and as many local AW nodes as needed. Place them wherever they are needed.

Automation Worker Node on Windows Server

In Clarity LIMS v5.4 and later, you can install the Automation Worker Node onto the Windows server. Before you begin the installation, make sure that you have met the following requirements:

• The clarity-aiinstaller-x-deployment-bundle.zip file must be retrieved from the server where Clarity LIMS is installed. You can find this file at /opt/gls/clarity/config/.templates/automation_worker/.

• For Windows 10 users, the command prompt must be specified in the Automation command line (eg, cmd.exe / c echo 'Hello World').

• If VISTA-SETUP.bat does not display in the installation window after Run as Administrator is selected, start the installation window as follows.

Install the Automated Worker Node as follows.

1. Copy the SecretUtil deployment bundle ZIP file to the remote Automation Worker node.

2. Extract the contents of the ZIP file to a folder named secretutil. You can add this folder to C:\opt\gls\clarity\tools or another location you choose.

3. Edit vault.properties of the file in the conf folder to update application.mode to file.

Create a Configuration Package File for Import to Another System (or for Backup Purposes)

Use a configuration package file to copy a configuration set from one server to another or to back up a particular working configuration at a particular time.

Required steps:

1. Create a configuration manifest file.

2. Export to configuration package file.

Import (install) a Configuration Package File on a Production or Test Server

This process involves copying a configuration set from one server to another, by importing a configuration package file.

For example, to move a configuration set to a different environment for testing or troubleshooting purposes, or copy a new configuration set (created and tested on one system) onto another system.

Required steps:

1. On the source server, create a configuration manifest file, and then export to configuration package file.

2. On the destination server, import the configuration package file.

Compare Differences between a Working Configuration and a Broken Configuration

There are two approaches:

• Comparing configuration manifest files provides a way to determine if there are processes or UDFs missing from a system. The information in the manifest files only allows comparing process and UDF names, not the specific way in which a process or UDF is configured.

• Comparing configuration package files helps check how specific processes are configured. If the systems being compared are meant to be identical, this method is more appropriate to use.

Required steps:

1. On each system, create a configuration manifest file, or a configuration package file.

2. Run a diff comparison on the two files.

3. Edit the broken manifest file, export it, and import the resulting configuration package file into the system to add the missing entities.

There are several tools that available to compare files:

• Meld (graphical), for Linux, port to MacOS

• Standard Unix diff (Linux, MacOS) (use -q for a quick check).

• FileMerge (OSX with XCode installed) - /Developer/Applications/Utilities/FileMerge.app

Merge the Configuration Sets from Multiple Test Systems to a Production System

Combine configuration sets from multiple systems, merge them into a single configuration package file, and then import the file into a new system.

Required steps:

1. On each source server, create and edit a configuration manifest file.

2. Merge the entities from all files into a single manifest file.

3. Export the resulting file to a configuration package file.

Back up and Restore a Configuration Set

Copy a configuration set to restore it on another server and use it for testing/troubleshooting purposes.

Required steps:

1. On the server containing the 'broken' source system, create a full manifest file, containing all of the LIMS system configuration.

2. Export the manifest to a configuration package file. Save file to media/disk.

3. On the target server, import the configuration package file created on the source system.

Back up and Upgrade a Configuration Set

To upgrade or add to a configuration set already installed on a server, two configuration package files are needed: one to back up the working configuration set and one containing the new updated configuration that have been created on a test server.

Required steps:

1. On the server you want to upgrade, create a full manifest file and export this to a configuration package file. Save this file as a backup.

2. On the test server, create a manifest file and edit it so that it only includes the entities you want to import.

3. On the server you want to upgrade, import the configuration package file.

Deploy a New Configuration Set from Test to Production Server

You may want to take a configuration that has been created and tested on one system/site (referred to as the source system in the steps below), and deploy it on another system/site (destination system).

Take a configuration that has been created and tested on one system/site (referred to as the source system in the following steps) and deploy it on another system/site (destination system).

As a best practice, make sure that the configuration is backed up by creating a full manifest file and exporting to a configuration package file (see Step 2). The process is also described in .

Required steps:

1. On the source system, create a configuration package file containing the tested configuration to import.

2. On the destination system, create a full manifest file and export this to a configuration package file. Save this file as a backup.

3. On the destination system, import the configuration package file that was created in step 1.

Command-line Options and Usage

Refer to Import/Export Mode and Guidelines and Semantics for Creating Manifest Files.

* The importAndOverwrite option lets Config Slicer update existing configuration, rather than create new configuration. This option is only available in LIMS 3.4.

Usage

Copy

EXPORT: Creating a configuration package file

Prerequisites

• Created and validate a configuration set on the source server.

• Have access to the Config Slicer tool and the libs subdirectory.

Step 1: Create configuration manifest file

Create Simple manifest file or Custom manifest file.

Simple manifest file:

1. On the source server, copy and paste following code to the command line. Edit the variables (version, server IP address, username, password, and manifest file name) to match those in your system.

   Copy

   A command with the variables filled in might look like this:

   Copy

2. This step produces a manifest file containing information about the entire system configuration. For best practice, copy this file and rename the copy in a way that reflects the configuration (we'll use newconfiguration.txt for this example). Use the copied file for the next steps.

A manifest file is used as an intermediary step to produce an XML configuration package file.

The manifest file is only relevant to the data that exists in the system at the time it is created. Discard it after creating the configuration package file or save the manifest file for historical auditing purposes. It can provide a record of a known working configuration set on a particular system.

Custom manifest file:

To create a manifest file for only specific workflows, protocols, or process types, follow the steps outlined previously, using -o custom instead of -o example.

• When using this operation provide additional parameters (-w, -pr, and/or -pt) specify the exact entities for which to create a manifest. For example:

  Copy

• Specifying every option is not required. It is also possible to specify more than one of each kind. For example, create a manifest file for a workflow with the following command:

  Copy

Step 2: Edit Manifest File

The next step is to edit the manifest file, removing unnecessary information and preserving only the custom configuration to import into the destination system.

Example 1: In this example, everything is deleted from the manifest file, except for the two new process types to export.

Copy

Example 2: In this example, the manifest file contains definitions for some new reagent types:

Copy

Step 3: Export to XML Configuration Package File

• Copy and paste the following code onto the command line. Edit the variables (version, server IP address, username, password, and manifest and package file names) as required.

  Copy

• An edited command might look like the following example:

  Copy

This step generates a data file in an XML format (newconfiguration.xml in our example) that is compliant with the Rapid Scripting API.

IMPORT: Installing a Configuration Package File

Prerequisites

• A configuration package file has been exported. This example uses a file named newconfiguration.xml.

• Access to the Config Slicer tool on the destination server has been granted.

• There are no in progress steps for any of the protocols that are going to be sliced in, otherwise the import of the protocol fails.

Step 1: Import Configuration Package File

• On the destination server, copy and paste the following code to the command line. Edit the variables (version, package file name, server IP address, username, and password) as required.

  Copy

• A command with the variables filled in might look like this:

  Copy

About duplicate entities

If any of the configuration entities that are about to import, exist in the destination system, Config Slicer either logs a warning or attempts to update them. It depends on the mode being run (see ).

If Clarity LIMS has maintained an internal record of deleted items, the previous information may also apply to deleted entities. This situation may occur if those entities have created outputs that currently still exist in the system.

• When running in import mode, entities that exist and are different from the version in the package have a warning and full diff logged.

• When running in importAndOverwrite mode, Config Slicer attempts to update entities that exist and are different from the version in the package.

  • In this scenario, back up configuration package containing copies of the updated entities before they were changed is saved to the directory where the configuration package is located. If that directory is not writable, the backup package is saved to the same directory as the log file.

To avoid changing existing configuration (which could possibly break historical data), another option is manually renaming the old entities. Add an extension or a prefix and continue with importing the new configuration package.

Step 2: Validate the import

Use the following methods to validate whether an import has completed successfully:

Check the Import Log:

For each specific type of configuration that is being imported (e.g. container types, process types, workflows), Config Slicer will log a set of messages. The messages look similar to the following examples:

Copy

• Before it begins to process a specific entity, the file logs how many entities were found. Any errors or warnings about this set of entities always appear between Found 4 $Entities and Summary of $Entities.

• Every entity that is found in the configuration package always appears in the summary, in one category or another. If a scenario occurs where this isn't true, or where the initial count of entities does not match the number in the summary, something has gone wrong and a bug report should be filed.

Validate with Config Slicer:

Running Config Slicer with the validate operation checks every entity in the package to see if it exists on the destination server. It reports results in a format similar to the log format shown previously.

Run the validate operation before or after importing:

• Before importing—checks if there could be any problems when importing a configuration from a package. This feature is its primary use as it makes sure that during import, "configuration exists in package but not on server" is not considered an error case.

• After importing—makes sure that the results are what was expected.

Example of validate output:

Copy

Check Configuration on the Destination Server:

The ultimate test of whether configuration has imported successfully is to check the configuration on the destination server itself. Make sure it looks and behaves as expected.

Configuration can be checked either via the Configuration screen in the Clarity LIMS user interface, or via the configuration endpoints in the API.

Guidelines and Semantics for Creating Manifest Files

Top-level entities

• To be included in a configuration package file, the top-level entities of the custom configuration set must be explicitly enumerated.

• Some of the top-level entities are discrete 'self-contained' units, and do not include other units (for example, container types, reagent types, artifact groups, and non-artifact/non-process type UDFs).

• Some top-level entities (process types, for example) automatically include other units (refer to for more information).

Non-Top-Level Entities

• Some entities are only included as part of other entities. For example, process templates, process type UDFs, and artifact UDFs are only included when included in a top-level process type. (The latter is a special case, given that the same artifact UDF can be used by multiple process types.)

Required Entities

• Some entities may be required by other entities. In these cases, make sure that these entities are exported/imported in the correct order. For example, because process types may require the existence of a container type, create the container type first.

• Required entities are not automatically included. If they do not exist in the destination system, explicitly include them in the manifest file. For example, suppose that a process type declares a particular container type as a default output plate. If that container type does not exist in the destination system, include that container type in the manifest file.

Import/Export Mode

Import modes affect the transactability of the tool, allowing it to make incremental changes if errors occur or provide an all-or-none option. For example, use the operation validate mode to determine if errors were encountered.

Best-Effort Mode

• This is the default import mode.

• This mode attempts to import as many units as possible. Any failures are logged, but the import operation is not interrupted.

  • For example, a failing container type import will not prevent other container types from being processed.

Strict Mode

• If this mode is used, the import operation is aborted if it encounters a failure.

  • For example, if there is an API version mismatch, the operation will abort and no further imports will be executed. Note that any changes already performed are not reverted.

• Use the -Strict option to enable this import mode.

Validate Mode

Use the validate operation (instead of import) to enable this mode.

This mode produces a report listing showing the following items:

• Entities that would be successfully imported because they do not exist on the target server.

• Entities that already exist on the target server and are identical.

• Entities that already exist on the target server but are different.

Validate mode can only detect a limited set of errors. For example, it can check if a particular piece of configuration already exists. If so, it checks if it is identical to the one included in the configuration package.

This information can help determine if the importAndOverwrite option is needed instead. For details, see .

Example of console output:

Copy

Example Mode

• Use this mode to generate a manifest file if the configuration you want to export is not tied to a specific set of workflows, protocols, or process types.

• Use the example operation (instead of import) to enable this mode.