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

Credential Management

8 minute readReference

attachCredential

Attaches a credential to an object, such as a step or a schedule. Attaching a credential allows the credential to be passed as an actual argument by a schedule or subprocedure step, or to be used in a getFullCredential call by a command step.

You must specify projectName, credentialName, and locator arguments to identify an object.

Arguments Descriptions

projectName

The name of the project that must be must be unique among all projects.

Argument type: String

credentialName

Name of the credential in one of these forms:

  • Relative (for example, "cred1" )—The credential is assumed to be in the project that contains the request target object.

  • Absolute (for example, "/projects/BuildProject/credentials/cred1" )—The credential can be from any specified project, regardless of the target object’s project.

Argument type: String

Locator arguments:

applicationName

The name of the application process to which the credential is attached.

Argument type: String

applicationProjectName

The name of the project containing the application. If not specified, it defaults to the release project name.

Argument type: String

componentName

The name of the component to which the credential is attached when attaching a credential to a component, component process, or component process step.

Argument type: String

pipelineName

The name of the pipeline when attaching a credential to a stage task.

procedureName

The name of a procedure when attaching a credential to a procedure or procedure step.

Argument type: String

processName

(Optional) The name of a process when attaching a credential to a process or process step.

Argument type: String

processStepName

The name of a process step when attaching a credential to a process step.

Argument type: String

releaseName

The name of a release when attaching a credential to a release.

Argument type: String

scheduleName

The name of the schedule for running a procedure or process in the "named" project when attaching a credential to the schedule.

Argument type: String

serviceName

(Optional) The name of the service, if attaching a credential to a service process or service process step.

Argument type: String

serviceProjectName

(Optional) The name of the project containing specified service. If not specified, it is defaulted to the release project name.

Argument type: String

stageName

The name of the stage when attaching a credential to a task.

Argument type: String

stateDefinitionName

The name of the workflow state definition when attaching a credential to a state definition.

Argument type: String

stepName

A step name in a procedure or process in the "named" project when attaching a credential to a procedure step.

Argument type: String

taskName

The name of the task when attaching a credential to the task.

Argument type: String

workflowDefinitionName

The name of the workflow when attaching a credential to a state definition.

Argument type: String

Positional arguments

projectName, credentialName, and locator arguments to identify an object.

Response

None or a status OK message.

ec-perl

syntax: $cmdr->attachCredential(<projectName>, <credentialName>, {<optionals>});

Example

$cmdr->attachCredential("Default", "QA User", {procedureName =>
   "Run Build", stepName=>"Get Resources"});
▼

ectool

syntax: ectool attachCredential <projectName> <credentialName> [optionals]

Example

ectool attachCredential "Default" "QA User" --procedureName "Run Build" --stepName "Get Resources"
▼

createCredential

Creates a new credential for a project.

You must specify a projectName, credentialName, username, and password.

Arguments Descriptions

projectName

The name of the project where the credential will be stored. The name must be unique within all projects.

Argument type: String

credentialName

The name of the credential.

Argument type: String

userName

The user name of the credential.

Argument type: String

password

The password of the credential.

Argument type: String

description

(Optional) A plain text or HTML description for this object. If using HTML, you must surround your text with ` <html> …​ </html>` tags. The only HTML tags allowed in the text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol> <p> <pre> <span> <style> <table> <tc> <td> <th> <tr> <ul>

Argument type: String

passwordRecoveryAllowed

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

If 1 or true, the password can be recovered by running getFullCredential from a job step.

Argument type: Boolean

credentialProviderName

(Optional) The name of the credential provider where the credential secret is stored. Use getCredentialProviders to retrieve a list of credential providers.

Argument type: String

credentialProviderProjectName

(Optional) Name of the credential provider project, if different from the credential project.

Argument type: String

test

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

Applicable if credentialProviderName is specified. If 1 or true, test that the credential exists in the secret management system prior to saving.

Argument type: Boolean

secretPath

The full path to the object with secret. Applicable for CyberArk and Hashicorp external credential providers.

Positional arguments

projectName, credentialName, userName, password

Response

None or a status OK message.

ec-perl

syntax: $cmdr\->createCredential(<projectName>, <credentialName>, <userName>, <password>, {<optionals>});
▼

Example

$cmdr->createCredential("Default", "QA Deploy", "QA", "abc123", {description => "Use during preproduction"});
▼

ectool

syntax: ectool createCredential <projectName> <credentialName> <userName> <password> [optionals]
▼

Example

ectool createCredential "Default" "QA Deploy" "QA" "abc123" --description "Use for preproduction"
▼

deleteCredential

Deletes a credential.

You must specify a projectName and a credentialName.

