User Management API reference

6 minute readReference

This section describes user management-related requests.

All database examples provided in this guide are specific to MySQL. If you use a different database, use syntax that is appropriate for your respective database.

addGroupMember

Adds a user name to the member list for a specific group.

Required arguments

Field Description

groupName

The unique name of the group.

userName

The unique name of the user.

Optional arguments

None

Syntax

cmtool addGroupMember <groupName> <userName>
▼

Example

cmtool addGroupMember DevGroupA ec123
▼

Adds user ’ec123’ to group DevGroupA.

changeOwnUser

Modifies the settings for the currently logged-in user.

Required arguments

Field Description

userName

The unique name of the user.

Optional arguments

Field Description

fullUserName

The real world name of the user.

email

The associated user email address.

password

The password for a particular user.

passwordFile

The path to a password file. If `--password ` is also specified, `--passwordFile ` overrides its value in the command line.

Syntax

cmtool changeOwnUser <userName> [optionals...]
▼

Example

cmtool changeOwnUser ec123 --fullUserName "Mary Smith"
▼

createGroup

Creates a new local group.

Required arguments

Field Description

groupName

The unique name of the group to create.

Optional arguments

None

Syntax

cmtool createGroup <groupName>
▼

Example

cmtool createGroup DevGroupA
▼

createUser

Creates a new local user.

Required arguments

Field Description

userName

The unique name of the user.

password

The password for a particular user.

Optional arguments

Field Description

fullUserName

The real world name of the user.

email

The associated user email address.

passwordFile

The path to a password file. If `--password ` is also specified, `--passwordFile ` overrides its value in the command line.

Syntax

cmtool createUser <userName> <password> [optionals...]
▼

Example

cmtool createUser ec123 psword --fullUserName "Bob Smith" --email "ec123@ourhost.com"
▼

Creates a new user named “ec123” whose real-world name is Bob Smith; with “psword” as his password.

If you do not wish to expose passwords on the command line, you can omit the password from the example above. Press the Enter key after typing the command string (without the password) and you will be prompted for the password.

deleteGroup

Deletes a local group.

Required arguments

Field Description

groupName

The unique name of the group.

Optional arguments

None

Syntax

cmtool deleteGroup <groupName>
▼

Example

cmtool deleteGroup DevGroupA
▼

Removes the ’DevGroupA’ group from the Cluster Manager.

deleteUser

Deletes a local user.

Required arguments

Field Description

userName

The unique name of the user.

Optional arguments

None

Syntax

cmtool deleteUser <userName>
▼

Example

cmtool deleteUser ec123
▼

getAccessEntries

Retrieves permissions for all users and groups that were granted server access.

Required arguments

None

Optional arguments

None

Result tags

Field Description

entityName

A user or group name in an access entry.

permissions

The list of permission flags for a particular entity.

Example

cmtool getAccessEntries
▼

getGroupMembers

Retrieves a list of users in a specific group.

Required arguments

Field Description

groupName

The unique name of the group.

Optional arguments

None

Result tags

Field Description

userName

The unique name of the user.

Example

cmtool getGroupMembers
▼

Retrieves a list of user name elements.

getGroups

Finds all groups known to the server. If “local” is true, returns local groups only.

Required arguments

Field Description

userName

The unique name of the user.

Optional arguments

Field Description

local

Can be true or false. If true, returns local users only.

Result tags

Field Description

groupName

The unique name of the group.

mutable

True if the associated user or group record is modifiable.

providerName

The human-readable name configured for the directory provider of a specific user or group.

Syntax

cmtool getGroups [optionals...]
▼

Example

cmtool getGroups
▼

Returns a list of groupInfo elements.

getEffectivePermissions

Retrieves the permissions for the currently logged-in user.

Required arguments

None

Optional arguments

None

Result tags

Field Description

permissions

The list of permission flags for a particular entity.

Possible Results

`AgentsDelete ` `AgentsRead ` `AgentsWrite ` `BuildsDelete ` `BuildsRead ` `BuildsWrite ` `ClassesDelete ` `ClassesRead ` `ClassesWrite ` `EMakeImpersonate ` `EMakeInvoke ` `MaintenanceDelete ` `MaintenanceRead `

MaintenanceWrite MessageLogDelete ` `MessageLogRead ` `MessageLogWrite ` `ReportsDelete ` `ReportsRead ` `ReportsWrite ResourcesDelete ` `ResourcesRead ` `ResourcesWrite `ServerAccess ` `UserModify `

Example

cmtool getEffectivePermissions
▼

Retrieves the permissions for the currently logged-in user.

getPermissions

Retrieves permissions for a particular user or group.

Required arguments

Field Description

principalType

Can be user or group.

entityName

A user or group name in an access entry.

Optional arguments

None

Result tags

Field Description

permissions

The list of permission flags for a particular entity.

Possible results

`AgentsDelete ` `AgentsRead ` `AgentsWrite ` `BuildsDelete ` `BuildsRead ` `BuildsWrite ` `ClassesDelete ` `ClassesRead ` `ClassesWrite ` `EMakeImpersonate ` `EMakeInvoke ` `MaintenanceDelete ` `MaintenanceRead `

MaintenanceWrite MessageLogDelete MessageLogRead ` `MessageLogWrite ` `ReportsDelete ` `ReportsRead ` `ReportsWrite ResourcesDelete ` `ResourcesRead ` `ResourcesWrite `ServerAccess ` `UserModify `

Syntax

cmtool getPermissions <principalType> <entityName>
▼

