File exchange

The File exchange screen is where you connect an SFTP server that another system writes files to, so arriving files are imported automatically on a schedule, and where you set up extracts that write files back for other systems to read. Open it from Administration → Integrations → File exchange.

The File exchange screen with a new connection open

An import you run by hand still needs somebody to remember to run it. File exchange is the same import running unattended: files read on a schedule and turned into imports against a mapping you kept in the Import Studio. Nothing is committed unless the feed says so — by default what arrives waits for somebody to review it, exactly as a file uploaded by hand does.

The connections list

One row per SFTP server. With none, the screen says No connections yet. Add a connection opens an empty connection form; click a connection’s name to open it.

Column	What it shows
Connection	Its name, with `username@host:port` underneath
Feeds	How many feeds watch it
Last look	How long ago it was last looked at, and how many files were taken, or Never
State	On, Off, Not pinned (no host key fingerprint yet, so nothing signs in) or Failing (the last look failed)

A connection

The form is titled New connection or This connection.

Field	What it means	Notes
Name	What the connection is called, such as “Payroll from Workday”	Required. Up to 100 characters
Host	The SFTP server’s host name	Required
Port	The SSH port	Default 22
Username	The account to sign in as	Required
Sign in with	A private key or A password	Default A private key
Private key / Password	The credential, matching Sign in with	Stored encrypted and never shown again. Once one is stored, the hint says so; leave it empty to keep it. Room for a PEM private key
Host key fingerprint	The server’s SSH host key fingerprint, such as `SHA256:…`	Nothing signs in until this matches what the server offers. Ask whoever runs the server, or leave it empty and switch the connection on: the first look fails and reports the fingerprint it saw, which you check against what the other side says before pasting it here. Pasting what the connection reported is not the same as checking it — a server never spoken to before could be anybody
Folder to watch	The folder files arrive in	Default `/`
Move files here afterwards	A folder to move each file to once it has been read	Optional. Empty leaves files where they are. Nothing is ever deleted on your server
Every (minutes)	How often the server is looked at	Default 15. Between 1 and 10080 (a week)
Look at this server on a schedule	Whether the scheduled look runs	Off by default

If the last look failed, The last look failed: shows the reason. Save connection saves it; Look now (on a saved connection) looks straight away; Close closes the form.

What arrives here

Once a connection is saved, What arrives here holds its feeds and what has landed.

Feeds

A feed watches the folder for files whose names match a pattern, and imports each one through a kept mapping.

Column	What it shows
Feed	Its name, with the file pattern underneath
Mapping	The kept mapping it imports through
Imported as	The person it imports as, or a red — no longer active when their account has gone
After it is read	Waits for review or Commits itself
(buttons)	Edit, and the bin icon to delete the feed

Add a feed opens the feed form:

Field	What it means	Notes
Name	What the feed is called, such as “Weekly staff export”
Files named like	The file-name pattern	`` matches any run of characters and `?` one character, such as `staff-.csv`. Matched against the name only
Mapping	The kept mapping each file is imported through	Chosen from mappings kept in the Import Studio
Imported as	The person the import runs as	Their permissions are what the import has, and their name is on every row it creates — exactly as if they had uploaded the file by hand
After it is read	Wait for review or Commit automatically	Default Wait for review: the file becomes an import that waits on the Import screen for somebody to check and commit it

Save feed saves it; Cancel discards it.

A feed cannot be anonymous: an import writes somebody’s name onto every row it creates. If the person a feed imports as leaves or loses access, the whole connection stops rather than silently importing as nobody, and a red banner says so. Name somebody else on that feed, or switch it off.

Files that landed

Every file the connection has seen, refusals first:

Column	What it shows
File	The file name, its size and when it was seen
Feed	The feed it matched, or Matched nothing
Outcome	Taken, Had it already, No feed for it or Refused
Why	For a refusal: too large to take in one piece, still being written when it was looked at (left for the next look rather than read half-written), the server would not let it be read, or the feed it matched has no kept mapping any more

Recent looks

Column	What it shows
Look	When it ran, and Scheduled or who started it
Found	How many files were seen and taken
State	Done, Some refused, Failed or In flight

What leaves here

An extract is a file this product writes to the connection for another system to read on a schedule. It is an interface, not a report, and that shapes it:

It is named and versioned. Within one version, columns may be added but never reordered or removed, so the other system’s column positions never move.
Every file ships with a manifest beside it carrying the row count and a checksum, so the system reading it can refuse a truncated file rather than load half a night’s rows.
It can send only what changed since the last run.

Column	What it shows
Extract	Its name, with its code, version and the kind of record it reads
Columns	How many columns it has
Sends	Everything, every time, Everything, first time or Changes since …
State	On, Off, Failing, or a warning: No folder to write to, No columns, Its reader has left or Not pinned
(buttons)	Edit; Files sent shows the files it has written; Send now runs it now; New version (once a version has been sent) starts a new version so columns can be reordered or removed; Send everything again (for an extract that sends changes) makes the next run a full one

With none, the section says Nothing leaves here yet. Add an extract opens the extract form:

Field	What it means	Notes
Code	What the consuming system knows this extract by	Goes in the file name, so lowercase letters, numbers and underscores, such as `asset_register`
Name	What it is called on screen
Of what	The kind of record it reads	Defaults to assets. Cannot be changed once saved: make a new extract instead, because a consumer’s loader matches on the code
Read as	The person whose permissions decide what the extract may read	An extract of people should be read as somebody who may see people
Every (minutes)	How often it is sent	Default 1440 (daily). Between 5 and 10080
Send only what has changed	Whether each run sends only changes since the last	Off by default: sending everything every time is the choice that cannot silently miss a row. The first run always sends everything
Columns	What goes in the file, in order, each with the header it is given	Add a column to the end adds one; the header box beside each renames it. Until a version has been sent, columns can be removed and are free to rearrange; afterwards they can only be added to, and New version is the way to change their shape — the version is in the file name, so the consumer sees it
Send this on a schedule	Whether it runs on its schedule	Off by default. An extract needs at least one column before it can be switched on

Save extract saves it; Stop sending this deletes it. Files sent lists each file written: Sent (when, and the file name), Rows (count and version), Checksum (the start of the checksum written in its manifest) and State (Done, Failed or In flight) — the record for “we think we are missing rows from Tuesday”.

Who can use this

To	You need (as shown on Access)	Default roles
See connections, feeds, extracts and their history	View notification templates and subscriptions (the integrations view permission)	System Administrator, Auditor, Executive
Add and change connections, feeds and extracts, and run them now	Configure integrations	System Administrator

Without the view permission the screen says Not yours to read. See roles.

Import

Keeping the mapping a feed imports through, and reviewing the imports a feed holds for review.

Setting up

Configuration

The connections list

A connection

What arrives here

Feeds

Files that landed

Recent looks

What leaves here

Who can use this

Import