Remote HTTP Filestore Setup

Server-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).

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.

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.
• LIMS 4.x and earlier—For the property changes to take effect, JBoss must be restarted.
• LIMS v5 and later—For the property changes to take effect, Tomcat must be restarted.

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>

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>

To set a property to the encrypted result, set the value as ENC(<result>).

See also Creating Encrypted Passwords.

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

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 <attached-to> parameter.
• For LIMS v4.x and earlier, if you would like the file to be accessible from the LabLink Collaborations Interface, change the <is-published> value to true.

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