File server integration

Overview

Kompass can connect to an external file server to give users direct access to project documents, proposals, and general company files from inside the application, without needing to open a separate file browser or navigate outside of Kompass.

Once connected, files appear in two places:

• Project detail pages – on the Files tab of any project, showing operations files and commercial files associated with that project.
• The Files section – a top-level navigation item showing shared company files not tied to any specific project.

Kompass does not store or copy your files. It reads them directly from your file server on demand and streams them to the browser. Your file server remains the single source of truth.

Supported providers

Kompass supports two families of backend: cloud and network storage (Rclone based) and the legacy on-premise File Gateway.

The Rclone connectors fall into two groups. The tested providers are in regular use and verified. The untested providers are implemented and selectable, but have not yet been verified end to end, so please involve Kompass Staff before relying on one of them in production.

Tested providers

• Google Drive – Google Workspace or personal Google Drive
• OneDrive / SharePoint – Microsoft 365 OneDrive or SharePoint document libraries
• Dropbox – Dropbox Business or personal accounts
• Citrix ShareFile

Untested providers

• FTP Server
• SFTP (SSH FTP)
• Amazon S3
• Google Cloud Storage
• Azure Files
• MEGA

Setting up the connection

File server connections are managed in the administration area under Admin → Files → File Servers. Only one file server can be enabled per organisation at any time. Enabling a new connection automatically disables any previously enabled one.

Cloud backends (Google Drive, OneDrive, Dropbox, ShareFile)

These use OAuth authentication. To start, click the Rclone Config Helper button, then follow the three-step wizard:

1. Select the backend – choose your storage provider (see the lists above) and give the connection a descriptive name, for example “Company OneDrive” or “Project Dropbox”.
2. Authorise Kompass – click Continue to Authorization. You are redirected to your provider's login page to grant Kompass read-only access. Sign in with the account that owns or can access the file storage. Kompass receives an access token and stores it securely.
3. Select the drive – for OneDrive and Google Drive, where multiple drives or shared drives may exist, you select the specific drive or folder to connect to.

Credentials (tokens, client secrets) are redacted in the administration interface and never displayed after initial setup. When a token expires, Kompass automatically refreshes it in the background without requiring you to re-authenticate.

Provider-specific details, including what to prepare on the provider side and current limitations, are covered in File server setup: Google Drive, OneDrive, Dropbox and ShareFile.

FTP and SFTP

Enter the host address, username, and password directly in the form. Passwords are automatically obscured before storage using rclone's built-in obfuscation, so Kompass does not store FTP or SFTP passwords in plain text.

Setup details for these and the other credential-based providers (Amazon S3, Google Cloud Storage, Azure Files and MEGA) are covered in File server setup: FTP, SFTP, S3, Google Cloud Storage, Azure Files and MEGA.

The legacy File Gateway

The File Gateway is an older option for organisations that want to expose existing on-premise file directories without moving them to a cloud provider. It is a small service that runs on a machine inside your own network and makes selected directories available to Kompass over a secure connection, using the gateway URL and a shared token.

Installing and configuring the gateway is involved and varies with each environment, so it is not something you set up on your own. Please contact Kompass Support before going down this route. We will talk you through what is needed and help with the installation. As part of that, Kompass checks the gateway's SSL certificate once a day, so if your gateway uses a custom or self-signed certificate it has to be added to the server's trusted certificate bundle. We will handle this with you during setup.

Checking the connection and understanding the folder structure

After a file server is connected, use the Test connection action on the file server in the administration area to confirm it works. For a cloud or network connection this lists the top level of the connected drive or folder and reports how many items were found together with the names of the first items.

This is useful for more than a pass or fail check: it gives you a quick picture of how the file server is structured at the top level, that is, which folders sit at the root. That makes it much easier to configure where Kompass should look for project and quote folders and how it should recognise them, because you can see the real folder names before you set the search paths.

How Kompass finds project directories

The most important configuration step after connecting is telling Kompass where on the file server to look for project files, and how to match folder names to project IDs.

Directory categories

Kompass searches for files in up to three named categories:

• projects – directories containing files for accepted projects
• quotes – directories containing files for proposals (pre-acceptance)
• general – a shared company-wide folder not tied to any project

Each category is configured with one or more search configs in the file server's Categories field. A search config has three properties:

• path – the root subdirectory on the file server to search within, for example Projects/   or Surveying/Active Projects/  .
• regex – a regular expression with exactly one capturing group, used to extract the project identifier from directory names. Kompass tests this pattern against every subdirectory name inside the path. Directories whose names match have their identifier extracted from the capturing group. For example, the pattern ^(\d+).*$   extracts the leading number from folder names like 12345 - Smith Survey   or 67890_Jones_Development  .
• depth – how many levels of subdirectory to search. A depth of 1 means Kompass searches the immediate children of the path plus their children. A depth of 0 or omitted means immediate children only. A depth of 2 or more allows deeper nesting. Use the lowest depth that covers your folder structure to keep lookups fast.

