Using the Perl API
IntroductionACL 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 managementProcedure managementProcessProcess dependencyProcess stepProject managementProperty managementResource managementRolling deploySchedule managementServer managementSingle sign-onSnapshotsTier mapUser and group managementWait dependenciesWebhhook managementWorkflow definition managementWorkflow managementWork itemsWorkspace managementMiscellaneous management
Perl API response and element glossary
IntroductionExamplesTroubleshooting
IntroductionaccesstokenaclaclentryactualparameteractualparametersapplicationapplicationdependencyapplicationservicemappingapplicationtierarchiveconnectorartifactartifactversioncatalogcatalogitemcatalogitemruncibuildcibuilddetailciconfigurationcieventclustercomponentcontainercredentialcredentialproviderdashboarddashboardcolumndataretentionpolicydeployerapplicationdeployerconfigurationdeployerservicedeploymenthistoryitemdevopsinsightdatasourcedirectoryprovideremailconfigemailnotifierentitychangeenvironmentenvironmentinventoryitemenvironmentmapenvironmenttemplateenvironmenttemplatetierenvironmenttemplatetiermapenvironmenttemplatetiermappingenvironmenttierenvironmentvariableenvtempltierresourcetemplmappingeventsubscriptionflowruntimeformaloutputparameterformalparametergategatewaygrouphookjobjobstepkerberoskeytablicensemicroservicemicroservicemappingnoteobjectoutputparameterpersonapersonacategorypersonapagepipelinepluginpluginconfigurationportprocedureprocedurestepprocessprocessdependencyprocessstepprojectpropertyreleasereportreportingfilterreportobjectassociationreportobjectattributereportobjecttyperepositoryreservationresourceresourcepoolresourcetemplateresourceusageretrievedartifactsrollingdeployphaserundiscoverysamlidentityprovidersamlserviceproviderschedulesearchfilterserverserversettingserversettingcategoryserviceaccountserviceserviceclustermappingservicedependencyservicemapdetailsessionsnapshotstagestatestatedefinitiontagtasktiermaptiermappingtransitiontransitiondefinitiontriggertriggererrordetailuseruseremailutilityresourcewaitdependencywebhookresultwidgetwidgetfilteroverrideworkflowworkflowdefinitionworkitemworkspacezoneArgument models

CI job commands

4 minute readReference

These commands fetch native CI jobs and, for jobs so configured, its parameters.

getCIJob

Gets the specified CI job.

Arguments Descriptions

ciConfigurationName

The name of the CI configuration for the server that contains ciJobName.

Argument Type: String

ciJobName

The name of the CI job to retrieve.

folder

(Optional) Path to the folder on the CI server referenced by ciConfigurationName that contains the specified CI job. Must be in format folder1/folder2/folder3/…​.

If not specified, the root level for ciConfigurationName is used.

Positional arguments

ciConfigurationName

Response

Returns a ciJob object.

ec-perl

syntax: $cmdr->getCIJob (<ciConfigurationName>, <ciJobName>, {<optionals>});

Example

$cmdr->getCIJob
  (
    ciConfigurationName => "CI Build Demo", ciJobName => "build-with-params"
  );
▼

ectool

syntax: ectool getCIJob <ciConfigurationName> <ciJobName> [optionals]

Example

ectool getCIJob 'CI Build Demo' 'build-with-params'
▼

Back to top

getCIJobs

Gets CI jobs for the specified CI configuration.

Arguments Descriptions

ciConfigurationName

The name of the CI Configuration. Argument Type: String

folder

(Optional)Path to the folder on the CI server referenced by ciConfigurationName that contains the specified CI job. Must be in format folder1/folder2/folder3/…​.

If not specified, the root level for ciConfigurationName is used.

jobSearchType

(Optional) Specify job search type:

  • FOLDER to return all folders

  • JOB to return all other job types

  • ALL to return both jobs and folders

If not specified, JOB is used.

Argument Type: String

Positional arguments

ciConfigurationName

Response

Returns one or more ciJob objects.

ec-perl

syntax: $cmdr->getCIJobs (<ciConfigurationName>, {<optionals>});

Example