Example

cmtool getPermissions group DevGroupA
▼

Retrieves permissions for group DevGroupA.

getUser

Finds a specific user known to the server.

Required arguments

Field Description

userName

The unique name of the user.

Optional arguments

None

Result tags

Field Description

email

The associated user email address.

fullUserName

The real world name of the user.

groupName

The unique name of the group.

mutable

True if the associated user or group record is modifiable.

providerName

The human-readable name configured for the directory provider of a specific user or group.

userName

The unique name of the user.

Syntax

cmtool getUser <userName> [optionals...]
▼

Example

cmtool getUser ec123
▼

Retrieves the attributes for user ec123.

getUsers

Finds all users known to the server. If “local” is true, returns local users only.

Required arguments

None

Optional arguments

Field Description

pattern

A wildcard pattern for a user name where “*” matches any character or SQL “like” string. If LDAP is set up for getting users, the * is the preferred wildcard, as % is not understood by LDAP (this limits the result set to records in the local database).

local

Can be true or false. If true, returns local users only.

Result tags

See the getUser command for descriptions.

email
fullUserNamemutable
providerName
userName
▼

Syntax

cmtool getUsers [optionals...]
▼

Example

cmtool getUsers --pattern ec*
▼

Retrieves information on all user IDs that begin with ’ec’.

getUserSettings

Retrieves settings for the currently logged-in user.

Required arguments

None

Optional arguments

None

Example

cmtool getUserSettings
▼

login

Logs in to the client with the appropriate credentials and creates a session file in the users home directory, which allows subsequent calls to cmtool to connect to the Cluster Manager.

Required arguments

Field Description

userName

The unique name of the user.

password

The password for a particular user.

Optional arguments

Field Description

passwordFile

The path to a password file. If `--password ` is also specified, `--passwordFile ` overrides its value in the command line.

Result tags

Field Description

sessionId

This is a session "cookie."

Syntax

cmtool login <userName> <password> [optionals...]
▼

Example

cmtool login ec123 bobs
▼

Logs in a user named “ec123” whose password is “bobs”.

If you do not wish to expose passwords on the command line, you can omit the password from the example above. Press the Enter key after typing the command string (without the password) and you will be prompted for the password.

logout

Logs out of the client session.

Required arguments

None

Optional arguments

None

modifyGroup

Modifies a local group.

Required arguments

Field Description

groupName

The unique name of the group.

Optional arguments

Field Description

newName

The new group name.

Syntax

cmtool modifyGroup <groupName> [optionals...]
▼

Example

cmtool modifyGroup DevGroupA --newName GroupDevA
▼

modifyUser

Modifies a local user.

Required arguments

Field Description

userName

The unique name of the user.

Optional arguments

Field Description

fullUserName

The real world name of the user.

email

The associated user email address.

password

The password for a particular user.

passwordFile

The path to a password file. If `--password ` is also specified, `--passwordFile ` overrides its value in the command line.

Syntax

cmtool modifyUser <userName> [optionals...]
▼

Example

cmtool modifyUser ec123 --fullUserName "Mary Smith"
▼

removeGroupMember

Deletes a user name from a specific group member list.

Required arguments

Field Description

groupName

The unique name of the group.

userName

The unique name of the user.

Optional arguments

None

Syntax

cmtool removeGroupMember <groupName> <userName>
▼

Example

cmtool removeGroupMember DevGroupA ec123
▼

setBuildEndNotification

Enables/disables notification when builds of this class end for the currently logged-in user.

Required arguments

Field Description

buildClassId

A unique number assigned by the Cluster Manager for each build class. Use getBuildClasses to retrieve a list of build class IDs.

enabled

Set this to true to enable notification and to false to disable it.

Optional arguments

None

Syntax

cmtool setBuildEndNotification <buildClassId> <enabled>
▼

Example

cmtool setBuildEndNotification 1 true
▼

Enables build ’end notification’ for build class 1.

setPermissions

Creates or modifies permissions for a user or group. The permissions are a space-separated list of permission names.

Required arguments

Field Description

principalType

Can be user or group.

entityName

A user or group name in an access entry.

permissions

The list of permission flags for a particular entity. See the available permissions flags below.

Possible results

AgentsDelete AgentsRead AgentsWrite BuildsDelete BuildsRead BuildsWrite ClassesDelete ClassesRead ClassesWrite EMakeImpersonate EMakeInvoke MaintenanceDelete MaintenanceRead

MaintenanceWrite MessageLogDelete MessageLogRead MessageLogWrite ReportsDelete ReportsRead ReportsWrite ResourcesDelete ResourcesRead ResourcesWrite ServerAccess `UserModify `

Optional arguments

None

Available Permission Flags

Syntax

cmtool setPermissions <principalType> <entityName> <permissions>
▼

Example

cmtool setPermissions user ec123 "BuildsRead AgentsRead"
▼

Restricts user ec123 to read-only privileges for builds and agents.

setUserSettings

Updates settings for the currently logged-in user.

Required arguments

Field Description

watchMessages

Indicates whether you want to receive notifications when messages of the specified notification level arrive. Can be Y, N, y, n, yes, no, Yes, or No.

Optional arguments

Field Description

notificationLevel

Can be Info, Warning, or Error.

Syntax

cmtool setUserSettings <watchMessages> [optionals...]
▼

Example

cmtool setUserSettings yes --notificationLevel Info
▼

Sets the current user to receive notifications for ’Info’ level messages.

Reporting API