Skip to content
Foldr MaSH docs v11.2.0.0

Send an email from a template when a field changes

What it does. When someone sets a document’s Status to Approved, the script emails the person named in its Owner Email field, using a notification template. It emails once for each approval, however many times the trigger fires.

What you need.

  • The MaSH feature.
  • A notification template, made under Settings > Notifications > Templates. Write placeholders in double braces, such as {{file}}, {{status}} and {{link_name}}. The script fills them in. Call the template Document approved.
  • Fields on the share: Status and Owner Email.
  • The trigger Fields Changed on Settings > MaSH > Events, filtered to the share’s path. This event fires when a person, a script or the API changes fields. Captur’s own writes don’t fire it. See Events.
  • On Foldr Cloud, mash.mail sends only to members of your organisation. An email to an outside address needs your own mail server, with mail.client. See Foldr Cloud and appliances.

The message, on its own

Section titled “The message, on its own”

The data you give the template is a dictionary. This block builds it and the subject line, so you can test them without sending anything:

block messageFor fileName status owner
    set data to {
        "file": fileName,
        "status": status,
        "owner": owner
    }
    set subject to "{{fileName}} is now {{status}}"
    return {"subject": subject, "data": data}
end


set msg to messageFor("INV-2041.pdf", "Approved", "sam@example.com")
printline msg["subject"]
printline msg["data"]["owner"]
INV-2041.pdf is now Approved
sam@example.com

The script

Section titled “The script”
set errorblock to "onError"
block onError
    printline "Error on line {{mash.error.line}}: {{mash.error.message}}"
end


set doc to mash.event.file
if not doc
    return
end
if doc.is_dir
    return
end


set status to doc.fields["Status"] ?? ""
set owner to mash.str(doc.fields["Owner Email"] ?? "").trim().toString()


if status is not "Approved"
    return
end


if owner is ""
    printline "{{doc.name}} is approved but has no Owner Email. Nobody was told."
    return
end


# Once only. The key names this document and what it was approved as, so a
# re-approval after a change sends again, but a repeat trigger does not.
mash.store.register("approval-emails")
set key to "{{doc.share.id}}:{{doc.path}}:{{doc.hash}}"


if mash.store.get(key)
    return
end


mash.mail.sendWithTemplate(
    "Document approved",
    owner,
    "{{doc.name}} is now Approved",
    {"file": doc.name, "status": status, "owner": owner}
)


mash.store.set(key, mash.date.now().format("Y-m-d H:i:s P"))
printline "Told {{owner}} that {{doc.name}} is approved."

How it works

Section titled “How it works”
  1. The guards stop the script early unless there’s a file, the status is Approved and an address is present. A document with no address prints a line, so the run log shows who wasn’t told.
  2. The store key is what makes it once only. A trigger can fire twice for one approval, and the script must not email twice. The key includes the file’s hash (a fingerprint of its content), so a changed file that is approved again sends again. Drop doc.hash from the key to send only one email for a document, ever.
  3. mash.mail.sendWithTemplate takes the template’s name (or id), the recipient, a subject, and the dictionary of values for the placeholders. Messages go into a queue and leave shortly after.
  4. The store write comes after the send. If the send fails, nothing is recorded and the next trigger tries again. If you’d rather never send twice, record first.

A missing template stops the send with an error that names it: no notification template called "Document approved". Check the name in Settings > Notifications > Templates.

Variations

Section titled “Variations”
  • Several people. Pass a list as the recipient, or add cc and bcc lists after the attachments argument.
  • Attach the file. Add [doc] as the next argument after the data: sendWithTemplate(name, owner, subject, data, [doc]).
  • A plain email. Skip the template: mash.mail.send(owner, subject, "Body text").
  • Tell the person who made the change. mash.event.user is the share’s user on this event, so it doesn’t name the editor. Put the editor’s address in a field if you need it.
  • Other values. Test for any field value, such as a due date in the past, then send a reminder. A schedule suits date-based checks better than a field trigger.

Library pages used: Mail, Store.