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 managementGet application environment inventoryInstalling 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
IntroductionaccesstokenaclaclentryactualparameterapplicationapplicationdependencyapplicationtierarchiveconnectorartifactartifactversioncatalogcatalogitemcatalogitemruncibuildcibuilddetailciconfigurationcieventclustercomponentcredentialcredentialproviderdashboarddashboardcolumndataretentionpolicydeployerapplicationdeployerconfigurationdeploymenthistoryitemdevopsinsightdatasourcedirectoryprovideremailconfigemailnotifierentitychangeenvironmentenvironmentinventoryitemenvironmenttemplateenvironmenttemplatetierenvironmenttemplatetiermapenvironmenttemplatetiermappingenvironmenttierenvtempltierresourcetemplmappingeventsubscriptionflowruntimeformaloutputparameterformalparametergategatewaygrouphookjobjobstepkerberoskeytablicensemicroservicemicroservicemappingnoteobjectopenidconnectconfigurationoutputparameterpersonapersonacategorypersonapagepipelinepluginplugincatalogpluginconfigurationprocedureprocedurestepprocessprocessdependencyprocessstepprojectpropertyreleasereportreportingfilterreportobjectassociationreportobjectattributereportobjecttyperepositoryreservationresourceresourcepoolresourcetemplateresourceusageretrievedartifactsrollingdeployphaserundiscoverysamlidentityprovidersamlserviceproviderschedulescmsyncsearchfilterserverserversettingserversettingcategoryserviceaccountsessionsnapshotstagestatestatedefinitionstringresulttagtasktiermaptiermappingtransitiontransitiondefinitiontriggertriggererrordetailuseruseremailutilityresourcewaitdependencywebhookresultwidgetwidgetfilteroverrideworkflowworkflowdefinitionworkitemworkspacezoneArgument models

Catalog Commands

8 minute readReference

createCatalog

Creates a new catalog.

Arguments Descriptions

projectName

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

Argument Type: String

Argument type: String

catalogName

The name of the catalog.

Argument type: String

description

(Optional) Comment text describing this object; not interpreted at all by CloudBees CD/RO .

Argument type: String

iconUrl

(Optional) Set icon URL for a catalog.

Argument type: String

Positional arguments

projectName, catalogName

Response

Returns the new catalog.

ec-perl

syntax: $<object>->createCatalog(<projectName>, <catalogName>, {<optionals>});

Example

$cmdr->createCatalog("ENTBU Deploy", "ENTBU Q2 Catalog", {description => "Enterprise BU catalog for Q2 deployments"});
▼

ectool

syntax: ectool createCatalog <projectName> <catalogName> [optionals]

Example

ectool createCatalog "ENTBU Deploy" "ENTBU Q2 Catalog" --description "Enterprise BU catalog for Q2 deployments"
▼

createCatalogItem

Creates a new catalog item in a catalog.

Arguments Descriptions

projectName

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

Argument Type: String

Argument type: String

catalogName

The name of the catalog.

Argument type: String

catalogItemName

The name of the catalog item.

Argument type: String

afterItem

(Optional) If specified, the catalog item will be placed after the named catalog item.

Argument type: String

beforeItem

(Optional) If specified, the catalog item will be placed before the named catalog item.

Argument type: String

buttonLabel

(Optional) The name of the button label.

Argument type: String

description

(Optional) Comment text describing this object; not interpreted at all by CloudBees CD/RO . This argument supports HTML. For example:

<xml>
 <title>This is the short description that is shown in the Service Catalog UI when the catalog items are first rendered.</title>
 <htmlData>
 <![CDATA[<div>
  This is the stylized HTML-based catalog item details that is shown when the user clicks the "more" link.
  </div>]]>
 </htmlData>
</xml>
▼

dslParamForm

(Optional) The DSL Parameter form metadata.

Argument type: String

dslString

(Optional) The DSL string that is evaluated for the catalog item.

Argument type: String

endTargetJson

(Optional) A DSL string to specify the end target object of the this catalog item. It has the following form:

"endTarget": {
     "source": "<source>",
      "object": "<objectType>",
      "objectName ": "<objectName>",
      "objectProjectName ": "<objectProjectName>",
      "objectId" : "<objectId>"
}
▼

