Using the Perl API
IntroductionAccess tokensACL managementApplication dependencyApplicationsApplication tier Artifact managementCatalogsChange historyCI build detailCI configurationCI jobsComponentsCredential managementCustom filtersDatabase configurationData retentionCloudBees AnalyticsDirectory provider managementDynamic environmentsEmail configuration managementEmail notifier managementEnvironmentEnvironment tierGateway and zone managementInstalling or upgrading remote agentsJob managementMicroservicesObject tagsParameter managementPersonasPipelines and releasesPlugin managementPlugin configuration managementProcedure managementProcessProcess dependencyProcess stepProject managementProperty managementResource managementRolling deploySchedule managementService accounts for webhooksServer managementSingle sign on for SAMLSnapshotsTier mapTrigger managementUser and group managementUser profile email managementWait dependenciesWorkflow definition managementWorkflow managementWork itemsWorkspace managementMiscellaneous management
Perl API response and element glossary
IntroductionExamplesTroubleshooting
IntroductionaccesstokenaclaclentryactualparameteractualparametersapplicationapplicationdependencyapplicationtierarchiveconnectorartifactartifactversioncatalogcatalogitemcatalogitemruncibuildcibuilddetailciconfigurationcieventclustercomponentcredentialcredentialproviderdashboarddashboardcolumndataretentionpolicydeployerapplicationdeployerconfigurationdeploymenthistoryitemdevopsinsightdatasourcedirectoryprovideremailconfigemailnotifierentitychangeenvironmentenvironmentinventoryitemenvironmenttemplateenvironmenttemplatetierenvironmenttemplatetiermapenvironmenttemplatetiermappingenvironmenttierenvtempltierresourcetemplmappingeventsubscriptionflowruntimeformaloutputparameterformalparametergategatewaygrouphookjobjobstepkerberoskeytablicensemicroservicemicroservicemappingnoteobjectopenidconnectconfigurationoutputparameterpersonapersonacategorypersonapagepipelinepluginplugincatalogpluginconfigurationprocedureprocedurestepprocessprocessdependencyprocessstepprojectpropertyreleasereportreportingfilterreportobjectassociationreportobjectattributereportobjecttyperepositoryreservationresourceresourcepoolresourcetemplateresourceusageretrievedartifactsrollingdeployphaserundiscoverysamlidentityprovidersamlserviceproviderschedulescmsyncsearchfilterserverserversettingserversettingcategoryserviceaccountsessionsnapshotstagestatestatedefinitiontagtasktiermaptiermappingtransitiontransitiondefinitiontriggertriggererrordetailuseruseremailutilityresourcewaitdependencywebhookresultwidgetwidgetfilteroverrideworkflowworkflowdefinitionworkitemworkspacezoneArgument models

User and Group Management

10 minute readReference

addUsersToGroup

Adds one or more specified users to a local group.

You must specify a groupName and one or more user names.

Arguments Descriptions

groupName

The name of the group that must be unique among local groups.

userName

Use ec-perl to enter one or more user names to add to the group.

userName

Use ectool to enter one user name to add to the group.

userNames

Use ectool to enter two or more user names to add to the group.

Positional arguments

ec-perl: groupName, userName

ectool: groupName, userName or groupName, userNames, depending on the number of user names.

Response

None or a status OK message.

ec-perl

syntax: $cmdr->addUsersToGroup(<groupName>, {userName⇒ [<userName1>, …​]});

Example

$cmdr->addUsersToGroup("Developers", {userName => ["John", "Jim", "Joey"]});
▼

ectool

syntax: ectool addUsersToGroup <groupName> --userNames <userName1> …​

Examples

This example uses the singular userName argument to add one user to the group:

ectool addUsersToGroup Developers --userName John
▼

This example uses the plural userNames argument to add more than one user to the group:

ectool addUsersToGroup Developers --userNames John Jim Joey
▼

createGroup

Creates a new local group of users or personas.

You must specify a groupName.

Arguments Descriptions

groupName

Name for the new group that you are creating.

Argument type: String

personas

(Optional) A list of one or more personas belonging to this group. Use personaName returned by getPersonas .

Argument type: String

userName

(Optional) The user name to add to the group.

  • If using ec-perl, enter one or more user names to add to the group.

  • If using ectool, enter one user name to add to the group.

Argument type: Collection (ec-perl) or String (ectool)

