Working with Users

In MaSH we can access any user available within Foldr including those from Active Directory/LDAP. There are three types of users that we can work with.

LDAP Users hosted within the Active Directory which is connected to Foldr. These user objects are read-only.

Local Users within the Foldr appliance. These users are read/write and can be created, updated and deleted by MaSH.

External These are special users which are used for sharing with external delegates. They are read/write and can be created, updated and deleted by MaSH but cannot be used to sign in to Foldr.

Retrieving Specific Users

get

mash.users.get(string: identifier, string: ?type) -> Collection|User

Retrieves a user single user object or a Collection of users which match the identifier and type provided.

Parameters

identifier

Usernames cannot be considered unique within Foldr since it is possible that LDAP users and Local/External users could have the same username. Providing a username here will return a collection of users unless a value is also provided for the type parameter.

If you provide a GUID as the identifier then this method will return a single User object.

type (optional)

Either ldap, local or external.

Natural

# This will retrieve a single user using their GUID
set myUser to mash.users.get("b8236683-6426-4658-bf6f-0e78068ca327")

printline myUser

# Since it's possible that an external user may have the same username as an LDAP user, this will return a collection of Users
set myUsers to mash.users.get("[email protected]")

printline myUsers

Standard

# This will retrieve a single user using their GUID
myUser = mash.users.get("b8236683-6426-4658-bf6f-0e78068ca327")

printline(myUser)

# Since it's possible that an external user may have the same username as an LDAP user, this will return a collection of Users
myUsers = mash.users.get("[email protected]")

printline(myUsers)

Output

Collection [
	{
	  "guid": "b8236683-6426-4658-bf6f-0e78068ca327",
	  "type": "ldap",
	  "username": "[email protected]",
	  "account_name": "grace",
	  "display_name": "Grace Hopper",
	  "personal_email": "[email protected]",
	  "directory_email": "[email protected]",
	  "personal_mobile": "+447975777666",
	  "directory_mobile": "+447975777777",
	  "last_seen": "2022-02-04T09:09:40+00:00"
	},
	{
		"guid": "e3f03995-4338-4ded-b1e5-9257a1821c40",
		"type": "local",
		"username": "[email protected]",
		"account_name": "grace",
		"display_name": "Grace Local",
		"directory_email": "[email protected]",
		"last_seen": "2022-01-24T13:15:40+00:00"
	}
]

Notes

This method can also be called via the shorthand form:

mash.user(string: identifier, string: ?type) -> User

When the shorthand form is used it will only ever return a single user object. If a username is provided as the identifier then the first matching user will be returned.

---

Retrieving All Users

all

mash.users.all(boolean: ?sync = false) -> Collection

Retrieves all users.

Parameters

sync

If this is false only Active Directory users previously seen by Foldr will be returned alongside any local or external users. If set to true MaSH will query the Active Directory directly for ldap users to return.

---

Creating Users

make

mash.users.make(dictionary: ?properties) -> User

Create a new User object. The User can be either local or external, creating ldap users is not currently supported.

Parameters

properties

A dictionary containing key/value combinations for the various properties to be set on the user. A random GUID will be generated for the new User. Note that the default type will be local.

Notes

When creating a new User object it will not be persisted until the update() method is called. This allows you to set the User’s properties before saving it.

Natural

set myUser to mash.users.make({username: "[email protected]"})

printline myUser

# Note that the user will not be persisted until you call its update() method

Standard

myUser = mash.users.make({username: "[email protected]"})

printline(myUser)

# Note that the user will not be persisted until you call its update() method

Output

User {
	"guid": "ca3101d3-a4ff-469d-b261-a9b7fddc6fbf",
	"type": "local",
	"username": "[email protected]",
	"account_name": "newuser"
}

The User Object

Properties

accountName

accountName: string  get

A short form of the username. For Active Directory users this represents the samAccountName attribute.

directoryEmail

directoryEmail: string  get

For local and external users this maps to the username attribute. For Active Directory users this maps to their LDAP email address.

displayName

displayName: string  get/set

The user’s name used within various aspects of the Foldr UI.

Notes

For Active Directory accounts this attribute is not writable.

guid

guid: string  get

The unique identifier for each user account.

lastSeen

lastSeen: date  get

The date and time that the user last accessed Foldr.

password

password: string  write

The password for the account.

Notes

For Active Directory accounts this attribute is not writable.

personalEmail

personalEmail: string  get/set

An email address used with Foldr’s self-service password reset feature.

Notes

For Active Directory accounts this attribute is stored with Foldr and not written to the directory.

personalMobile

personalMobile: string  get/set

A mobile number used with Foldr’s self-service password reset feature.

Notes

For Active Directory accounts this attribute is stored with Foldr and not written to the directory.

username

username: string  get/set

The username associated with the account.

Notes

This attribute must be unique for each type of account (ldap, local, external).

For local and external Foldr accounts this should be a valid email address. For Active Directory accounts this maps to the UPN attribute and is read-only.