User

4 minute readReference

createUser

Creates a new local user.

This API does not apply to non-local users.

User or Group Lists

The commands createUser and modifyUser can have an optional argument called groupNames. The commands createGroup and modifyGroup can have an optional argument named userNames. In each case, the optional argument is followed by a list of groups or names.

Using ectool, your command string would be:

ectool createGroup "New Group Name" --userNames "A Adams" "B Barker"

To make this call via the Perl API, create a list of names and then pass a reference to the list as an optional parameter.

The name of the optional parameter is singular, "userName" or "userGroup," not the plural form used by ectool.

Here is an example using the Perl API:

# Run the procedure - pass a reference to the list of names $xPath = $cmdr->createGroup("New Group Name", { "userName" ⇒ ['A Adams', 'B Burns'] });

Arguments

Argument Name Type Description

userName

String

(Required) The user name.

email

String

Email address of the user.

fullUserName

String

Full name of the user.

groupNames

Collection

List of groups that this user is in.

password

String

The users password.

personas

Collection

List of personas that this user has.

Positional arguments

userName

Usage

ec-perl

$cmdr->createUser(<userName>, {<optionals>});

ectool

ectool createUser userName, [optionals]

deleteUser

Deletes a local or registered user.

Arguments

Argument Name Type Description

userName

String

(Required) The user name.

Positional arguments

userName

Usage

ec-perl

$cmdr->deleteUser(<userName>);

ectool

ectool deleteUser userName

getUser

Retrieves information about a user.

Arguments

Argument Name Type Description

userName

String

(Required) The user name.

providerName

String

The name of the provider from which to get the user.

registerLDAPUser

Boolean

Set to 0 or false to show user without register LDAP user in the EF system.

traverseHierarchy

Boolean

Set to 0 or true to include parent groups in the result if this is an LDAP user and recursive traversal of group hierarchy is enabled for the directory provider.

Positional arguments

userName

Usage

ec-perl

$cmdr->getUser(<userName>, {<optionals>});

ectool

ectool getUser userName, [optionals]

getUsers

Retrieves information about all users. By default, this command returns users who have been added to the CloudBees CD/RO database, which means they have logged in previously.

When calling getUsers, the default limit is 100 user records. Use the maximum option to specify a larger number, but this may inhibit performance, or you could define a search pattern to filter your search and conduct multiple queries.

Arguments

Argument Name Type Description

filter

String

Apply a glob-style filter (for example, foo*) when looking for users or groups.

includeAll

Boolean

Whether to include all users or groups, or only users or groups that are known to the system.

maximum

Integer

The maximum number of users or groups to return.

searchFields

Collection

Filter search fields. Supported FulName or/and Email.

sortKey

UserSortKey

How to sort the results.

sortOrder

SortOrder

Specifies the order to sort the results.

Positional arguments

None.

Usage

ec-perl

$cmdr->getUsers({<optionals>});

ectool

ectool getUsers [optionals]

login

Signs in to the server and saves the session ID for subsequent ectool use. The user name provided determines the permissions for commands that can be run during the session.

Arguments

Argument Name Type Description

userName

String

(Required) User name under which you wish to login.

password

String

(Required) Secret value used to identify the account for a particular user.

Positional arguments

userName, password

Usage

ec-perl

$cmdr->login(<userName>, <password>);

ectool

ectool login userName, password

logout

Signs out of the client session.

Arguments

Argument Name Type Description

jwtToken

String

JWT token.

uiLogout

Boolean

If true, server will return URL for redirect to logout from CI.

Positional arguments

None.

Usage

ec-perl

$cmdr->logout({<optionals>});

ectool

ectool logout [optionals]

modifyUser

Modifies a non-local (LDAP) user that is registered with CloudBees CD/RO (with certain limitations described below) or a local user.

Using modifyUser for Non-Local (LDAP) Users

You can use the following modifyUser arguments for non-local users that are registered with CloudBees CD/RO:

  • groupNames

  • removeAllGroups

You cannot use modifyUser for non-local users that are not registered with CloudBees CD/RO. You cannot use the following modifyUser arguments for non-local users, regardless of whether they are registered with CloudBees CD/RO:

  • email

  • fullUserName

  • password

  • migrateSettings

  • newName

User or Group Lists

The createUser and modifyUser commands can use an optional groupNames argument. The createGroup and modifyGroup commands can have an optional userNames argument. In each case, the argument is followed by a list of groups or names. Using ectool, your command string would be:

ectool createGroup `New Group Name --userNames A Adams B Barker

To make this call via the Perl API, create a list of names and then pass a reference to the list as an optional parameter. The name of the optional parameter is singular, userName or userGroup, not the plural form used by ectool.

Arguments

Argument Name Type Description

userName

String

(Required) The user name.

clearPersonas

Boolean

Clear personas for user, if modifying.

email

String

Email address of the user.

fullUserName

String

Full name of the user.

groupNames

Collection

List of groups that this user is in.

migrateSettings

String

Migrate the user or group settings to this name.

newName

String

The new name for an existing object that is being renamed.

password

String

The users password.

personas

Collection

List of personas that this user has.

removeFromAllGroups

Boolean

True to remove this user from all groups.

sessionPassword

String

Session user’s password. Used to re-verify identity before changing user passwords in the system.

Positional arguments

userName

Usage

ec-perl

$cmdr->modifyUser(<userName>, {<optionals>});

ectool

ectool modifyUser userName, [optionals]