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

Plugin Management

7 minute readReference

createPlugin

Creates a plugin. You can create an entirely new plugin or a plugin based on an existing plugin project.

You must specify key, version, and projectName.

Arguments Descriptions

category

(Optional) Category for the plugin. Categories let you group plugins by functionality or purpose and provide a convenient way to look up a specific plugin if you know its functionality or purpose. For example, when you are configuring a process step and want to deploy an application on WebSphere, you first choose the Application Server category and then the WebSphere plugin. The default category is Utility.

Argument type: String

pluginWizardBased

(Optional) Whether the plugin conforms to the standard format used by plugins that are created using the Plugin Manager. The default is false or 0 (meaning that the format is not used).

Argument type: Boolean

key

Version-independent name for the plugin.

Argument type: String

version

Plugin version.

Argument type: String

projectName

Name of the project. This is not required if the pluginWizardBased argument is set to true, in which case the plugin name is used as the name of the project to be created. Therefore, this argument is optional if you also set the pluginWizardBased argument to true or 1.

Argument type: String

author

(Optional) Plugin author’s name. For example, a user or organization name. The current user name (such as System Administrator ) is used by default.

Argument type: String

authorUrl

(Optional) Plugin author’s URL. For example, https://example.com/integrations/docker.

Argument type: String

description

(Optional) Plain text or HTML description of the parameter. CloudBees CD/RO does not interpret this text.

If using HTML, you must surround the text with < html> …​ </html> tags. The following HTML tags are allowed: <a> <b> <br> <div> <dl> <font> <i> <li> <ol> <p> <pre> <span> <style> <table> <tc> <td> <th> <tr> <ul>.

Argument type: String

label

(Optional) Label to display in lists of plugins.

Argument type: String

supportsConfigurations

(Optional) Whether to allow the addition of plugin procedures to support the creation of plugin configurations. Enabling this option adds the Configuration Setup tab to the Project Details page in the Automation Platform UI for this plugin. The value is false by default (meaning that configurations are not supported). You must use this argument when using the pluginWizardBased argument.

If this argument is set to true, the CreateConfiguration and DeleteConfiguration plugin configuration procedures are added to the plugin (go to the Procedures tab of the Project Details page for this plugin to see these procedures).

Argument type: Boolean

Positional arguments

key, version, and projectName

Response

Returns a plugin object.

ec-perl

syntax: $cmdr->createPlugin(<key>, <version>, <projectName>, {<optionals>});

Example

$cmdr->createPlugin("SCM-P4", "2.1.3", "Default", {author => "jdoe"});
▼

ectool

syntax: ectool createPlugin <key> <version> <projectName> [optionals]

Example

ectool createPlugin "SCM-P4" "2.1.3" "Default" --author "jdoe"
▼

deletePlugin

Deletes an existing plugin object without deleting the associated project or files.

You must specify a pluginName.

Arguments Descriptions

pluginName

Name of the plugin.

Argument type: String

Positional arguments

pluginName

Response

None or a “status OK” message.

ec-perl

syntax: $cmdr->deletePlugin(<pluginName>);

Example

$cmdr->deletePlugin("TheWidget-1.0");
▼

ectool

syntax: ectool deletePlugin <pluginName>

Example

ectool deletePlugin "TheWidget-1.0"
▼

exportPlugin

Exports a plugin to a .zip file. You can use this file to import a plugin to another CloudBees CD/RO server.

Arguments Descriptions

pluginKey

Name given to the plugin when it was created. For example, MyPlugin. In other words, the given name of the plugin without the version number. This name does not include the plugin version. This is required if you do not specify pluginName. If you use this argument, the promoted version of the plugin is exported.

Argument type: String

pluginName

Fully-qualified name of the plugin. This name includes the given name of the plugin and its version number. For example, MyPlugin-1.0.0.4, where MyPlugin is the given name, and 1.0.0.4 is the plugin version.

Argument type: String

fileName

File name of the plugin .zip file to export. The plugin zip file is downloaded to your system as <filename> - <version> .zip .