where:

  • <source> is one of:

  • parameter —use values supplied with objectName, objectProjectName, and objectId as fields in the formal parameter; set useFormalParameter to true.

  • form —use values supplied with objectName, objectProjectName, and objectId as fields in the form XML; set useFormalParameter to false.

  • property —use values supplied with objectName, objectProjectName, and objectId as properties.

  • name —use values supplied with objectName, objectProjectName, and objectId as literal strings.

  • <objectType> is the type of object.

  • <objectName> is the name of the object. Can be a literal string, property, or formal parameter field based on <source> type.

  • <objectProjectName> is the project. Can be a literal string, property, or formal parameter field based on <source> type.

  • <objectId> is the object id. Can be a literal string, property, or formal parameter field based on <source> type.

Argument type: String

firstItem

(Optional) True to make a catalog item the first in a catalog.

Argument type: Boolean

iconUrl

(Optional) The URL for the icon to be used in the UI. Place a custom icon for the catalog item in the <install_dir>/apache/htdocs/flow/public/app/assets/img folder and reference it using this attribute as public/app/assets/img/<image_name>.<extension>. For example, public/app/assets/img/mycatalogitem.jpg. You can use any browser-supported format such as .jpg, .png, or gif.

Argument type: String

subpluginKey

(Optional) The name of the procedure’s pluginKey.

Argument type: String

subprocedure

(Optional) The name of the subprocedure.

Argument type: String

subproject

(Optional) The name of the project that contains the subprocedure or subprocess.

Argument type: String

usrFormalParameter

If true or 1, use formal parameters data.

If false or 0, use formXML data.

Argument type: Boolean

Positional arguments

projectName, catalogName, catalogItemName

Response

Returns the new catalog item.

ec-perl

syntax: $<object>->createCatalogItem(<projectName>, <catalogName>, <catalogItemName>, {<optionals>});

Example

$cmdr->createCatalogItem("ENTBU Deploy", "ENTBU Q2 Catalog", "Oracle WebLogic", {buttonLabel => "Create"});
▼

ectool

syntax: ectool createCatalogItem <projectName> <catalogName> <catalogItemName> [optionals]

Example

ectool createCatalogItem "ENTBU Deploy" "ENTBU Q2 Catalog" "Oracle WebLogic" --buttonLabel "Create"
▼

deleteCatalog

Deletes a catalog.

Arguments Descriptions

projectName

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

Argument Type: String

Argument type: String

catalogName

The name of the catalog.

Argument type: String

Positional arguments

projectName, catalogName

Response

None or a status OK message.

ec-perl

syntax: $<object>->deleteCatalog(<projectName>, <catalogName>);

Example

$cmdr->deleteCatalog("ENTBU Deploy", "ENTBU Q2 Catalog");
▼

ectool

syntax: ectool deleteCatalog <projectName> <catalogName>

Example

ectool deleteCatalog "ENTBU Deploy" "ENTBU Q2 Catalog"
▼

deleteCatalogItem

Deletes a catalog item.

Arguments Descriptions

projectName

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

Argument Type: String

Argument type: String

catalogName

The name of the catalog.

Argument type: String

catalogItemName

The name of the catalog item.

Argument type: String

Positional arguments

projectName, catalogName, catalogItemName

Response

None or a status OK message.

ec-perl

syntax: $<object>->deleteCatalogitem(<projectName>, <catalogName>, <catalogItemName>);

Example

$cmdr->deleteCatalogitem("ENTBU Deploy", "ENTBU Q2 Catalog", "Oracle WebLogic");
▼

ectool

syntax: ectool deleteCatalogitem <projectName> <catalogName> <catalogItemName>

Example

ectool deleteCatalogitem "ENTBU Deploy" "ENTBU Q2 Catalog" "Oracle WebLogic"
▼

getCatalog

Retrieves a catalog by name.

Arguments Descriptions

projectName

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

Argument Type: String

Argument type: String

catalogName

The name of the catalog.

Argument type: String

Positional arguments

projectName, catalogName

Response

Returns the catalog.

ec-perl

syntax: $<object>->getCatalog(<projectName>, <catalogName>);

Example

$cmdr->getCatalog("ENTBU Deploy", "ENTBU Q2 Catalog");
▼

ectool

syntax: ectool getCatalog <projectName> <catalogName>

Example

ectool getCatalog "ENTBU Deploy" "ENTBU Q2 Catalog"
▼

getCatalogItem

Retrieves a catalog item by name.

Arguments Descriptions

projectName

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

Argument Type: String

Argument type: String

catalogName

The name of the catalog.

Argument type: String

catalogItemName

The name of the catalog item.

Argument type: String

Positional arguments

projectName, catalogName, catalogItemName

Response

Returns the catalog item.

ec-perl

syntax: $<object>->getCatalogItem(<projectName>, <catalogName>, <catalogItemName>);

Example

