SFTP (Secure File Transfer Protocol) lets your source system push files straight into a Datarails Filebox over an encrypted connection. Datarails hosts the SFTP server for you — your system drops a CSV or Excel file into a folder, and Datarails picks it up, tags it with the right reporting period, and creates a new Filebox version automatically.

You can now set this up yourself, from the Integrations screen, without opening a support ticket. Datarails creates the SFTP directory, generates the credentials, and gives you the folder path for each Filebox.

Already using an SFTP integration? Existing SFTP integrations that were set up manually by the Datarails Integrations team keep working exactly as they do today. Datarails is migrating them to the self-serve mechanism — you don't need to do anything, and your credentials and folders stay the same.

How it works

SFTP is a push integration: Datarails never reaches out to fetch your data — your system decides when to send it.

1. Your system uploads a file to your organization's Datarails SFTP directory.
2. Datarails detects the new file automatically, within moments of the upload completing. There is no polling delay, and there is no manual or scheduled sync to trigger — SFTP Fileboxes have no Sync or Test sync action.
3. Datarails works out which Filebox the file belongs to (from the folder it landed in, or from Smart routing).
4. Datarails works out the file's reporting period — either from the file name or from the upload date.
5. A new version is created in the Filebox, and its sync status changes to Synced.
6. The file is then removed from the SFTP folder. A file that is still sitting in the folder is a file that has not been loaded yet — see Troubleshooting.

Supported file types

CSV and Excel files — .csv, .xlsx, .xls, .xlsm, .xlsb, and the other Excel formats a Filebox accepts for manual upload. A file with an unsupported extension is rejected and the Filebox shows an error.

Before you start

• You need permission to create and manage Fileboxes in your Datarails workspace. Viewer-only users can't set up an SFTP integration, and viewing the SFTP credentials requires owner permissions on the Filebox.
• Your source system (ERP, data warehouse, scheduler, script) needs to be able to upload files to an external SFTP server using a username and password.
• Decide how each file should be dated (Step 3 below). If your file names already contain a date — for example GL_202401.xlsx — you'll get the most accurate tagging.

Set up an SFTP Filebox

Go to Integrations → Integration Fileboxes and click + New.

Step 1 — Create the Filebox

Fill in the Filebox details:

Click Create & connect.

Step 2 — Choose the connection type

Under Choose how this Filebox will receive its data, select SFTP integration — Upload files to a secure SFTP directory, then click Create connection.

Step 3 — Set the date tagging logic

Every file that arrives over SFTP has to be linked to a reporting period, so Datarails knows which day/month/quarter/year the data belongs to. Choose one of two methods.

This step only appears when the Filebox has a date label. A Filebox created without one goes straight to the credentials step.

Option A — Extract date from file name (recommended)

Datarails reads the date out of each file name as it arrives.

1. Date format in your filename — pick the pattern your files use:
    

2. Format	Example file name |
   YYYYMMDD	GL_20240131.xlsx
   YYYYMM	GL_202401.xlsx
   MMM-YYYY	GL_Jan-2024.xlsx
   YYYY-MM-DD	GL_2024-01-31.xlsx
   YYYY-MM	GL_2024-01.xlsx
   MMM YYYY	GL_Jan 2024.xlsx
   MM-DD-YYYY	GL_01-31-2024.xlsx
   DD.MM.YYYY	GL_31.01.2024.xlsx
   DD-MMM-YYYY	GL_31-Jan-2024.xlsx
   MMM-YY	GL_Jan-24.xlsx

3. Date position in filename — End of filename (default) or Beginning of filename. This matters when a file name contains more than one date: from_20240101_to_20240131.csv resolves to January 31 with End, and to January 1 with Beginning.

4. Test it - paste a real filename — paste an actual file name from your system. The Extracted date tag field shows the period Datarails would assign, so you can confirm the rule before you finish. If nothing matches, you'll see No date found.

   

The extracted date is snapped to the Filebox's granularity — with a Month Filebox, GL_20240131.xlsx is tagged Jan 2024.

Option B — Use upload date

Files are tagged with the period they're uploaded in. Use this when your file names don't carry a date.

Allow submitting previous periods (backfill) — off by default. Turn it on when you also need to send files for earlier periods:

