Event

mash.event · Core

mash.event describes what started the script: the file that arrived, the person who did it, the email that came in, or the input another script passed on. It’s how an event, a schedule, a webhook or a call from another script hands a script its work.

How it works

Which properties are filled depends on how the script started. An upload fills file and user. A mail event fills mail. A schedule fills files. A call to mash.scripts.run(..., input) or a webhook fills input. A script run by hand from the editor has none of them unless you pick a test file and user.

Missing things are null, not errors. mash.event.file is null when there’s no file, so test for it first. Objects are always “true” in MaSH, so if not mash.event.file is the right guard, and count() is the right test for an empty list.

A file the run isn’t allowed to see is refused when you read it. On some events the file belongs to someone the run’s owner can’t read. Reading mash.event.file then raises an error rather than handing the file over.

input carries data from outside. When the script was started with input (by another script, a webhook, a form or a schedule), it arrives as a Collection you can read with get("key") or ["key"].

Common tasks

Guard against being run by hand, and say what you got:

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.

Read input with defaults, so the script also works with none:

set input to mash.event.input ?? {}
set mode to input["mode"] ?? "preview"
printline "Mode: {{mode}}"

Mode: preview

Handle a scheduled run’s list of files, and notice when it was cut short:

each mash.event.files ?? [] as doc
    printline doc.name
end
if mash.event.files_truncated
    printline "More files matched than this run took. The next run will pick up the rest."
end

Act as the person who caused the event:

set who to mash.event.user
if who
    printline "{{who.username}} did this"
end

Watch out for

• mash.event.user is the person who caused the event, not the script’s owner. Use mash.user() for the identity the script runs as.
• Always check file for folders and the wrong extension before you work on it. See Reacting to events.
• Write your output somewhere the script isn’t listening. A script that saves into the folder that triggers it runs again.

See also

Reacting to events, mash.scripts for passing input to another script, and the File type.

What started this run. A trigger, a schedule, a form or a mail rule fills it in; a run started by hand has an empty one. Which properties hold something depends on the kind of event.

Properties

Name	Type	Description
id	int	The id of the event type.
name	string	The event type, in snake case: file_uploaded, user_sign_in.
file	File	The file the event is about. Null for sign-in and mail events. Reading it fails when the storage refused to open it.
files	File[]	The files the event is about, when it is about several. One entry when there is a single file.
shared_file	File	For an event that came through a public link: the item the link shares.
path	string	The path of the file, or the path the event names.
share	Share	The share the event happened on.
user	User	The person who caused the event. Null when nobody did.
input	dictionary	What the trigger was given: the fields of a form, the values of a scheduled run. For a webhook, input.foldr_request is the request itself (see Request).
count	int	How many scripts in a row this event chain has started. Use it to stop a script that triggers itself.
files_truncated	bool	True when files holds only part of what matched.
total_matched	int	How many files matched, when files holds only part.
mail	dictionary	The message, for a mail received event. Null otherwise.
envelope	dictionary	Envelope completed events only: the envelope that was signed.
signers	array	Envelope completed events only: each signer, with uuid, email, name, role, status and signed_at.
documents	array	Envelope completed events only: each written bundle, with share_id, path and sha256.
outcome	string	File extracted events only: how extraction went. “failed” comes with error.
fieldsWritten	int	File extracted events only: how many fields it filled in.
pagesRead	int	File extracted events only: how many pages it read.
pagesTotal	int	File extracted events only: how many pages the file has.
valuesNeedingCheck	int	File extracted events only: how many values were flagged for a check. A count taken before automations ran.
fingerprint	string	File extracted events only: a fingerprint of the values that need a check.
error	string	File extracted events only: the first line of the failure, when outcome is “failed”.
form	dictionary	Form completed events only: the form.
answers	dictionary	Form completed and form script events: what was answered.
submission	dictionary	Form completed events only: the submission.
vars	dictionary	Form script events only: the variables the form passed in.