$cmdr->getCIJobs
  (
    ciConfigurationName => "CI Build Demo"
  );
▼

ectool

syntax: ectool getCIJobs <ciConfigurationName> [optionals]

Example

ectool getCIJobs 'CI Build Demo'
▼

Back to top

getCIJobParameters

Retrieve parameters for the given CloudBeesCI job. See This list for the types of parameters.

Arguments Description

ciConfigurationName

The name of the CI Configuration. Argument Type: String

ciJobName

The name of the CI Job as returned from the getCIJobs command. Argument Type: String

folder

(Optional)Path to the folder on the CI server referenced by ciConfigurationName that contains the specified CI job. Must be in format folder1/folder2/folder3/…​.

If not specified, the root level for ciConfigurationname is used.

Positional arguments

ciConfigurationName, ciJobName

Response

Returns the parameters for the specified ciJobName as a string.

Parameter types

Type Description

Boolean

Defines a simple boolean parameter, which you can use during a build, either as an environment variable, or through variable substitution in some other parts of the configuration. The string value is true or false.

Choice

Defines a simple string parameter, which can be selected from a list. You can use it during a build, either as an environment variable, or through variable substitution in some other parts of the configuration.

Credentials

Defines a credentials parameter, which you can use during a build. For security reasons, the credential is not directly exposed, but rather, the ID of the credential is exposed.

However, the selected credential is available through variable substitution in some other parts of the configuration. The string value is the ID of the credential. A supporting plugin can thus use the ID to retrieve the selected credential and expose it to the build in an appropriate way.

File

Accepts a file submission from a browser as a build parameter. The uploaded file is placed at the specified location in the workspace, which your build can then access and use.

This is useful for many situations, such as:

  • Letting people run tests on the artifacts they built.

  • Automating the upload/release/deployment process by allowing the user to place the file.

  • Processing data by uploading a dataset.

The name of the submitted file is available in the environment variable whose name is the same as file location. For example, if you set the file location to be abc.zip, then ${abc.zip} gives you the original file name passed from the browser, such as my.zip. The name does not include the directory name portion.

File upload is optional. If a user chooses not to upload anything, Jenkins simply skips this parameter and does not place anything. But, it also does not delete anything that’s already in the workspace.

From the CLI, the -p option to the build command should take an empty value to read from standard input. Only one file parameter can be defined this way.

Subversion tag list

Displays a field at build-time for the user to select a Subversion tag from which to create the working copy for this project. Once the two fields Name and Repository URL are set, you must

  • Ensure the job uses Subversion.

  • Set the Repository URL field of Subversion by concatenating the two fields of this parameter.

For instance, if Name is set to SVN_TAG and Repository URL is set to https://svn.jenkins-ci.org/tags, then Subversion’s Repository URL must be set to https://svn.jenkins-ci.org/tags/$SVN_TAG.

Notice that you can set the Repository URL field to a Subversion repository root rather than just pointing to a tags directory. That is, you can set it to https://svn.jenkins-ci.org rather than https://svn.jenkins-ci.org/tags. In that case, if this repository root contains the trunk, branches, and tags folders, then the dropdown allows the user to pick the trunk, or a branch, or a tag.

Multi-line string

Displays a text area.

Password

Passes a password to your build. The password entered here is made available to the build in plain text as an environment variable like a string parameter would be. The value is stored encrypted on the Jenkins master, similar to passwords in Jenkins configuration.

Run

Defines a run parameter, where users can pick a single run of a certain project. The absolute URL of this run is exposed as an environment variable, or through variable substitution in some other parts of the configuration. In the build this can be used to query Jenkins for further information.

String

Defines a simple text parameter, where users can enter a string value, which you can use during a build, either as an environment variable, or through variable substitution in some other parts of the configuration.

ec-perl

syntax: $cmdr->getCIJobParameters (<ciConfigurationName>, {<ciJobName});

Example

$cmdr->getCIJobParameters
  (
    getCIJobParameters => {"CI Build Demo","job-with-params"}
  );
▼

ectool

syntax: ectool getCIJobParameters <ciConfigurationName> [optionals]

Example

ectool getCIJobParameters 'CI Build Demo'
▼

Back to top

CI configuration
Components