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

## 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](http://httpd.apache.org/docs/current/programs/httpd.html) or [HFS](http://www.rejetto.com/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 the following database properties: directory, host, port and scheme.

The 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 two properties listed in the table (with the .domain and .user suffixes) to specify a domain, and username to be used when accessing files.
* Configure the external filestore password using Secret Utility. For more information on Secret Utility configuration, refer to the [Clarity LIMS (Clarity & LabLink Reference Guide) documentation](https://help.connected.illumina.com/clarity-lims/clarity-lims/clarity-and-lablink).

| **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.                                                     |

### 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>
```

## Example: Mapping a Remote HTTP URI

The following example maps a remote HTTP URI: [http://YourHTTPHost:80/limsdata/LegacyFile.RAW](http://yourhttphost/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 [page](https://help.connected.illumina.com/clarity-lims/api-and-database/api-docs/cookbook/page "mention").

## Troubleshooting

### Remote HTTP and HTTPS Download of Files and Folders Fail

{% hint style="danger" %}
There is a known issue in Clarity LIMS v6.3.2 and onwards where remote HTTP and HTTPS download of files and folders will fail.
{% endhint %}

For on-premise customers, apply the following steps to workaround the issue:

1. Copy vfs-providers.xml to the appropriate directory in the Clarity LIMS server. Example (Replace `6.x.x.x` with the correct application version in the deployed server):

   ```
   /opt/gls/clarity/tomcat/current/webapps/clarity##6.x.x.x/WEB-INF/classes/META-INF/vfs-providers.xml
   /opt/gls/clarity/tomcat/current/webapps/api##6.x.x.x/WEB-INF/classes/META-INF/vfs-providers.xml
   ```
2. Ensure that the file permission is the same as the other files within the directory. Run the following commands to update the permission (if needed) by replacing `6.x.x.x` with the correct application version in the deployed server:

   ```
   chown glsjboss:claritylims /opt/gls/clarity/tomcat/current/webapps/clarity##6.x.x.x/WEB-INF/classes/META-INF/vfs-providers.xml
   chown glsjboss:claritylims /opt/gls/clarity/tomcat/current/webapps/api##6.x.x.x/WEB-INF/classes/META-INF/vfs-providers.xml
   ```

vfs-providers.xml