File-triggered workflows
Kick off a workflow automatically when a file arrives, and label the files it receives.
A workflow can start on its own the moment a file lands in your workspace. This connects the Files area to the Workflows area: a file arriving is an event, and a workflow can listen for it. The listener is the File Received trigger, which fires for a file whether it was uploaded on the Files page or pushed over Managed SFTP. A file attached in a thread or uploaded into a task starts no workflow.
Only workflows that are Active and not archived are started. See Build a workflow for activating one.
Choose at upload whether workflows run
Uploads from the Files page let you decide whether an arriving file may start a workflow:
- From the New dialog. Each file under Selected files says how many workflows it would start, for example 1 workflow to be triggered; hover the badge to see their names and status. Leave the Trigger workflows checkbox selected to let them run, or clear it to store the files quietly. It is on by default.
- By dropping files on the list. SPARK asks once for the whole drop, and only when a workflow would start: Upload and run starts them, Upload only stores the files without starting anything.
See Organize files for both ways to upload.
Files that arrive over SFTP or by email have no such question: a matching workflow always starts.
Match the right files
The File Received trigger does not fire for every file. Select the trigger on the workflow canvas and narrow it in the side panel so only relevant files start a run:
| Section | Setting | Matches on |
|---|---|---|
| File Extension | A pick from csv, txt, pdf, xlsx, xls and dat, or Custom... for any other, such as json | The file's extension, given without its dot |
| File Matching Logic, Pattern builder tab | Starts with | A prefix on the file name |
| Name includes | A substring anywhere in the file name | |
| Ends with | A suffix on the whole file name, the extension included | |
| File Matching Logic, Regular Expression tab | Regular expression | A pattern matched anywhere in the file name, for example ^invoice_\d{4}.*\.csv$ |
| Provider | A provider name | Recorded on the trigger |
How the matching works:
- Every condition you fill in must match. Leave one empty and it is ignored.
- Matching reads the name the file was uploaded with, and ignores upper and lower case throughout, the regular expression included.
- A regular expression matches anywhere in the name unless you anchor it with
^and$. One that does not compile starts nothing. - The Provider field does not filter which files start the workflow.
A workspace can therefore hold many file-triggered workflows that each react to a different kind of file. A file that matches several of them starts each one.
SPARK does not drop a repeated file. Each copy is stored and starts the workflow again, so make re-processing safe where the data lands, for example with Replace Existing Records on a Save Record step.
Build the workflow
The trigger is one action in a larger flow. Add a File Received trigger as the workflow's starting action, set its conditions, then add the steps that read, transform or load the file:
- Read a CSV or Excel file for delimited files and workbooks.
- Read documents for PDFs and other documents to extract values from.
- Save records to write the result into a data object.
For the mechanics of assembling actions, see Build a workflow.
Label the files a run received
The Apply File Label action labels the files that reached it, so arrivals can be grouped, filtered and found later by the feed they came from. It is in the Data group of the node picker. In its side panel, you write rules, each one a short sentence:
- Click Add rule.
- Choose what the rule matches: Every file, Name contains (with the text to look for, for example
NAV), or Name matches (a regular expression, marked advanced, for example^NAV_\d{8}\.csv$). - After the arrow, pick the labels a matching file earns.
Add as many rules as you need. One workflow can then serve several feeds: a File Received trigger watching a whole SFTP folder feeds one Apply File Label step, which tags each file with the feed it came from.
How the rules apply:
- Rules are additive. A file gets the labels of every rule it matches, not only the first, so a NAV file that is also a month-end file can carry both labels. A file that matches no rule is left unlabelled.
- Name contains ignores upper and lower case. Rules read the name the file was uploaded with.
- By default the labels are added to the ones the file already has. Turn on Replace Existing to replace them instead. Adding is the safer choice when one file can start several workflows, since replacing would let two of them drop each other's labels.
- Labels are given by name, so the same workflow works unchanged in every workspace. Each label must already exist: a name the workspace does not have fails the run with Unknown file label(s), so create labels on the Files page first.
A rule is Every file, Name contains or Name matches (marked advanced), then the text, then the label it gives, picked from the workspace's existing file labels. A rule that is half finished, with no text or no label yet, is not saved, and the panel says what it is missing: Fill in the text and pick a label. (or Pick a label to apply. for Every file).