Grace and Captur

Writing a script with Grace

Grace is Foldr’s assistant. Ask her in plain words to set up something that should run by itself, and she drafts the script and its trigger for you.

1. Open Grace from the file browser. If you’re inside a share’s folder, she knows which one.
2. Describe the job. Say when it should run, which folder, which file type and which fields. “When a PDF arrives in Invoices, copy it into the folder named in its Customer field” works better than “tidy my invoices”.
3. Grace shows a card with the script, the trigger, and any settings it needs.
4. Read the script. Fix anything wrong by telling Grace, or edit it later in the editor.
5. Choose Set it up. Only now is anything saved.

Nothing is saved until you choose Set it up. Grace drafts only. The script is saved as a script you own, so your own rights are what it runs with. A script she wrote shows a sparkle icon (Authored by Grace) in Settings > MaSH > Scripts.

You need the permission to use Grace automations. If the option is missing, ask your administrator.

What Grace checks before you set it up

Grace tries to catch the usual mistakes while you can still stop:

• A trigger that doesn’t exist. Moves, copies and shares aren’t events. If the draft was built on one, the card says the draft has no trigger and can’t be set up as it is. Tell Grace when it should run instead.
• Settings the script reads. A setting the script reads but the card can’t ask for is listed, because it would read as empty on every run.
• A script that triggers itself. She narrows the trigger so the script stays off its own output.
• A field-change trigger on a share Captur fills. She warns, because Captur’s own writes would fire it.
• A schedule with no files. She warns when a schedule’s script expects files but none are chosen.
• Her opening check, tried on your files. This is the rehearsal.

The rehearsal

A drafted script usually opens with a check, such as “return unless the file has an Order No”. A check no file passes looks like a working automation from the outside: every run says “complete” and nothing happens. So Grace tries the check against up to 20 real files in the folder you’re working in, before you set anything up, and tells you how many get past it.

The rehearsal is cautious:

• It runs only the opening guard, never the body of the script.
• It runs in the virtual sandbox, so nothing is written, no email is sent and no web call is made.
• It stops after about four seconds and reports what it did check.
• It covers only scripts that open with top-level ensure … else return guards. If the check sits inside a loop, or there’s no opening guard, nothing is rehearsed and Grace says nothing about it.

A rehearsal that says “0 of 20 would get past the check” is worth acting on. The usual cause is asking for every field when real files leave some empty.

Grace also has her own library object, mash.grace, for scripts that call a model. See Grace. Calls to a model use Grace credits.

Captur

Captur reads documents and writes what it finds into custom fields. A script touches it in two places.

As a trigger. Captur Extracted fires when Captur finishes a file, or fails. The script gets mash.event.outcome, fieldsWritten, pagesRead, pagesTotal, valuesNeedingCheck, fingerprint and error. It is the cleanest signal that the fields are ready. Indexed can fire first, with empty fields. valuesNeedingCheck is a snapshot taken before automations run, and a failed event reports 0 even when checks are still outstanding, so don’t read 0 as “all clear” when outcome is failed. The outcome is ok or failed. The event doesn’t fire when Captur skips a file that already has its values.

As an object. mash.captur extracts on demand (extract, queue) and manages the “needs a check” flags on a field (check, clearCheck, checks). It needs the Captur feature on the tenant. extract refuses the file that triggered the script, so a Fields Changed or Captur Extracted script can’t ask Captur to re-read the very file it is working on.

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

if mash.event.outcome == "failed"
    printline "Captur did not finish: {{mash.event.error}}"
    return
end

printline "Captur wrote {{mash.event.fieldsWritten}} fields on {{doc.name}}"

See the Captur library page for every method and option.