• Under How many months back can be uploaded? choose the depth — between 1 and 24; the default is 3. (The label names your Filebox's own granularity, so a quarterly Filebox reads "How many quarters back…".)
• Datarails creates one dated subfolder per period inside the Filebox folder: /-1/, /-2/, /-3/, …
• A file dropped into /-2/ is tagged two periods before the current one. A file dropped into the main folder is tagged with the current period.
• Each path row has a copy button, so you can paste the exact path into your ETL or scheduler configuration.
  Click Next.

Step 4 — Copy your SFTP credentials

Datarails now provisions the directory and shows the credentials your system needs. All fields are read-only, and each has a copy button.

Directory details and credentials

Filebox details

Click Finish & close (or Go to Filebox to open the Filebox straight away).

The new Filebox appears at the top of the Integration Fileboxes list with the status Waiting for data. Both the sync status and the data status update once the first file arrives and is mapped.

Connect your system to the SFTP server

Configure your source system with:

• Host — as shown on the credentials screen
• Port — 22 (standard SFTP)
• Protocol — SFTP (SSH File Transfer Protocol)
• Username / Password — as shown on the credentials screen
• Upload path — the Filebox Folder, e.g. /Actuals_12345/

A few things worth knowing:

• One user per organization. Every SFTP Filebox in your organization uses the same username and password. Each Filebox has its own folder underneath it.
• The folder decides the Filebox. Anything dropped in /Actuals_12345/ goes to that Filebox. If your system can't target a specific subfolder, use Smart routing instead.
• Uploads must complete. Datarails only picks up a file once the transfer is finished, so partial uploads are never ingested.
• Overwriting a file re-triggers it. Uploading a file with the same name again is treated as a brand-new file.

Passwords

The SFTP password is generated once, when your organization's directory is created, and it doesn't expire. You can view and copy it at any time from SFTP server details (see below) — but you can't change or regenerate it yourself. If the password needs to be replaced, contact support@datarails.com.

Smart routing

Some systems can only write to one location and can't be configured to target a per-Filebox subfolder. Smart routing handles that case: files land in the root of your SFTP directory, and Datarails decides which Filebox each one belongs to based on its file name.

Smart routing is off by default and is configured per Filebox, in SFTP settings.

To turn it on:

1. On the Filebox row, open the ⋮ menu → Settings.
2. Turn on Smart routing.
3. In File unique identifier, enter the string that identifies files for this Filebox — for example Budget, GL, Actuals.
4. Use Test it - paste a real filename to check the rule, then Save changes.

How identifiers are matched

• The identifier must appear in the file name as a whole word — bounded by a non-alphanumeric character (_, -, ., a space) or by the start or end of the name. Budget matches GL_Budget_202401.xlsx.
• A partial hit doesn't count: the identifier GL does not match GLOBAL_202401.xlsx.
• Matching is case-sensitive. Budget does not match gl_budget_202401.xlsx — use the exact casing your system produces.
• Identifiers must be unique across your organization's SFTP Fileboxes. Reusing one shows an inline error naming the Filebox that already has it, and blocks Save changes until you change it.
• If a file name matches more than one Filebox's identifier, the longer (more specific) identifier wins; if two are the same length, the alphabetically-first one wins.

The routing tester

Test it evaluates the file name against every Filebox's identifier, not just this one, so the result reflects what will really happen:

Smart routing only applies to files in the root of your SFTP directory. A file placed directly in a Filebox folder always goes to that Filebox, whatever its name.

Manage an existing SFTP Filebox

On the Filebox row in Integration Fileboxes, open the ⋮ menu and choose Settings.

The SFTP settings dialog contains:

• Directory details → Path — the read-only upload path for this Filebox, with a copy button, plus a link back to this documentation.
• Smart routing — the toggle, identifier and tester described above.
• Date tagging logic — a read-only summary of the current method (and its date format and position, or whether previous periods are allowed). Click Edit date tagging logic to change any of it, including switching between the two methods and turning Allow submitting previous periods on or off.
• Filebox timezone — shown only when the method is Use upload date. Choose the GMT offset that matches your local time so uploads are dated the way you expect. The default is GMT +00:00.

Click Save changes to apply, or Cancel to discard.

Changing the backfill depth Raising it creates the extra dated subfolders straight away. Lowering it stops the removed subfolders from being used — files dropped into them are no longer picked up — but the folders themselves stay visible in your SFTP client.

SFTP server details

Your organization's SFTP integration also appears on the Data sources tab as SFTP. Open its ⋮ menu for:

• SFTP server details — a read-only view of the username, password, email and host, in case you need the credentials again later.
• View Fileboxes — every Filebox connected to the SFTP integration.

The Auto-sync settings column shows Not applicable for SFTP, because uploads are always triggered by your system.

Statuses and indicators

Sync status

Data status shows what happened to the data after it loaded — Unmapped, Included in DB, or Mapping Failed.

Row icons

• A lock icon next to the Filebox name means the Filebox is locked and won't sync with new versions.
• A ban icon means you don't have permission to access that Filebox.

Troubleshooting

The file is still sitting in the SFTP folder. Files are removed only after they load successfully, so a file that's still there hasn't been ingested. Check the Filebox's sync status and Error details, and the SFTP integration row on the Data sources tab.

The Filebox shows "Failed". Open Error details on the row. Common causes: an unsupported file type, a file name whose date can't be parsed with the configured format and position, a locked Filebox, or a closed reporting period. Fix the problem and upload the corrected file again under the same name — overwriting re-triggers the load. Renaming the file in place does not.

The file didn't reach any Filebox. If it was dropped in the SFTP root and no identifier matched it, the SFTP data source shows an error naming the file. Either upload it into the Filebox's own folder, or set up a matching Smart routing identifier and re-upload it.

The date tag is wrong. Open Settings → Edit date tagging logic and re-test with a real file name. If you're tagging by upload date, check the Filebox timezone — a file uploaded late in the day near a period boundary can be dated to the wrong period if the timezone doesn't match yours.

The file went to the wrong Filebox. Two identifiers probably both match the file name, and the longer one won. Use Test it in each Filebox's SFTP settings to see which one claims the name, and make the identifiers more specific.

I need to change or reset the password. Contact support@datarails.com.

FAQ

Can I trigger a sync manually? No. SFTP is a push integration — Datarails loads files as your system sends them. That's why SFTP Fileboxes have no Sync or Test sync action.

How long does it take for a file to appear? Datarails reacts to the upload as soon as the transfer completes; loading itself takes as long as processing the file normally would.

Can several Fileboxes share one SFTP connection? Yes. Your organization has one SFTP user, and each Filebox gets its own folder under it.

What happens to my file after it's loaded? It's deleted from the SFTP folder. The contents live on as a version in the Filebox.

Can I upload historical files? Yes. If the date is in the file name, just upload it — the tag comes from the name. If you tag by upload date, turn on Allow submitting previous periods and drop the file into the matching /-N/ subfolder.

Can I change the date tagging rule later? Yes — Settings → Edit date tagging logic. The change applies to files that arrive from then on; files already loaded keep the tag they were given.

Updated August 17, 2026 13:45