Remote HTTP Filestore Setup

${baseName}.dirServer-side configuration allows for configuration of multiple filestores to be associated to entities (samples, projects, processes/steps, and so on) in BaseSpace Clarity LIMS.

This feature allows for linking to large data files on a different server, eliminating the need to move large files on the Clarity LIMS filestore. Large files can include results, images, and searches, and so on.

For example, sequencing instruments typically produce large result files. Attaching these files to the Sequencing step in Clarity LIMS results in the following drawbacks.

• Involves transferring the files to the Clarity LIMS filestore. The larger the file, the slower the transfer speed.

• Requires a large amount of space as runs build up.

An alternative solution is to set up a remote filestore to be used as the results directory from which Clarity LIMS accesses the files directly.

To do this setup, three steps are required:

1. Set up HTTP, HTTPS, FTP, or SFTP access to the files and folders you wish to share.

2. Configure the Clarity LIMS server to recognize the URI of a file on the remote filestore.

3. POST information to Clarity LIMS, via the REST API, to reference the file from a Clarity LIMS entity (project, sample, process/step, result file, and so on).

Setting Up Access to the Files

BaseSpace Clarity LIMS can operate with many different forms of file servers – HTTP, HTTPS, FTP, and SFTP access are all supported.

It is your responsibility to set up this access. For HTTP, you may be interested in httpd or HFS for HTTP file serving.

Configuring the LIMS Server

Properties Required for Tracking a New Remote Filestore

To track a new remote filestore, Clarity LIMS requires four database properties: directory, host, port, and scheme.

The four properties share a base name, but have different suffixes attached (dir, host, port, scheme). These suffixes are summarized in the following table.

• The base name can be anything. Clarity LIMS finds any base names that end in .scheme and uses that base name to find the other information.

• If necessary, add the last three properties listed in the table (with the .domain, .user, and .password suffixes) to specify a domain, username, and password to be used when accessing files.

Property Name	Usage	Example Value	Required	Description
Directory	${baseName}.dir	/limsdata	True	The highest level directory in which it is valid to access files. Files outside this directory are not attached.
Hostname/IP	${baseName}.host	YourHTTPHost	True	The hostname or IP address to use when accessing the files.
Port	${baseName}.port	80	True	The port to use when accessing the files.
Scheme	${baseName}.scheme	http	True	The scheme of the URI used to access the files. Examples are HTTP, HTTPS, FTP, and SFTP.
Domain	${baseName}.domain	YourAuthDomain	False	The domain to use when authenticating access to the files.
Username	${baseName}.user	fileUser	False	The username to use when authenticating access to the files.
Password	${baseName}.password	filePassword	False	The password to use when authenticating access to the files. It is highly recommended that you encrypt your password. See the following section for details.

• Clarity LIMS v5 and later—For the property changes to take effect, Tomcat must be restarted.

Working with the Database Properties

Use the omxprops-ConfigTool.jar to create, update, and retrieve values of the database properties. This tool is found at the following location: /opt/gls/clarity/tools/propertytool

To create a property, use the following examples:

java -jar omxprops-ConfigTool.jar addPropertyType <baseName><suffix> /<value> <description>

NOTE: These properties may not be global properties. Do not use the -g property here.

To get the value of an existing property:

java -jar omxprops-ConfigTool.jar get <baseName><suffix>

To update the value of an existing property:

java -jar omxprops-ConfigTool.jar set -y <baseName><suffix> <newValue>

To encrypt a password:

java -jar omxprops-ConfigTool.jar encryptPassword <password>

NOTE: To set a property to the encrypted result, set the value as ENC().

Example: Mapping a Remote HTTP URI

The following example maps a remote HTTP URI: http://YourHTTPHost:80/limsdata/LegacyFile.RAW

In this case, the base name for the properties is http-lims-files.

Steps

1. As the glsjboss user, access the omxprops property tool in /opt/gls/clarity/tools/propertytool.

2. Add the following dir, host, port, and scheme properties to the server from the command line:

java -jar omxprops-ConfigTool.jar addPropertyType http-lims-files.dir '/limsdata' 'Alternate filestore server dir'

java -jar omxprops-ConfigTool.jar addPropertyType http-lims-files.host 'YourHTTPHost' 'Alternate filestore host'

java -jar omxprops-ConfigTool.jar addPropertyType http-lims-files.port '80' 'Alternate filestore port'

java -jar omxprops-ConfigTool.jar addPropertyType http-lims-files.scheme 'http' 'Alternate filestore server type'

In the example above, the <http-lims-files.dir> parameter value is /limsdata. Any file in http://<YourHTTPHost/limsdata/ is available to be referenced by BaseSpace Clarity LIMS.

For all files on the web server to be available, use the / parameter value, for example:

java -jar omxprops-ConfigTool.jar addPropertyType -y http-lims-files.dir / Alternate filestore server dir

Posting Information to the LIMS Referencing Files on the Remote Filestore

After the filestore properties are added to Clarity LIMS (and JBoss/Tomcat has been restarted, as applicable), you can attach the files to Clarity LIMS.

To attach the files to Clarity LIMS:

• POST to http://hostname/api/v2/files, with the content-location tag pointing to the remote filestore.

An example XML POST is provided, using the filestore created in the previous example:

<file:file xmlns:file="http://genologics.com/ri/file">

<content-location>http://YourHTTPHost:80/limsdata/LegacyFile.RAW</content-location>

<attached-to>http://hostname/api/v2/artifacts/92-148</attached-to>

<original-location>http://YourHTTPHost:80/limsdata/LegacyFile.RAW</original-location>

<is-published>false</is-published>

</file:file>

Results

• The file is now downloadable directly from Clarity LIMS.

• Any entity that can have a file attached to it may be referenced in the parameter.

For more information on working with files, see Work with Files.