Arguments Descriptions

projectName

The name of the project that contains this credential. The project name must be unique among all projects.

Argument type: String

credentialName

Name of the credential in one of these forms:

  • Relative (for example, "cred1" )—The credential is assumed to be in the project that contains the request target object.

  • Absolute (for example, "/projects/BuildProject/credentials/cred1" )—The credential can be from any specified project, regardless of the target object’s project.

Argument type: String

Positional arguments

projectName, credentialName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->deleteCredential(<projectName>, <credentialName>);

Example

$cmdr->deleteCredential('Default', 'Build User');
▼

ectool

syntax: ectool deleteCredential <projectName> <credentialName>

Example

ectool deleteCredential "Default" "Build User"
▼

detachCredential

Detaches a credential from an object.

You must specify projectName and credentialName. Also, depending on where the credential is attached, you must specify a step (using procedureName and stepName ), or define a schedule (using scheduleName ).

Arguments Descriptions

projectName

The name of the project that must be unique among all projects.

Argument type: String

credentialName

Name of the credential in one of these forms:

  • Relative (for example, "cred1" )—The credential is assumed to be in the project that contains the request target object.

  • Absolute (for example, "/projects/BuildProject/credentials/cred1" )—The credential can be from any specified project, regardless of the target object’s project.

Argument type: String

applicationName

(Optional) The name of the application process with the credential that you want to detach.

Argument type: String

applicationProjectName

(Optional) The name of the project containing specified application. If this is not specified, the default is the release project name.

Argument type: String

componentName

(Optional) The name of the component or component process with the credential that you want to detach.

pipelineName

(Optional) The name of the pipeline when a credential attached to a stage task.

Argument type: String

procedureName

(Optional) The name of the procedure with the credential that you want to detach.

Argument type: String

processName

(Optional) The name of the process with the credential that you want to detach.

Argument type: String

processStepName

(Optional) The name of the process step with the credential that you want to detach.

Argument type: String

releaseName

(Optional) The name of the release defined by a pipeline to which a credential attached.

Argument type: String

scheduleName

(Optional) The name of the schedule where this credential is attached.

Argument type: String

serviceName

(Optional) The name of the service, if attaching a credential to a service process or a service process step.

Argument type: String

serviceProjectName

(Optional) The name of the project containing the specified service. If not specified, it defaults to the release project name.

Argument type: String

stageName

(Optional) The name of the stage when a credential is attached to a stage task.

Argument type: String

stateDefinitionName

(Optional) The name of the workflow state definition when a credential is attached to a state definition.

Argument type: String

stepName

(Optional) A step name in a procedure or process in the "named" project.

Argument type: String

taskName

(Optional) The name of the task when a credential is attached to a task.

Argument type: String

workflowDefinitionName

(Optional) The name of the workflow definition when a credential is attached to a state definition.

Argument type: String

Positional arguments

projectName, credentialName

Response

None, or a status OK message on success, or:

NoSuchCredential if the specified credential does not exist.

NoSuchSchedule if the specified schedule does not exist.

ec-perl

syntax: $cmdr->detachCredential(<projectName>, <credentialName>, {<optionals>});

Examples

$cmdr->detachCredential("Default", "Preflight User",
                         {procedureName => "Run Build",
                               stepName => "Get Sources"});

$cmdr->detachCredential("Default", "Preflight User",
                          {scheduleName => "Build Schedule"});
▼

ectool

syntax: ectool detachCredential <projectName> <credentialName> [optionals]

Examples

ectool detachCredential "Default" "Preflight User"
  --procedureName "Run Build" --stepName "Get Sources"

ectool detachCredential "Test Proj" "Preflight User"
  --scheduleName "Build Schedule"
▼

getCredential

Finds a credential by name.

You must specify projectName and credentialName.

Arguments Descriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

Argument type: String

credentialName

Name of the credential in one of these forms:

  • Relative (for example, "cred1" )—The credential is assumed to be in the project that contains the request target object.

  • Absolute (for example, "/projects/BuildProject/credentials/cred1" )—The credential can be from any specified project, regardless of the target object’s project.

Argument type: String

Positional arguments

projectName, credentialName

Response

A credential object.

ec-perl

syntax: $cmdr->getCredential(<projectName>, <credentialName>);

Example

$cmdr->getCredential("QA Runs", "Build User");
▼

ectool

syntax: ectool getCredential <projectName> <credentialName>

Example

ectool getCredential "QA Runs" "Build User"
▼

getCredentials

Retrieves all credentials in a project.

You must specify a projectName.

Arguments Descriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

Argument type: String

usableOnly

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

If set to 1 or true, only those credentials that the currently logged-in user has execute privileges for will be returned.

