Events

An event is something that happens in Foldr: a file arrives, a field changes, someone signs in. You attach a saved script to an event and Foldr runs it each time. The tutorial’s Reacting to events chapter walks through the first one. This page is the reference.

Attach a script

1. Open Settings > MaSH > Events.
2. Find the event under its group and choose Add script.
3. Pick your script.
4. Use the Configuration icon beside the script to fill in its config parameters. The same script can be attached to two events with different settings.
5. Use the Filter icon to narrow when it runs (see below).

A share’s own settings can also carry scripts. A script attached to a share runs only for that share’s files. One attached on this tab runs for every share. If the same script is attached both ways, it runs once for an event.

A script that is switched off doesn’t run from an event or a schedule, whatever is attached.

The events

Group	Event	Fires when
Files	Uploaded	a file is uploaded
Files	Downloaded	a file is downloaded
Files	Deleted	a file is deleted
Files	Crawled	the crawler visited a file, whether or not it was indexed
Files	Indexed	search indexed a file
Files	Captur Extracted	Captur finished reading a file, or failed to
Files	Fields Changed	a person, a script or the API changed a file’s custom fields. Captur’s own writes don’t fire it: use Captur Extracted for those.
Files	Mail Received	an email arrived in an Inbox share
Users	Signed In	a person signed in
Sign	Envelope Completed	every signer has signed an envelope
Forms	Form Completed	a form was submitted

There are no events for moving, copying or sharing a file. Foldr can’t trigger a script on those yet. Use Fields Changed or a schedule when you need to catch up with them.

What mash.event holds

Every event offers mash.event.file, mash.event.files, mash.event.share, mash.event.path, mash.event.user, mash.event.input and mash.event.count. Which ones have a value depends on the event.

Event	What is filled in
Uploaded, Downloaded, Crawled, Indexed	file is the file. files is a list holding just that file. user is the person who caused it, when there is one.
Fields Changed	the file, as above. mash.event.input["updated"] holds the fields that changed. user is the share’s own user, so don’t rely on it to name who made the change.
Deleted	file is the file that was deleted
Captur Extracted	the file, plus outcome, fieldsWritten, pagesRead, pagesTotal, valuesNeedingCheck, fingerprint and error
Mail Received	file is the Inbox folder the email landed in. files holds the attachments. mail holds from, from_display, to, subject, body_path, message_id and received_at.
Signed In	user only
Envelope Completed	envelope, signers and documents
Form Completed	form, answers and submission. user is empty when the submitter was anonymous.

The library page for mash.event lists every member. mash.event.count says how deep a chain of events is. See “Chains of events” below.

A guard at the top of the script makes it safe to test by hand, where there is no event:

doc = mash.event.file

if not doc
    printline "Run by hand: no file."
    return
end

printline "Event {{mash.event.count}} about {{doc.name}}"

Run by hand: no file.

Reading the event’s fields before they are ready is the usual trap. On Indexed, Captur may not have written anything yet, and its writes never fire Fields Changed, so use Captur Extracted to come back when they land. A field that is set up on the share but empty reads as null. Read it with ?? so an early run returns quietly:

doc = mash.event.file
if not doc
    return
end

reference = doc.fields["Order No"] ?? ""
if reference == ""
    return
end
printline "Order {{reference}}"

Filters

The Filter icon opens Event filter with two boxes:

• Path prefix: the script runs only for files under this path, for example Reports/Q1.
• Extension: the script runs only for these extensions, for example pdf, docx. Case and a leading dot don’t matter.

Both must match when both are set. Empty means no filter. A script that is filtered out never starts, which costs nothing, so filter here rather than returning early in the script.

Filters apply to file events only. Mail Received, Envelope Completed and Form Completed ignore them, because they have no file path to match. A file event with no path never passes a filter.

One run per event, no retries

Each event starts one run per attached script. Scripts attached to the same event run one after another, not together. If a run fails or times out, Foldr doesn’t try again, because a second attempt could repeat what the first already did: an email sent, a file written. The failure shows on the run log, and on the Failed jobs page when the worker itself died.

An event script runs in a separate process with the same time limit as any queued run: 60 seconds, on Foldr Cloud and on an appliance (an appliance can raise it with MASH_TIMEOUT, see Limits).

Chains of events

A script that changes a file can fire more events (a script that sets a field on its file fires Fields Changed for it when the run ends), and those can start scripts, which change more files. Each step in the chain counts one deeper in mash.event.count. A chain stops when it reaches a depth of ten, with Max recursion (10 iterations) reached, and the run that hit the limit does nothing.

The ten-step limit is a safety net, not a design. A script that watches a share and writes into it starts itself. Keep your output away from your input, check the work isn’t already done, and return early for files you made. The tutorial’s safe event script lists the four habits. The file-by-field guide shows them in a finished script.

Who it runs as

An event script runs as the script’s owner. See Who a script runs as. Its mash.event.user is a different thing: it is the person who caused the event, not the person the script runs as.