userNames

(Optional) If using ectool, enter two or more user names to add to the group.

Argument type: Collection

Positional arguments

groupName

Response

Returns a group object.

ec-perl

syntax: $cmdr->getGroup(<PersonaName>);

ec-perl

syntax: $cmdr->createGroup(<groupName>, {<optionals>});

Example

$cmdr->createGroup("Build Users", {userName => ["aallen", "Betty Barker", "cclark"]});
▼
$cmdr->createGroup("personaGroup", {personas => ["persona1", "persona2"]});
▼

ectool

syntax: ectool createGroup <groupName> --userNames <user1> [optionals]

Examples

This example uses the singular userName argument to add one user name to the group.

ectool createGroup "Build Users" --userName "Betty Barker"
▼

This example uses the plural userNames argument to add two or more user names to the group.

ectool createGroup "Build Users" --userNames "aallen" "Betty Barker" "cclark"
▼

This example creates a group of personas.

ectool createGroup "personaGroup" --personas "persona1" "persona2"
▼

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'] });`

You must specify a userName.

Arguments Descriptions

userName

This could be the user’s full name, but more commonly it is the shortened name, first initial and last name, or nickname used for email.

Argument type: String

email

(Optional) The email address of the user.

Argument type: String

fullUserName

(Optional) Full name of the user, not a nickname.

Argument type: String

groupNames

(Optional) List of groups of which this user is a member.

<group1 group2> Any group name containing spaces must be enclosed in double-quotes.

Argument type: Collection

password

(Optional) The password of the user.

Argument type: String

personas

(Optional) A list of one or more personas belonging to this user. Use personaName returned by getPersonas .

Argument type: String

Positional arguments

userName

Response

Returns a user object.

ec-perl

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

Example

$cmdr->createUser("aallen", {fullUserName => "Albert Allen"});
▼
$cmdr->createUser("Betty Barker");
▼
$cmdr->createUser("Betty Barker", {personas => "Release Manager"});
▼

ectool

syntax: ectool createUser <userName> [optionals]

Examples

ectool createUser "aallen" --fullUserName "Albert Allen"

ectool createUser "Betty Barker"

ectool createUser "Betty Barker" --personas "Release Manager"
▼

deleteGroup

Deletes a local group.

You must specify a groupName.

Arguments Descriptions

groupName

The name of the group that must be unique among local groups.

Argument type: String

Positional arguments

groupName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->deleteGroup(<groupName>);

Example

$cmdr->deleteGroup("Build Users");
▼

ectool

syntax: ectool deleteGroup <groupName>

Example

ectool deleteGroup "Build Users"
▼

deleteUser

Deletes a local or registered user.

You must specify the userName.

Arguments Descriptions

userName

The name of the user.

Argument type: String

Positional arguments

userName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->deleteUser(<userName>);

Example

$cmdr->deleteUser("Betty Barker");
▼

ectool

syntax: ectool deleteUser <userName>

Example

ectool deleteUser "Betty Barker"
▼

getGroup

Retrieves a group by its name.

You must specify the groupName.

Arguments Descriptions

groupName

The name of the group that must be unique among local groups.

Argument type: String

providerName

(Optional) The name of the provider from which to retrieve the group.Using this option allows you to search only the specified (LDAP or Active Directory) provider for group information.

Argument type: String

traverseHierarchy

(Optional) < Boolean flag— 0|1|true|false >

If this is set to true or 1, nested groups are included in the results when the group is an LDAP group and recursive traversal of group hierarchy is enabled for the directory provider.

Argument type: Boolean

Positional arguments

groupName

Response

One group element.

ec-perl

syntax: $cmdr->getGroup(<groupName>, {<optionals>});

Example

$cmdr->getGroup("QA group", {providerName => "LDAP", traverseHierarchy => true});
▼

ectool

syntax: ectool getGroup <groupName> [optionals]

Example

ectool getGroup "QA group" --providerName "LDAP" --traverseHierarchy true
▼

getGroups

Retrieves all groups.

Arguments Descriptions

filter

(Optional) A string used to filter the returned groups by their names.

Argument type: String

includeAll

(Optional) < Boolean flag— 0|1|true|false >

When enabled (the value is 1 or true ), this argument returns all matching groups, including LDAP or non-LDAP groups that may or may not be in the CloudBees CD/RO database already. A group is added to the CloudBees CD/RO database when a user (who is a member of that group) logs in to CloudBees CD/RO for the first time.