Argument type: String

Positional arguments

pluginName and fileName

ec-perl

syntax: $cmdr->exportPlugin(pluginName, fileName);

Example

$cmdr->exportPlugin("MyPlugin-1.0.0.4", "MyPluginName.zip");
▼

ectool

syntax: ectool exportPlugin "<plugin_name>" "<plugin_file_name>"

Example

ectool exportPlugin "MyPlugin-1.0.0.4" "MyPluginName.zip"
▼

getPlugin

Retrieves an installed plugin.

Arguments Descriptions

pluginName

Name of the plugin to find. If the name is specified without a version number, the currently promoted version is returned if a promoted version exists.

Argument type: String

Positional arguments

pluginName

Response

One plugin element, which includes the plugin ID, name, time created, label, owner, key, version, and so on.

ec-perl

syntax: $cmdr->getPlugin(<pluginName>);

Example

$cmdr->getPlugin("TheWidget");
▼

ectool

syntax: ectool getPlugin <pluginName>

Example

ectool getPlugin "TheWidget"
▼

getPlugins

Retrieves all installed plugins.

Arguments Descriptions

None

–

Positional arguments

None

Response

Zero or more plugin elements.

ec-perl

syntax: $cmdr->getPlugins();

Example

$cmdr->getPlugins();
▼

ectool

syntax: ectool getPlugins

Example

ectool getPlugins
▼

installPlugin

Installs a plugin from a .jar or .zip file. Extracts the .jar or .zip file contents on the server and creates a project and a plugin.

Arguments Descriptions

url

Location of the plugin .jar file to install:

  • If the location .jar to a file on the client machine, the file is uploaded to the server.

  • If the location refers to a remote accessible file (for example, via a URL), the server downloads it.

  • If the location is a file: reference, the file is read directly from the specified location on the server file system.

Argument type: String

disableProjectTracking

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

If this argument is set to 1 or true when you import or export a project, even if the original project had Change Tracking enabled, this disables Change Tracking of the newly imported or exported project.

If you do not need to track changes in the new project, this avoids the Change Tracking overhead that would slow down the import operation. This also saves having to subsequently disable change tracking of the re-imported project.

Argument type: Boolean

force

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

Specifying 0 or false causes an existing plugin with the same key and version to be overwritten with the new plugin contents; otherwise an error is returned.

Argument type: Boolean

reducedDetailChangeHistory

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

Use this argument for large projects containing over 20,000 audited objects with Change Tracking enabled.

When this argument is set to true or 1, CloudBees CD/RO automatically decreases the amount of Change History indexing information that it saves in a large project, which reduces the level of detail for Change Tracking-intensive operations in the change history. This can make it harder to revert an object to a specific state and to find information in the change history when you troubleshoot or debug an issue.

Set this argument to false or 0 to suppress this behavior so that CloudBees CD/RO does not change the amount of indexing information for a large project. This causes the operation to take longer and put more load on the database, but the change history will have the full details of the entities owned by objects in the project.

Argument type: Boolean

Positional arguments

url

Response

One plugin element.

ec-perl

syntax: $cmdr->installPlugin(<url>, {optionals});

Example

$cmdr->installPlugin("./myPlugin.jar", {disableProjectTracking => 1})
▼

ectool

syntax: ectool installPlugin <url> [optionals]

Example

ectool installPlugin "./myPlugin.jar" --disableProjectTracking 1
▼

modifyPlugin

Modifies an existing plugin.

Some plugin attributes available on the Plugins page are not available in any of the plugin-related APIs. Because some plugin metadata comes from the plugin.xml file, the web server can access this data, but the CloudBees CD/RO server cannot. Thus, the Plugin Manager, when run in the web server context, provides additional information and functionality.
Arguments Descriptions

category

(Optional) Category for the plugin. Categories let you group plugins by functionality or purpose and provide a convenient way to look up a specific plugin if you know its functionality or purpose. For example, when you are configuring a process step and want to deploy an application on WebSphere, you first choose the Application Server category and then the WebSphere plugin.