$cmdr->getCatalogItem("ENTBU Deploy", "ENTBU Q2 Catalog", "Oracle WebLogic");
▼

ectool

syntax: ectool getCatalogItem <projectName> <catalogName> <catalogItemName>

Example

ectool getCatalogItem "ENTBU Deploy" "ENTBU Q2 Catalog" "Oracle WebLogic"
▼

getCatalogItems

Retrieves all catalog items for a catalog.

Arguments Descriptions

projectName

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

Argument Type: String

Argument type: String

catalogName

The name of the catalog.

Argument type: String

Positional arguments

projectName, catalogName

Response

Returns the catalog items.

ec-perl

syntax: $<object>->getCatalogItems(<projectName>, <catalogName>);

Example

$cmdr->getCatalogItems("ENTBU Deploy", "ENTBU Q2 Catalog");
▼

ectool

syntax: ectool getCatalogItems <projectName> <catalogName>

Example

ectool getCatalogItems "ENTBU Deploy" "ENTBU Q2 Catalog"
▼

getCatalogs

Retrieves all catalogs in a project.

Arguments Descriptions

projectName

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

Argument Type: String

Argument type: String

Positional arguments

projectName

Response

Returns the catalogs.

ec-perl

syntax: $<object>->getCatalogs(<projectName>);

Example

$cmdr->getCatalogs("ENTBU Deploy");
▼

ectool

syntax: ectool getCatalogs <projectName>

Example

ectool getCatalogs "ENTBU Deploy"
▼

modifyCatalog

Modifies a catalog.

Arguments Descriptions

projectName

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

Argument Type: String

Argument type: String

catalogName

The name of the catalog.

Argument type: String

description

(Optional) Comment text describing this object; not interpreted at all by CloudBees CD/RO .

Argument type: String

iconUrl

(Optional) Set icon URL for a catalog.

Argument type: String

newName

(Optional) New name for an existing object that is being renamed.

Argument type: String

Positional arguments

projectName, catalogName

Response

None or a status OK message.

ec-perl

syntax: $<object>->modifyCatalog(<projectName>, <catalogName>, {<optionals>});

Example

$cmdr->modifyCatalog("ENTBU Deploy", "ENTBU Q2 Catalog", {newName=> "ENTBU Q3 Catalog", description => "Enterprise BU catalog for Q3 deployments"});
▼

ectool

syntax: ectool modifyCatalog <projectName> <catalogName> [optionals]

Example

ectool modifyCatalog "ENTBU Deploy" "ENTBU Q2 Catalog" --newName "ENTBU Q3 Catalog" --description "Enterprise BU catalog for Q3 deployments"
▼

modifyCatalogItem

Modifies an existing catalog item.

Arguments Descriptions

projectName

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

Argument Type: String

Argument type: String

catalogName

The name of the catalog.

Argument type: String

catalogItemName

The name of the catalog item.

Argument type: String

afterItem

(Optional) If specified, the catalog item will be placed after the named catalog item.

Argument type: String

beforeItem

(Optional) If specified, the catalog item will be placed before the named catalog item.

Argument type: String

buttonLabel

(Optional) The name of the button label.

Argument type: String

description

(Optional) Comment text describing this object; not interpreted at all by CloudBees CD/RO . This argument supports HTML. For example:

<xml>
 <title>This is the short description that is shown in the Service Catalog UI when the catalog items are first rendered.</title>
 <htmlData>
 <![CDATA[<div>
  This is the stylized HTML-based catalog item details that is shown when the user clicks the "more" link.
 </div>]]>
 </htmlData>
</xml>
▼

dslParamForm

(Optional) The DSL Parameter form metadata.

Argument type: String

dslString

(Optional) The DSL string that is evaluated for the catalog item.

Argument type: String

endTargetJson

(Optional) A DSL string to specify the end target object of the this catalog item. It has the following form:

"endTarget": {
     "source": "<source>",
      "object": "<objectType>",
      "objectName ": "<objectName>",
      "objectProjectName ": "<objectProjectName>",
      "objectId" : "<objectId>"
}
▼

where:

  • <source> is one of:

  • parameter —use values supplied with objectName, objectProjectName, and objectId as fields in the formal parameter; set useFormalParameter to true.

  • form —use values supplied with objectName, objectProjectName, and objectId as fields in the form or formal parameter (based on value of useFormalParameter argument).

  • property —use values supplied with objectName, objectProjectName, and objectId as properties.

  • name —use values supplied with objectName, objectProjectName, and objectId as literal strings.

  • <objectType> is the type of object.

  • <objectName> is the name of the object. Can be a literal string, property, or formal parameter field based on <source> type.

  • <objectProjectName> is the project. Can be a literal string, property, or formal parameter field based on <source> type.

  • <objectId> is the object id. Can be a literal string, property, or formal parameter field based on <source> type.

