Users

mash.users · Platform

mash.users looks up and creates people. Most scripts don’t need it: mash.user() with nothing in the brackets is the person the script is running as, and mash.user("name") is a shortcut for a lookup. Reach for mash.users when you need to find a user by username or GUID, or make a new local or external account.

How it works

A lookup by name gives you a list. A username can match more than one account (an external user and a local one can share a name), so mash.users.get("sam") and mash.user("sam") return a Collection of the matches. Use .first() for the one you want, and count() to see whether anyone matched. A lookup that matches nobody gives an empty list, not an error. A GUID is unique, so a GUID lookup gives the user directly.

Unsure what you’ve got? mash.debug.getClass(x) says Collection or User.

With a type, you get one user. mash.users.get("sam", "external") returns that user, or raises an error when nobody has that username and type.

A User has properties and a few changes. Read username, type (ldap, local, external, ms), groups (a list of Groups) and the profile fields. Change one by assigning to it and calling save(), or pass a dictionary to update.

Common tasks

Say who is running the script:

set me to mash.user()
printline "Running as {{me.username}}"

Find a person by name and check they exist:

set found to mash.users.get("sam.patel@example.com")
if found.count() is 0
    printline "No such user"
else
    set sam to found.first()
    printline "{{sam.username}} is a {{sam.type}} user"
end

Make an external account for a customer:

set guest to mash.users.make({
    username: "buyer@acme.example",
    type: "external"
})
guest.save()

Watch out for

• Changing users is an administrator’s job. A script run by a user needs the permission to manage users, and can’t change an account that holds more rights than it does. A script can’t create a directory (LDAP) user or rename one.
• mash.users.all() is for administrators. A script run by a user is refused. Look up the specific people you need instead.
• Usernames are unique within local accounts and within external ones. Making a user with a taken username is an error. An external account is also refused if a directory account already holds that address.
• make only builds the user. Nothing is stored until you call save().

See also

Reacting to events (mash.event.user is the person behind an event), and the User and Group types.

Methods

all

users.all(sync?: bool = false) → Collection

Get all users.

get

users.get(string?: string, type?: string) → User|Collection

Look up a user by GUID or username. Given a GUID it returns one User. Given a username it returns a Collection of the matching users, so take the first with [0].

make

users.make(data: array) → User

Create a new user.