Argument type: String

extensionVersion

(Optional) Number that CloudBees CD/RO uses to differentiate between the CloudBees created plugins that you downloaded but did not modify or extend and CloudBees created plugins that you have modified or extended. This prevents a CloudBees CD/RO upgrade that also upgrades the corresponding bundled plugin from overwriting the plugin that you have modified or extended.

Use only positive integers with no other characters. For example, 12. The default is 1.

For details about version extensions, see Plugin Manager.

pluginName

Plugin name. If the name is specified without a version number, the currently promoted version is used if one exists.

Argument type: String

author

(Optional) Plugin author’s name. For example, a user or organization name. The current user name (such as System Administrator ) is used by default.

Argument type: String

authorUrl

(Optional) Plugin author’s URL. For example, https://example.com/integrations/docker.

Argument type: String

description

(Optional) Plain text or HTML description of the parameter. CloudBees CD/RO does not interpret this text.

If using HTML, y ou must surround the text with < html> …​ </html> tags. The following HTML tags are allowed: <a> <b> <br> <div> <dl> <font> <i> <li> <ol> <p> <pre> <span> <style> <table> <tc> <td> <th> <tr> <ul>.

Argument type: String

label

(Optional) Label to display in plugin lists.

Argument type: String

supportsConfigurations

(Optional) Whether to allow the addition of plugin procedures to support the creation of plugin configurations. Enabling this option adds the Configuration Setup tab to the Project Details page in the Automation Platform UI for this plugin. The value is false by default (meaning that configurations are not supported).

If this is set to true, the CreateConfiguration and DeleteConfiguration plugin configuration procedures are added to the plugin (go to the Procedures tab of the Project Details page for this plugin to see these procedures).

Argument type: Boolean

Positional arguments

pluginName

Response

One plugin element.

ec-perl

syntax: $cmdr->modifyPlugin(<pluginName>, {<optionals>});

Example

$cmdr->modifyPlugin('TheWidget', {description => "new description"});
▼

ectool

syntax: ectool modifyPlugin <pluginName> [optionals]

Example

ectool modifyPlugin TheWidget --description "new description"
▼

promotePlugin

Sets the promoted flag on a plugin. Only one version of a plugin can be promoted at a time, so setting the promoted flag to true on one version sets the flag to false on all other plugins with the same key. The promoted version is the one resolved by an indirect reference of the form $[/plugins/<key>] or a plugin name argument without a specified version.

Arguments Descriptions

pluginName

Name of the plugin to promote. If the name is specified without a version number, the currently promoted version is used if one exists.

Argument type: String

promoted

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

New value of the promoted flag for the specified plugin. The default is true, which means the plugin will be promoted. To demote the plugin, use the value of 0 or false.

Argument type: Boolean

Positional arguments

pluginName

Response

One plugin element, which includes the plugin ID, name, time created, label, owner, key, version, project name, and so on.

ec-perl

syntax: $cmdr->promotePlugin(<pluginName>, {<optionals});

Example

$cmdr->promotePlugin("TheWidget-1.0");
▼

ectool

syntax: ectool promotePlugin <pluginName> [optionals]

Example

ectool promotePlugin TheWidget-1.0
▼

uninstallPlugin

Uninstalls a plugin and deletes the associated project and any installed files.

Arguments Descriptions

pluginName

Name of the plugin to uninstall. If the name is specified without a version number, the currently promoted version is used if one exists.

Argument type: String

timeout

(Optional) Maximum amount of time to spend waiting for this operation to complete.

Argument type: Long

Positional arguments

pluginName

Response

None or a “status OK” message.

ec-perl

syntax: $cmdr->uninstallPlugin(<pluginName>, {<optionals>});

Example

$cmdr->uninstallPlugin("TheWidget-1.0");
▼

ectool

syntax: ectool uninstallPlugin <pluginName> [optionals]

Example

ectool uninstallPlugin TheWidget-1.0
▼
Pipelines and releases
Plugin configuration management