Argument type: String

firstItem

(Optional) True to make a catalog item the first in a catalog.

Argument type: Boolean

iconUrl

(Optional) The URL for the icon to be used in the UI. Place a custom icon for the catalog item in the <install_dir>/apache/htdocs/flow/public/app/assets/img folder and reference it using this attribute as public/app/assets/img/<image_name>.<extension>. For example, public/app/assets/img/mycatalogitem.jpg. You can use any browser-supported format such as .jpg, .png, or gif.

Argument type: String

newName

(Optional) New name for an existing object that is being renamed.

Argument type: String

subpluginKey

(Optional) The name of the procedure’s pluginKey.

Argument type: String

subprocedure

(Optional) The name of the subprocedure.

Argument type: String

subproject

(Optional) The name of the project that contains the subprocedure or subprocess.

Argument type: String

usrFormalParameter

If true or 1, use formal parameters data.

If false or 0, use formXML data.

Argument type: Boolean

Positional arguments

projectName, catalogName, catalogItemName

Response

None or a status OK message.

ec-perl

syntax: $<object>->modifyCatalogitem(<projectName>, <catalogName>, <catalogItemName>, {<optionals>});

Example

$cmdr->modifyCatalogitem("ENTBU Deploy", "ENTBU Q2 Catalog", "Oracle WebLogic", {newName => "Oracle WebLogic v2", buttonLabel => "Define"});
▼

ectool

syntax: ectool modifyCatalogitem <projectName> <catalogName> <catalogItemName> [optionals]

Example

ectool modifyCatalogitem "ENTBU Deploy" "ENTBU Q2 Catalog" "Oracle WebLogic" --newname "Oracle WebLogic v2"--buttonLabel "Define"
▼

runCatalogItem

Run a catalog item.

Arguments Descriptions

projectName

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

Argument Type: String

Argument type: String

catalogName

The name of the catalog under which catalogItemName is organized.

Argument type: String

catalogItemName

The name of the catalog item to run.

Argument type: String

actualParameter

List of parameter/value pairs in the form var1=val1. Applicable for catalog items defining formal parameters.

Argument type: list

formParameter

List of parameter/value pairs in the form var1=val1. Applicable for catalog items defining form XML parameters.

Argument Type: list

Positional arguments

projectName, catalogName, catalogItemName

===Authentication contexts

When runCatalogItem is initiated from a command job step, take into account the following:

  • For DSL-based catalog items, the DSL script is evaluated with principals in the authentication context of the launching job user and the procedure project.

  • For procedure- and plugin-based catalog items: the catalog item procedure is run with principals in the authentication context of the launching job project and the subprocedure project. So in this case the proper privileges must be provided for one of the project.

Consider this example:

  • A procedure, create-project, in project, ` test1`, with the following command step: ectool createProject $[projName]

  • A catalog item , catalogItem1, in catalog, testCatalog, in project, test2, where subproject= test1, subprocedure= create-project, and formal parameter is projName.

  • A procedure, testProcedure, in project, test3, with a command step: ectool runCatalogItem test2 testCatalog catalogItem1 --actualParameter projName=newProject

Run the procedure: ectool runProcedure test3 --procedureName testProcedure

Result: the run job completes with success, but the runCatalogItem job fails with the following error:

ectool error [AccessDenied]: None of the principals in this authentication context ('project: test3', 'project: test1')
have modify privilege on systemObject 'projects'
▼

Response

  • DSL-based catalog items: the response from evaluating the DSL.

  • Plugin-based catalog items: the job Id.

  • Procedure-based catalog items: the job Id.

ec-perl

syntax: $<object>->runCatalogItem(<projectName>, <catalogName>, <catalogItemName>, [<optionals>]);

Example

$cmdr->runCatalogItem({"CloudBees", "Pipelines", "Multi-stage CD Pipeline",
           actualParameter => [
              {actualparameterName => pipelineName, value =>"MyPipeline"},
              {actualparameterName => pipelineProjName, value => "Default"}
            ]
         });
▼

ectool

syntax: ectool runCatalogItem <projectName> <catalogName> <catalogItemName> [optionals]

Example

ectool runCatalogItem "CloudBees" "Pipelines" "Multi-stage CD Pipeline"
           --actualParameter pipelineName="MyPipeline" pipelineProjName="Default"
▼
Artifact management
Change history