Argument type: Boolean

Positional arguments

projectName

Response

Zero or more credential elements.

ec-perl

syntax: $cmdr->getCredentials(<projectName>, {<optionals>});

Example

$cmdr->getCredentials("Default", {usableOnly => 1});
▼

ectool

syntax: ectool getCredentials <projectName> [optionals]

Example

ectool getCredentials "Default" --usableOnly 1
▼

getFullCredential

Retrieves a credential by name, including a user name or password, from within a running step. You must specify the credentialName.

Arguments Descriptions

credentialName

Name of the credential in one of these forms:

  • Relative (for example, "cred1" )—The credential is assumed to be in the project that contains the request target object.

  • Absolute (for example, "/projects/BuildProject/credentials/cred1" )—The credential can be from any specified project, regardless of the target object’s project.

Argument type: String

value

(Optional) <userName|password>

Retrieves the user name or password of the credential. The password might also be a certificate or other chunk of data.

Argument type: String

Positional arguments

credentialName

Response

If value is not specified, an XPath object is returned. If value is specified, only the user name or password is returned.

ec-perl

syntax: $cmdr->getFullCredential(<credentialName>, {<optionals>});

Example

# Returns an xPath object containing the password.
my $xpath = $cmdr\->getFullCredential("myCred");

# Parse password from response.
my $password = $xpath->find("//password");
▼

ectool

syntax: ectool getFullCredential <credentialName> ` [optionals]`

Example 1

ectool getFullCredential "/projects/Default/credentials/testCredential"
▼

Following is an example response:

<response requestId="1" nodeId="10.200.1.123">
  <credential>
    <credentialId>a7dad279-ae72-11e7-83c1-0050569dd9a6</credentialId>
    <credentialName>testCredential</credentialName>
    <createTime>2017-10-11T10:55:12.371Z</createTime>
    <description />
    <lastModifiedBy>admin</lastModifiedBy>
    <modifyTime>2017-10-11T10:55:12.371Z</modifyTime>
    <owner>admin</owner>
    ~password~
    <projectName>Default</projectName>
    <propertySheetId>a7dad27b-ae72-11e7-83c1-0050569dd9a6</propertySheetId>
    <tracked>1</tracked>
    <userName>credentialUserName</userName>
  </credential>
</response>
▼

Example 2

ectool getFullCredential "/projects/Default/credentials/testCredential" --value userName
▼

Following is an example response:

ktran
▼

Example 3

ectool getFullCredential "/projects/Default/credentials/testCredential" --value password
▼

Following is an example response:

3}CJ@*$D$%4MgJ=D
▼

modifyCredential

Modifies an existing credential.

You must specify projectName and credentialName.

Arguments Descriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

Argument type: String

credentialName

Name of the credential in one of these forms:

  • Relative (for example, "cred1" )—The credential is assumed to be in the project that contains the request target object.

  • Absolute (for example, "/projects/BuildProject/credentials/cred1" )—The credential can be from any specified project, regardless of the target object’s project.

Argument type: String

description

(Optional) A plain text or HTML description for this object. If using HTML, you must surround your text with <html> …​ </html> tags. The only HTML tags allowed in the text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol> <p> <pre> <span> <style> <table> <tc> <td> <th> <tr> <ul>

Argument type: String

newName

(Optional) New name of the credential.

Argument type: String

password

(Optional) The password for the credential. It can also be a certificate or other chunk of data.

Argument type: String

passwordRecoveryAllowed

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

If this is set to 1 or true, the password can be recovered by running getFullCredential from a job step.

Argument type: Boolean

userName

The name of the user for this credential.

Argument type: String

credentialProviderName

(Optional) The name of the credential provider where the credential secret is stored. Use getCredentialProviders to retrieve a list of credential providers.

Argument type: String

credentialProviderProjectName

(Optional) Name of the credential provider project, if different from the credential project. Use getCredentialProvider to retrieve the projectName for a given credential provider.

Argument type: String

test

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

Applicable if credentialProviderName is specified. If 1 or true, test that the credential exists in the secret management system prior to saving.

Argument type: Boolean

secretPath

The full path to the object with secret. Applicable for CyberArk and Hashicorp external credential providers.

Positional arguments

projectName, credentialName

Response

Returns an updated credential element.

ec-perl

syntax: $cmdr->modifyCredential(<projectName>, <credentialName>, {<optionals>});

Example

$cmdr->modifyCredential("Default", "Build User", {userName => "build"});
▼

ectool

syntax: ectool modifyCredential <projectName> <credentialName> [optionals]

Example

ectool modifyCredential "Default" "Build User" --userName "build"
▼
Components
Custom filters