Fields

mash.fields · Platform

mash.fields is for custom fields across the whole tenant: which fields exist, which values are in use, and which files carry a value. To read or write a field on one file, use that file’s own fields (see File). Use mash.fields when you don’t have the file yet, or when you want to ask a question about many files at once.

How it works

A script sees only what its owner can read. A script run by a user searches that user’s shares and nothing else. A script owned by an administrator searches every share. Pass a user as the last argument to answer as someone else (a script run by a user can’t).

get gives you the field itself. mash.fields.get("Status") takes a name, an id or a UUID and returns the field. Hold it in a variable and pass it where a name is accepted: file.fields[f], mash.search.byField(share, f, ...). A field the script can’t see is reported as “not found”, the same as one that doesn’t exist.

Results are plain data. list gives dictionaries with id, name, type, multivalue, share_ids and, where the share limits them, allowed_values. findFiles gives dictionaries with share_id, share_name, path and name, which is what mash.files.get(hit["share_id"], hit["path"]) wants. Each of search, findFiles returns at most 100 rows.

Exact, not search-engine. These calls read the database, so a value written a moment ago is found at once. (Full-text search can lag behind.)

Common tasks

List the fields a script can use:

each mash.fields.list() as f
    printline "{{f['name']}} ({{f['type']}}) on {{count(f['share_ids'])}} shares"
end

Find every document for an order, whichever share it’s on:

set filters to {}
set filters["Order No"] to "SO-20417"
each mash.fields.findFiles(filters) as hit
    set file to mash.files.get(hit["share_id"], hit["path"])
    printline "{{file.name}} on {{file.share.name}}"
end

Offer the values already in use, for a prefix someone has typed:

set seen to mash.fields.search("Customer", "Ac")
printline mash.collect(seen).join(", ")

Spot a near-duplicate before you add a new value:

set close to mash.fields.findSimilar("Customer", "Acme Limted")
if count(close) is more than 0
    printline "Did you mean {{close[0]}}?"
end

Watch out for

• get stops the run when nothing matches. The error isn’t one an error block catches. Look the field up with list first if the name comes from outside.
• Put the user last. The older calls took the user first. That order still works for now, but write new scripts with the user last, or leave it out.
• Folders carry no fields. findFiles only ever returns files.
• A filter needs every field. findFiles only searches shares where the script may see every field in the filter.
• Only files with a value are found. You can’t ask for “files with this field empty”. Set a starting value (such as Status = Pending) when you first see a file, then look for that.

See also

Custom fields in the tutorial, mash.search.byField for walking a share’s files by field value, and the File type.

Tenant-wide enumeration and querying of custom fields.

Methods

findFiles

fields.findFiles(filters: mixed, user?: mixed) → array

Find files where every {field => value} filter matches, on the shares the run’s user can read. Returns up to 100 files.

filters: {field_name_or_id: value, …}

findSimilar

fields.findSimilar(field: mixed, value?: mixed = "", user?: mixed) → array

Fuzzy-match values for a field — direct passthrough to the helper shared with Grace and search tooling. Catches typos, OCR errors, spacing/punctuation variants (“A.B.C.” ≈ “ABC”), abbreviations (“Mktg” ≈ “Marketing”).

get

fields.get(handle: mixed, user?: mixed) → CustomField

A custom field by name, id or UUID, to hold and pass on: f = mash.fields.get(“Status”) file.fields[f] = “done” Found only on a share the run’s user can read (pass a user to answer as someone else). Throws when nothing matches. f.id, f.name, f.type, f.multivalue.

list

fields.list(user?: mixed) → array

List custom fields on the shares the run’s user can see (all shares for an elevated run). Each entry: {id, name, type, multivalue, allowed_values?, share_ids}.

search

fields.search(field: mixed, prefix?: mixed = "", user?: mixed) → array

Distinct values for a field, across the run’s user’s shares. Optional prefix filter. Returns up to 100 values.