runCatalogItem

Back to index

Summary

Run a catalog item.
projectName
Stringrequired
The name for the project that must be unique among all projects.
catalogName
Stringrequired
The name of the catalog.
catalogItemName
Stringrequired
The name of the catalog item.
actualParameter
Arrayoptional
Parameters passed as arguments to the procedure or to DSL.
credentialReferenceParameter
Arrayoptional
List of credential parameters with references to existing credentials as parameter values. If the parameter value is a property reference then the credential would be resolved at runtime.
credential
Arrayoptional
Credentials to be used in the job.
formParameter
Arrayoptional
Parameters passed as arguments to the DSL.
parsedWebhookData
Stringoptional
JSON with parsed webhook data to be set on a pipeline/release/procedure run.
scheduleName
Stringoptional
Name for the schedule; must be unique among all schedules for the project.
webhookData
Stringoptional
The webhook data to be set on the pipeline/release/procedure run.
webhookHeaders
Stringoptional
The webhook headers in JSON format to be set on the pipeline/release/procedure run.

Usage

Perl

$cmdr->runCatalogItem( "test-projectName", # projectName "test-catalogName", # catalogName "test-catalogItemName" # catalogItemName # optionals );

ectool

ectool runCatalogItem \ "test-projectName" `# projectName` \ "test-catalogName" `# catalogName` \ "test-catalogItemName" `# catalogItemName` \ # optionals

Examples

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. In this case, the proper privileges must be provided for one of the projects.

Consider this example:

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

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

  • A testProcedure procedure, in test3 project, 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.

Perl

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

ectool

ectool runCatalogItem "CloudBees" "Pipelines" "Multi-stage CD Pipeline" --actualParameter pipelineName="MyPipeline" pipelineProjName="Default"