Identifier template

Each file server has an Identifier template field, a Jinja2 template that renders the string Kompass uses to match against what the regex extracts from folder names.

For most setups this is simply {{ project.id }}  , the numeric ID of the project in Kompass. If your folder naming convention uses the project reference instead, you would use {{ project.reference }}  . More complex templates are possible if your directory names encode information from both fields. The template is rendered per project, and the result is compared against the captured groups from the regex scan. When they match, Kompass has found the folder for that project.

Example

Suppose your Google Drive has this structure:

Projects/
  12345 - Acme Corporation Survey/
  67890 - Jones Development/
General/
  Company Policies/
  Templates/

The configuration would be:

{
  "projects": [
    {"path": "Projects/", "depth": 1, "regex": "^(\\d+).*$"}
  ],
  "general": [
    {"path": "General/"}
  ]
}

With identifier template {{ project.id }}  , Kompass extracts 12345   from 12345 - Acme Corporation Survey  , compares it to project ID 12345, and finds the correct folder.

Caching and rescans

Kompass caches the mapping between project identifiers and folder paths for 24 hours. This means that after a new project folder is created on the file server, it may take up to 24 hours before it appears in Kompass automatically. Your administrator can trigger a manual rescan at any time, which rebuilds the cache for all enabled file servers. This is also useful after reorganising your folder structure. If a cached folder path is later moved or renamed on the file server, Kompass detects the mismatch on the next access, removes the stale cache entry, and performs a fresh search.

How files are displayed in Kompass

On a project

Navigate to any project and click the Files tab. The tab shows two sections:

• Operations files – the folder mapped to the project under the projects category, containing field notes, survey data, deliverables, and similar working files.
• Commercial files – the same project folder under the quotes category (or the same projects folder if both point to the same location), containing proposals, contracts, and financial documents. Commercial files are only visible to users with the View Financials permission.

Files are displayed in a collapsible folder tree. Clicking a folder expands it and loads its contents. Clicking a file starts a download.

General files

The Files section in the main navigation shows the general category, a top-level view of shared company files not tied to any project. This is a good place to keep templates, policy documents, and reference materials.

Security

Access control

Access to the Files section and project files is controlled by the View Files permission (files.view_files  ). Users without this permission do not see the Files navigation item and cannot access the file browser. Commercial files on project pages additionally require the View Financials permission.

Signed download links

When Kompass displays a file listing, each file is given a signed link that is valid for one hour. Signed links are tied to the specific file path, the specific organisation, the specific category (projects, quotes or general), and the user who requested the listing.

If a user copies a signed link and shares it, it cannot be used by anyone else, because the link is cryptographically bound to the requesting user's ID. If the link is accessed by a different user, or after it has expired, Kompass automatically redirects to a re-signing page that validates the user's session and generates a fresh link before starting the download. This design lets file downloads work as native browser links (right-click then Save As, download managers, and so on) without the browser needing to send authentication headers, which standard links cannot do.

Credential storage and token management

• OAuth tokens (Google Drive, OneDrive, Dropbox, ShareFile) are stored securely and are never exposed in the administration interface after setup. The display shows ***REDACTED***  .
• FTP and SFTP passwords are obfuscated before storage.
• All sensitive values are stripped from log output automatically.

OAuth tokens are refreshed automatically when they expire. Kompass checks whether a token needs refreshing before each file server request and saves the new token back. You do not need to re-authenticate periodically under normal operation. If a token becomes permanently invalid, for example if access is revoked in the provider's admin console, the file server will stop working and the administration area will show an option to re-authenticate.

Permissions summary

Troubleshooting

No files appear on a project's Files tab. The most common cause is that no directory was found matching the project's identifier. Check that the project's ID (or reference, depending on your identifier template) is present at the start of the folder name on the file server in the format your regex expects, that the path in the categories config points to the correct root directory, and that the cache has been populated. If the folder was created recently, ask your administrator to run a rescan.

“Could not connect to file server” message. The file server is either unreachable or misconfigured. Your administrator should open the connection under Admin → Files → File Servers and use the Test connection action to check whether Kompass can reach the storage backend.

A download link has expired. Signed links are valid for one hour. If you click a link after it expires, Kompass automatically redirects you to a re-signing page, validates your session, and starts the download with a fresh link. No action is needed.

Commercial files are not visible. Commercial files require the View Financials permission in addition to View Files. If you can see the Files tab but there is no Commercial section, ask your administrator to check your group permissions.