A script that only runs when you press Run is a notebook. The useful ones start by themselves. This article shows an administrator how to attach a saved script to an event, a schedule or a webhook, and where to look afterwards. For how each one works in detail, and what the script receives, see the developer docs.
What you’ll need
- A saved script. See the MaSH script editor.
- The MaSH feature, and access to Settings > Scripting > MaSH.
Everything below is on that page. Its tabs are Scripts, Users & groups, Events, Schedule, Webhooks and Logs.
Run a script when something happens (an event)
- Open Settings > Scripting > MaSH > Events.
- Find the event under its group and choose Add script.
- Pick your script.
- Use the Configuration icon beside the script to set its config parameters. The same script can be attached to two events with different settings.
- Use the Filter icon to narrow when it runs, by Path prefix or Extension.
These are the events Foldr offers:
| Group | Events |
|---|---|
| Files | Uploaded, Downloaded, Deleted, Crawled, Indexed, Captur Extracted, Fields Changed, Mail Received |
| Users | Signed In |
| Sign | Envelope Completed |
| Forms | Form Completed |
There are no events for moving, copying or sharing a file. To catch up with those, use Fields Changed or a schedule.
Two things catch people out:
- Indexed can fire before Captur has written anything. Attach the script to Captur Extracted to act on what Captur found. Captur’s own writes don’t fire Fields Changed.
- A script attached to a share’s own settings 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.
The page for each event lists what the script gets in mash.event. See Events in the developer docs.
Run a script at set times (a schedule)
- Open Settings > Scripting > MaSH > Schedule and choose Add schedule.
- Pick the Script, and add a Description if you like.
- Choose a Frequency: Daily, Weekly, Monthly, Cron or Once. Fill in the box it shows.
- Set the Timezone.
- Under Files to run on, choose what the script gets: no files, a folder listing, a glob pattern, files matching field criteria, or an explicit list.
- Choose Save.
A schedule has no event, so it has no file of its own. The script runs once for each time slot, with the whole list of files in mash.event.files. It does not run once per file. Hour boxes run on the hour only, so use Cron for anything finer. See Schedules.
Run a script when another system calls Foldr (a webhook)
- Open Settings > Scripting > MaSH > Webhooks and choose Add webhook.
- Pick the Script and add a Description.
- Optionally set a Username and Password. The caller must then send them as HTTP Basic Auth.
- Choose Save. The URL column now shows the address, with a copy button.
The key in the address is the secret: anyone who has it can call the webhook. If it leaks, choose Create new URL and the old address stops working at once. The script reads the request from mash.event.input. There is no mash.request. See Webhooks.
Check that it ran
Open Settings > Scripting > MaSH > Logs. Each row shows the Date, Script, Trigger, Status and Duration. Open a row to see its Output, any Error, its Effects on files and fields, and Unhandled errors.
A status of Complete means the script reached its end. It doesn’t mean every statement worked, because a failed statement is recorded and the script carries on. Always check Unhandled errors too. A run you start by hand from the editor, and a successful webhook, don’t add a row. See The run log.
A script whose owner has left your directory refuses to run until it has a new owner. On the Scripts tab, use the Change owner icon on the script to pick one.
Other ways a script starts
Scripts can also run from a file’s action menu (set up under Users & groups), from a form, a signing envelope or a review, from Grace, and from another script. See Where scripts run.