Reacting to events

So far you’ve run scripts by hand. The real power comes when a script runs by itself: when a file arrives, when someone changes a field, every morning at seven, or when another system calls a web address.

Four ways a script runs

How	When it runs	Where you set it up
By hand	you choose Run in the editor, or pick it from a file’s action menu	the editor
Event	something happens in Foldr, such as a file upload	Settings > MaSH > Events
Schedule	on a timetable, against a list of files	Settings > MaSH > Schedule
Webhook	an outside system calls a URL Foldr gives it	Settings > MaSH > Webhooks

Run history for all of them is on the Logs tab.

What triggers a script

The Events tab lists the events a script can listen to, grouped as Files, Users, Sign and Forms:

Event	Fires when
Uploaded	a file is uploaded through the web app, a desktop app or the API
Downloaded	a file is downloaded
Deleted	a file is deleted
Crawled	the crawler visited the file, whether or not it was indexed
Indexed	search has indexed the file
Captur Extracted	Captur has finished reading the file, or failed to
Fields Changed	a person, a script or the API changed the file’s custom fields (not Captur’s own writes)
Mail Received	an email arrived in an Inbox share
Signed In	a person signed in
Envelope Completed	everyone has signed a signing envelope
Form Completed	someone submitted a form

Moves, copies and shares don’t have events. If you need to react to one, use Fields Changed or a schedule instead.

To attach a saved script to an event:

1. Open Settings > MaSH > Events.
2. Find the event under its group and choose Add script.
3. Pick your script.
4. Use the filter icon beside the script to limit it to a Path prefix (a share or folder) or an Extension (such as pdf).

Filtering here is better than filtering inside the script. A script that never starts costs nothing.

Reading what happened

When an event starts a script, the details are in mash.event:

Property	What it holds
mash.event.file	the file the event is about (empty for sign-in and mail events)
mash.event.user	the person who caused it, when there is one
mash.event.mail	the email, for a mail event
mash.event.files_truncated	on a schedule: true if the list was cut short

Run by hand, there’s no event, so these are empty. That makes this guard worth putting at the top of every event script:

Natural

set doc to mash.event.file

if not doc
    printline "No file: this script was run by hand."
    return
end

printline "Working on {{doc.name}}"

No file: this script was run by hand.

Standard

doc = mash.event.file

if (not doc) {
    printline("No file: this script was run by hand.")
    return
}

printline("Working on {{doc.name}}")

No file: this script was run by hand.

In the editor, you can test an event script without waiting for the real event. Use Pick file to choose a file and Select test user to choose a person, then Run.

Settings that belong to the automation

A script often needs values that change from one use to the next: which share to file into, what to call a folder. Don’t type them into the script. Declare them as config parameters in the editor (the Add config parameter button) and read them with mash.config.get:

Natural

set greeting to mash.config.get("GREETING") ?? "Hello"
printline "{{greeting}}, world"

Hello, world

Standard

greeting = mash.config.get("GREETING") ?? "Hello"
printline("{{greeting}}, world")

Hello, world

When you add the script to an event, a Configuration button appears beside it. Fill in the values there. The same script can then serve two shares with different settings. The ?? supplies a default for when nobody set one.

A safe event script

A script that changes files can trigger more events, and those can run the script again. Four habits stop trouble:

1. Check the file is one you want. Return early for folders, other file types and files that don’t match.
2. Check the fields are ready. On the first Indexed event Captur may not have finished. Return quietly and let Captur Extracted bring you back. Fields Changed won’t: Captur’s own writes don’t fire it, only changes made by a person, a script or the API.
3. Make it safe to run twice. Check whether the work is already done before you do it.
4. Keep your output away from your input. If a script writes a file into the share it watches, it triggers itself. Write somewhere it isn’t listening, or return early for the file it just made.

Here’s the skeleton of a good event script. It runs here, by hand, and stops at the first guard:

Natural

set doc to mash.event.file

# Guard 1: there must be a file, and it must not be a folder
if not doc
    return
end
if doc.is_dir
    return
end

# Guard 2: the file must be a PDF
if doc.extension is not "pdf"
    return
end

printline "Would process {{doc.name}}"

Standard

doc = mash.event.file

# Guard 1: there must be a file, and it must not be a folder
if (not doc) {
    return
}
if (doc.is_dir) {
    return
}

# Guard 2: the file must be a PDF
if (doc.extension != "pdf") {
    return
}

printline("Would process {{doc.name}}")

Because nothing is attached, it prints nothing. On a real upload of scan.pdf it prints Would process scan.pdf.

Schedules and webhooks

A schedule runs your script on a timetable. Choose Settings > MaSH > Schedule > Add schedule, then pick the script and set the Frequency (Daily, Weekly, Monthly, Cron or Once). Under Files to run on, choose where the script’s files come from: a Folder listing, a Glob pattern, Files matching field criteria, an Explicit list of files, or none.

The script runs once per timetable slot, not once per file. The files arrive together as a list in mash.event.files, and mash.event.file is empty. Loop over the list:

Natural

each mash.event.files as doc
    printline "Would process {{doc.name}}"
end
printline "Done"

Done

Standard

each (mash.event.files) as doc {
    printline("Would process {{doc.name}}")
}
printline("Done")

Done

Run by hand there are no files, so only the last line prints. A schedule hands over at most 1,000 files. mash.event.files_truncated tells you when it cut the list short.

A webhook gives your script a web address. When an outside system calls it, the script runs and what it returns goes back to the caller. Treat the address as a secret. If it leaks, use Create new URL on the webhook and give the new address to whoever needs it.

Try it

Write an event script for Uploaded, filtered to the extension pdf. Have it print the file’s name and size. Upload a PDF to the share, then check Settings > MaSH > Logs for the run.

Next, you’ll reach beyond Foldr: other systems, data formats and email.