The MaSH script editor

The MaSH designer is where you write, test and save MaSH scripts (also called mashlets). It has two modes, Visual and Code, and both edit the same script. This article tours the editor itself. For the language, see the MaSH docs.

What you’ll need

The MaSH feature, and access to Settings > Scripting > MaSH. On Foldr Cloud, MaSH comes with Business and Enterprise. On an appliance it is a licence. The editor is open to administrators who can manage MaSH.

Opening the editor

  1. Go to Settings > Scripting > MaSH. The Scripts tab lists your scripts, grouped into folders.
  2. To start a new script, choose Add script. To change an existing one, choose the Edit icon on its row, or double-click the row.

The editor opens in a new browser tab. Its address carries the script, so reloading the tab brings the same script back.

The toolbar

The MaSH designer in Visual mode: the toolbar across the top, the action palette on the left and the script as cards

From left to right:

  • The script name. Click it to rename the script. A | in a name makes folders, so Invoices | Tidy is a script called Tidy in a folder called Invoices. Names don’t have to be unique, but a clear one helps you later. An orange dot beside the name means you have unsaved changes.
  • Undo and Redo, in Visual mode only. In Code mode the code editor has its own undo.
  • New Script and Open script. Open script lists your scripts as a tree you can search.
  • Blueprints, in Visual mode only. A blueprint is a ready-made starting point you can drop into the script.
  • Visual mode, Code mode and a layout button. The layout button moves the bottom panels beside the script instead of under it.
  • Save, with a drop-down for Save As… and Save as Blueprint.
  • Set test file and Set test user.
  • Virtual mode, shown as a flask.
  • Run. While a script is running it becomes Stop.
  • Grace, if Grace is switched on for you.

Visual mode and Code mode

Visual mode shows the script as cards you can drag, with an action palette on the left. Each card is a real MaSH instruction. The Code tab at the bottom shows the text the cards produce, in either the natural syntax or the braces syntax.

Code mode shows the script as text, with syntax colouring, completions and a find and replace panel (Ctrl+F and Ctrl+H).

When you switch from Code to Visual, the editor reads your code again and turns it into cards. Anything it can’t draw may be simplified or lost, so it asks you to confirm first. If the code can’t be read at all, you stay in Code mode and the editor says why.

Running a script

Choose Run. The Output panel opens and shows what the script printed.

The editor in Code mode with a small script, and the Output panel showing its two lines of output

A run you start here is not a real event, so there is no file or user unless you give it one:

  • Set test file opens a file picker. The file you choose becomes mash.event.file, as if the event had fired for it.
  • Set test user opens Select test user. The person you choose becomes mash.event.user.

Both show as a small badge on the toolbar. Click the × on a badge to clear it.

Be careful with real files. Run runs the text on screen with the rights of the administrator running it. If the script moves, renames or emails, a run against a real file really does it. Use a copy of a document, or turn on Virtual mode.

Virtual mode

The flask button switches Virtual mode on and off. With it on, the script runs against mock files and mock I/O, so nothing real changes. The Output panel then shows a Virtual Runtime — Operations Log of what the script would have done, and Virtual Filesystem Changes. Hover over the button to see which mode you’re in.

The panels under the script

In Visual mode the tabs are Code, Blocks, Config, Variables, Issues, Capabilities, Output and History. In Code mode only Config, Capabilities, Output and History appear.

  • Config. Config parameters are named settings a script reads with mash.config.get("NAME"), so the same script can run against a different share or folder without editing the code. Choose + to add one, give it a name, pick a type (String, Number, Boolean, File, Share, Service account or Custom field) and a default. When you attach the script to an event, schedule or webhook, you can set different values for each.
  • Blocks. The script’s own blocks (MaSH’s functions), which you define and name here and call from elsewhere in the script. See Blocks and calls.
  • Variables. The variables the script has so far. In Visual mode you can drag one into an expression field.
  • Issues. Problems the editor found before you run: a variable that isn’t declared, or a value of the wrong type for a field. Choose one to jump to the card.
  • Capabilities. What the script can touch (files, mail, HTTP requests, databases and so on), found by reading the code. It is a guide, not a guarantee: it may not match what happens at run time.
  • Output. What the last run printed, with the result of the run.
  • History. Every save keeps a version. Choose a version to see what changed, and restore an earlier one. The current script stays in the history, so a restore can be undone. History appears once the script has been saved.

Reading the Output panel

A status line at the top says Running…, Complete or Failed. A script that stops on an error prints Error (line n): .... In Code mode the line is marked in the editor. In Visual mode the card that caused it is selected.

A failed statement in MaSH doesn’t always stop the script. It records the error and carries on. These are the Unhandled errors. When a run has any, the Output tab shows a number badge and the panel lists Unhandled errors (n) under the output. Each entry gives the line, the message, a count if it happened more than once, and the expression. Click an entry to go to that line. A run with unhandled errors still finishes as Complete, so check this list as well as the status. The docs explain more.

Use Clear to empty the panel before the next run.

Saving

Save keeps the script and adds a version to its history. Save As… saves a copy under a new name. Save as Blueprint keeps the script as a blueprint for Visual mode.

If someone else saved the same script while you had it open, the editor tells you and saves nothing. Open History to see what changed, then choose Discard mine and load theirs or Keep mine — save over theirs.

Saving doesn’t make a script run by itself. To run it when something happens, attach it on the Events, Schedule or Webhooks tab. See Running scripts from events, schedules and webhooks.

Asking Grace

If Grace is switched on for you, the Grace button opens her panel beside the editor. Describe what you want and she drafts a script. You can accept her draft into the editor, then test it as you would your own. Writing automations needs the Author Grace Automations permission. See Grace.

Keyboard shortcuts

ShortcutWhat it does
Ctrl+S (Cmd+S on a Mac)Save, in both modes
Ctrl+Z and Ctrl+Shift+ZUndo and redo, in Visual mode
Ctrl+K (Cmd+K on a Mac)Open or close the Grace panel
Ctrl+F and Ctrl+HFind, and find and replace, in Code mode

Where to go next

← All articles