Argument type: Boolean

maximum

(Optional) The maximum number of groups to return.

Argument type: Integer

Positional arguments

None

Response

Zero or more group elements, each containing summary information only.

ec-perl

syntax: $cmdr->getGroups({<optionals>});

Example

$cmdr->getGroups({filter => " dev*", maximum => 3,});
▼

ectool

syntax: ectool getGroups [optionals]

Example

ectool getGroups --filter dev* --maximum 3
▼

getUser

Retrieves information about a user.

You must specify the userName.

Arguments Descriptions

userName

The name of the user.

Argument type: String

providerName

(Optional) The name of the directory provider, which limits the search to the specified directory provider.

Argument type: String

registerLDAPUser

(Optional) < Boolean flag— 0|1|true|false >

If this is set to true or 1 (the default), the LDAP or Active Directory user is registered with the system.

Your CloudBees CD/RO license might restrict the number of users that you can register. To prevent user registration, specify 0 or false.

Argument type: Boolean

traverseHierarchy

(Optional) < Boolean flag— 0|1|true|false >

If this is set to true or 1, parent groups are retrieved when the user is an LDAP user and recursive traversal of group hierarchy is enabled for the directory provider.

Argument type: Boolean

Positional arguments

userName

Response

One user element.

ec-perl

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

Example

$cmdr->getUser("Betty Barker", {traverseHierarchy => true});
▼

ectool

syntax: ectool getUser <userName> [optionals]

Example

ectool getUser "Betty Barker" --traverseHierarchy true
▼

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 Descriptions

filter

(Optional) < filter pattern > Enter a filter pattern to match user names. The filter is not case sensitive and can include the "*" wildcard character.

Argument type: String

includeAll

(Optional) < Boolean flag— 0|1|true|false >

When this argument is 1 or true, this argument returns all matching groups, including LDAP or non-LDAP groups that may or may not be in the CloudBees CD/RO database. A group is added to the CloudBees CD/RO database when a user who is a member of that group logs in to CloudBees CD/RO for the first time.

Argument type: Boolean

maximum

(Optional) < number of users > Specify a larger number of user records to retrieve. The default limit is 100 user records.

Argument type: Integer

searchFields

(Optional) Filter search fields that include the user’s full name and email address.

Argument type: Collection

sortKey

(Optional) Sorts the list by the time of the users’ last login or user name. Possible values are lastLoginTime|userName.

Argument type: UserSortKey

sortOrder

(Optional) Sorts the list in ascending or descending order. Possible values are ascending|descending.

Positional arguments

None

Response

Zero or more user elements with summary information only.

ec-perl

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

Examples

$cmdr->getUsers();

$cmdr->getUsers({filter => '*Betty*', maximum => 25});
▼

ectool

syntax: ectool getUsers [optionals]

Examples

ectool getUsers

ectool getUsers --filter '*Betty*' --maximum 25
▼

login

Logs into 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.

You must specify the userName and password.

Arguments Descriptions

password

The password for the user who is logging in.

Argument type: String

userName

The name of a user who has login privileges.

Argument type: String

Positional arguments

userName, password

Response

One session element containing the session ID.

ec-perl

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

Example

$cmdr->login("Ellen Ernst", "ee123");
▼

ectool

syntax: ectool login <userName> <password>

ectool will prompt for the password if not supplied.

Example

ectool --server EAVMXP login "Ellen Ernst" "ee123"
▼

logout

Logs out of the client session.

Arguments Descriptions

None

–

Positional arguments

None

Response

None or a status OK message.

ec-perl

Example

$cmdr->logout();
▼

ectool

Example

ectool logout
▼

modifyGroup

Modifies an existing group.

You must specify groupName.

Arguments Descriptions

groupName

Name of the group that must be unique among local groups.

Argument type: String

clearPersonas

(Optional) < Boolean flag —0|1|true|false >

If the value is true or 1, clear all persona associations from this group.

Argument type: Boolean

migrateSettings

(Optional) < targetGroupName > Use this argument to specify the new name to which the settings need to be moved.

Argument type: String

newName

(Optional) Enter any name of your choice to rename the group.

Argument type: String

personas

(Optional) A list of one or more persona names. Append these personas to this group. Use personaName returned by getPersonas .

Argument type: String

removeAllUsers

(Optional) < Boolean flag —0|1|true|false >

If the value is true or 1, the system removes all the users from this group.

Argument type: Boolean

userName

(Optional) If using ec-perl, enter one or more user names to add to the group.

user1 [user2…​] Provide a complete list of names for the group. These names will replace existing names in the group. Any name with spaces must be enclosed in double-quotes.

Argument type: Collection

userName

(Optional) If using ectool, enter one user name to add to the group.

user1 Provide one user name for the group such as an alias. This name will replace existing names in the group. Any name with spaces must be enclosed in double-quotes.

Argument type: String

userNames

(Optional) If using ectool, enter two or more user names to add to the group.

user1 [user2…​] Provide a complete list of names for the group. These names will replace existing names in the group. Any name with spaces must be enclosed in double-quotes.

Argument type: Collection

Positional arguments

groupName

Response

Returns an updated group object.

ec-perl

syntax: $cmdr->modifyGroup(<groupName>, {<optionals>});

Examples

$cmdr->modifyGroup("Build Users", {userName => "dduncan"});
$cmdr->modifyGroup("Build Users", {userName => ["dduncan", "jack"]});
▼
$cmdr->modifyGroup("Build Users", {personas => ["persona1", "persona2"]});
▼

ectool

syntax: ectool modifyGroup <groupName> [<optionals>]

Examples

This example has the singular userName argument to add one user name to the group.

ectool modifyGroup "Build Users" --userName dduncan
▼

This example has the plural userNames argument to add two or more user names to the group.

ectool modifyGroup "Build Users" --userNames dduncan jack tthomas
▼

This example adds personas to the existing group

ectool modifyGroup "Build Users" --personas persona1 persona2
▼

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 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

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

  • groupNames

  • removeAllGroups

===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. For example:

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

You must specify a userName.

Arguments Descriptions

userName

The name used by the user to log in or receive email. For example, "jsmith".

Argument type: String

clearPersonas

(Optional) < Boolean flag —0|1|true|false >

If the value is true or 1, clear all persona associations from this user.

Argument type: Boolean

email

(Optional) (local users only) The user’s email address.

Argument type: String

fullUserName

(Optional) (local users only) The user’s full name. For example, "John Smith".

Argument type: String

groupNames

(Optional) group1 [ group2 …]

Assigns the user to one or more groups and removes the user from any groups not included in the list. For a non-local user, this argument adds the user to a local group (not a non-local group).

Argument type: Collection

migrateSettings

(Local users only) < targetUserName > The new name to which the settings need to be moved.

Argument type: String

newName

(Optional) (local users only) The new name of the user (for example, changing an existing user’s surname).

Argument type: String

Use this option only if the existing username is referenced anywhere.

password

(Optional) (local users only) Enter a new password for the user.

Argument type: String

personas

(Optional) A list of one or more persona names. Append these personas to this user. Use personaName returned by getPersonas .

Argument type: String

removeFromAllGroups

(Optional) < Boolean flag — 0|1|true|false > If set to 1 or true, this user will be removed from all groups. For a non-local user, this argument removes the user from all local groups (not non-local groups).

Argument type: String

sessionPassword

(Optional) If changing the user’s password, you must also enter the password you logged in with (the password you used in the login command).

Argument type: String

Positional arguments

userName

Response

Returns a user object.

ec-perl

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

Example

$cmdr->modifyUser("Betty Barker", {email => "bbarker@abc.com"});
▼

ectool

syntax: ectool modifyUser <userName> [optionals]

Example

ectool modifyUser "Betty Barker" --email "bbarker@abc.com"
▼

removeUsersFromGroup

Removes one or more users from an existing local group.

You must specify a groupName and one or more user names.

Arguments Descriptions

groupName

The name of the group from which to remove users.

Argument type: String

userNames

The list of users to remove from the group.

Argument type: Collection

Positional arguments

groupName, userNames

Response

Removes one or more users from a local group.

ec-perl

syntax: $cmdr->removeUsersFromGroup(<groupName>, {<optionals>});

Example

$cmdr->removeUsersFromGroup("Developers", {userName => ["John", "Jim", "Joey"]});
▼

ectool

syntax: ectool removeUsersFromGroup <groupName> <userNames> [optionals]

Example

ectool removeUsersFromGroup Developers --userNames John Jim Joey
▼
Trigger management
User profile email management