Install and use PDK

The CloudBees PDK (Plugin Development Kit) is a versatile framework for developing plugins to interact with CloudBees CD/RO. The PDK is a combination of tools, specifications, APIs, and libraries that work together with the overall goal of making plugin development easy and consistent.

This page explains:

Installing PDK
Basic PDK command usage
Generating plugin workspaces
Reserved plugin workspace resources
Common scenarios in plugin development

Setup PDK

CloudBees offers two versions of the PDK framework: one compatible with Java 8 and 11 and another compatible with Java 17. Both PDK versions operate the same except for the required Java version. Based on your development requirements, follow the steps in the following sections.

Prerequisites

To use Java 17, the following minimum CloudBees CD/RO version requirements must be met or plugins using Java 17 cannot be used in your environment. You must use:

CloudBees CD/RO server v10.11 or later.
CloudBees CD/RO agent v10.5 or later.

Install PDK

Complete the following steps to set up the PDK environment for your required Java version:

Download and open the archive of one of the following pdk CLI options:
- Java 8 and 11 option:
  - Full bundle (pdk-cli-bundle.zip): Standalone version.
- Java 17 options:
  
  Ensure your system meets the minimum CloudBees CD/RO version requirements listed in Setup PDK.
  - Thin bundle (pdk-cli.zip): Requires internet connection during the generation/build process to fetch new versions of remote assets.
  - Full bundle (pdk-cli-bundle.zip): Standalone version.
Set the JAVA_HOME environmental variable to the top-level directory of the Java binary installation path.
To use the pdk CLI, include PDK in your PATH environmental variable. Once you have added it, ensure it is present.

PDK commands

The PDK CLI is structured as a hierarchy of commands with top-level commands, subcommands, and additional switches/options that control the output of the command:

pdk command subcommand [switches] [--option=value]▼

pdk config proxy <serverAddress> <port> -u <user> -p <password>▼

Top-level commands

Top-level commands perform PDK functions using subcommands and switches/options. The following sections explain these commands and their subcommands, switches/options, and common use cases.

The --help and -h switches can be used for PDK top-level commands and subcommands to display the basic descriptions in the terminal.

`pdk config`

This command is used to configure general-purpose defaults for the pdk utility, such as author, support URL, and so on. This command supports the following subcommands:

listoptions  List available configuration options
show         Show currently saved configuration
setoption    Set a specific configuration option▼

pdk config listoptions: Lists general-purpose defaults that can be configured for the pdk as a one-time setup.

Usage: pdk config listoptions

pluginAuthor: Default plugin author name to be set for the new plugins
supportUrl: Default support URL to be set for the new plugins
debugOn: If set to true, logs will be redirected to the log file.
verbosity: Log verbosity level. Only applicable if debugOn is enabled.▼

pdk config show: Shows the value of each configured item.
```
Usage: pdk config show

debugOn: false
verbosity: 2▼
```

pdk config setoption: Sets the value of an item.

Usage: pdk config setoption <optionName> <optionValue>

pdk config setoption pluginAuthor "James Doe"▼

`pdk generate`

This command is used to generate a templated plugin workspace (pdk generate workspace) or boilerplate code after modifying the plugin spec during development (pdk generate plugin).

Usage 1: pdk generate workspace
Usage 2: pdk generate plugin▼

pdk generate workspace: Generates a workspace for the plugin to hold the source code based on a standard layout. It can be invoked in one of the following ways:

Interactive mode with prompts to provide plugin metadata.
```
Usage 1: pdk generate workspace▼
```

Passing the values as arguments required to generate the workspace.

Usage 2: pdk generate workspace [--category=<category>] [--description=<description>] [--plugin-name=<pluginName>] [--author=<author>] [--support-url=<supportUrl>]▼

When generating the workspace, choose the type of workspace (category) based on your plugin use case.

default: Generates a generic plugin with an example procedure section in the plugin spec.
rest: Generates a REST-based plugin with an example REST procedure section in the plugin spec.
reporting: Generates a plugin to retrieve third-party data for reporting purposes, and includes a reporting section in the plugin spec.

pdk generate plugin: Generates/updates the plugin workspace using the configuration defined in config/pluginspec.yaml.

When you make changes in the config/pluginspec.yaml, run pdk generate plugin. This ensures your changes are applied to files generated by the PDK, and your workspace stays synced.
```
Usage: pdk generate plugin --overwrite  --upgrade
--overwrite This flag forces rewrite for auto-generated portions of code on files shared with user.
--upgrade   This flag will launch the upgrade process for plugin cores.▼
```

`pdk build`

This command is used to compile the plugin into an executable archive (.zip) that can be imported to CloudBees CD/RO. You must execute pdk build in the root directory of the plugin workspace. Once the plugin is compiled, a build directory is created that contains your <YOUR-PLUGIN>.zip.

Usage: pdk build▼

`pdk showdoc`

This command shows the description of the various fields that make up the plugin spec to provide reference during plugin development.

pdk showdoc pluginspec: Produces a list of fields available in the pluginspec and their description.
```
Usage : pdk showdoc pluginspec▼
```
pdk showdoc toolkit: Shows the full PDK --help reference.
```
Usage: pdk showdoc toolkit▼
```

`pdk describe`

Shows the version of plugin pdk dependencies, as described in the config/flowpdf.yaml.

Usage: pdk describe

Layout version: 1.0.10
Language core Perl version: 1.1.11▼

`pdk debug`

This command is used to manage logs written by PDK, with required verbosity where appropriate. When debug is enabled, logs are written to a log file called pdk.log in the <PDK-HOME-DIR>/.flowpdf directory.

pdk debug on: Enables debug and write logs to pdk.log under the /bin directory. Default is the lowest verbosity.
```
Usage: pdk debug on▼
```
pdk debug off: Disables debug and does not write logs.
```
Usage: pdk debug off▼
```
pdk debug purge: Purges debug logs.
```
Usage: pdk debug off▼
```
pdk debug setverbosity: Sets the debug verbosity level (info|debug|trace).
```
Usage: pdk debug setverbosity

pdk debug setverbosity info|debug|trace▼
```

pdk debug check: Returns detailed information about your PDK installation, its dependencies, and its runtime environment.

Usage: pdk debug check▼

Example

pdk debug check▼

INFO: Writing log to the file <PDK-HOME-DIR>.flowpdf/pdk.log
INFO: Version Data
INFO: pdk version 4.0.2
INFO: toolkit version 4.0.2
INFO: Build Timestamp: 2023-12-27T16:52:47.348+0000
INFO: Build Number: 0
INFO: Commit: b7babaa405e82886a57ed142c79a5074130faf89
INFO: Built with Java: 17.0.7
INFO: OS: <YOUR-OS>
INFO: Java version: 17.0.10
INFO: Configuration file: <PDK-HOME-DIR>.flowpdf/config
INFO: Configuration values
INFO: pluginAuthor = null (Default plugin author name to be set for the new plugins)
supportUrl = null (Default support URL to be set for the new plugins)
debugOn = true (If set to true, logs will be redirected to the log file.)
verbosity = 0 (Log verbosity level. Only applicable if debugOn is enabled.)
ignoreSslIssues = false (HTTP clients ignore issues with SSL certificates.)
proxyHost = null (Host to connect through proxy server)
proxyPort = 0 (Proxy server port to connect)
proxyUsername = null (Proxy server authorization username)
proxyPassword (SECRET, Password to connect to the proxy server) = Not Set
proxyScheme = null (Proxy scheme to connect to the proxy server. HTTP by default.)▼

Generic switches

--help or -h provides help at any level of the hierarchy.

The --help and -h switches can be used for all top-level commands PDK commands.

pdk --help▼

Usage: pdk [-hv] [COMMAND]
Commands:
config    Configure the pdk utility
generate  Generate a plugin workspace along with a starter plugin spec or a plugin from a filled
          in plugin spec.
build     Build the plugin
showdoc   Show the description of the various fields that make up the plugin spec
describe  Show the content of the pdk spec which contains its dependencies
debug     Turn on/off/purge logs written by the pdk utility with required verbosity where
          appropriate. When debug is enabled logs will be written to a log file called pdk.
          log under the pdk/bin directory.

pdk config setoption --help

Usage: pdk config setoption [-h] [-v]... optionName optionValue
Description: Set a specific configuration option
optionName    Option name
optionValue   Option value▼

--version or -v provides miscellaneous version information about pdk.

pdk --version▼

pdk version 4.0.2
toolkit version 4.0.2
Build Timestamp: 2023-12-27T16:52:47.348+0000
Build Number: 0
Commit: b7babaa405e82886a57ed142c79a5074130faf89
Built with Java: 17.0.7▼

Bash autocomplete

A built-in autocomplete is packaged with PDK, but must be initialized in your installation. To generate the autocomplete script, run the following:

pdk config generate-completion▼

INFO: Writing log to the file <PDK-INSTALLATION_DIR>/.flowpdf/pdk.log
INFO: Saved completion script into <PDK-INSTALLATION_DIR>/.flowpdf/pdk_completion, file is set executable
INFO: Please add source <PDK-INSTALLATION_DIR>/.flowpdf/pdk_completion to your .bashrc or .zshrc file▼

PDK generates an autocompletion script for Bash and adds it to the PDK configuration installation directory. To enable autocompletion, source this script in your .bashrc or .zshrc.

Once your terminal session sources your profile, run:

pdk<TAB>▼

pdk
build          cc             config         cookie-cutter  debug          describe       generate       server         showdoc        watchpatch▼

Generate plugin example

You have completed Setup PDK, before you can complete these steps.

This section demonstrates the minimal steps to generate a basic plugin using PDK:

Navigate to the directory where you want to generate the plugin.

Generate the plugin workspace, by running:

For this exercise, you only need to provide a plugin name, and all other values can be set to default. In the following examples, QuickStartPlugin is used as the plugin name.

pdk generate workspace▼

 >> pdk generate workspace
INFO: Plugin name is not provided
Please provide a name for the new plugin, e.g. MyPlugin: QuickStartPlugin
Please provide a workspace type or types.
Available types are rest, reporting or default (default: 'default', separated by a comma or a space):
Please provide the author name (default: none):
Please provide the support URL (default: none):
Please provide the plugin category (default: Utilities):
Please provide the description for the plugin: Demo plugin for QuickStart
Please provide the language for the plugin (default: groovy, available languages are perl, groovy):
WARN: Language  is not supported, Groovy will be used by default
WARN: Language  is not supported, Groovy will be used by default
INFO: Wrote initial declaration to ~/work/plugins: QuickStartPlugin/config/pluginspec.yaml
INFO: Plugin folder is ~/work/plugins: QuickStartPlugin
INFO: Wrote flowpdf specification into ~/work/plugins: QuickStartPlugin/config/flowpdf.yaml
INFO: Initial plugin spec has been placed into ~/work/plugins: QuickStartPlugin/config/pluginspec.yaml
INFO: Go into the plugin directory: 'cd ~/work/plugins: QuickStartPlugin'
INFO: Change the plugin spec and run 'pdk generate plugin' from the plugin directory▼

This step used the interactive mode to create the plugin workspace/directories, and you were prompted to provide your plugin metadata. You can also pass plugin metadata as arguments, refer to Generate PDK workspace with arguments.

The PDK generates the following directory structure:

QuickStartPlugin
└── config
    ├── flowpdf.yaml
    └── pluginspec.yaml

The flowpdf.yaml contains PDK metadata about your plugin. If the data in this file is erroneously modified, your plugin may behave in expected ways or not function.

flowpdf.yaml example

flowpdf-plugin-spec: 2
flowpdf-groovy-sdk: 1.3.0
flowpdf-plugin-layout: 1.3.7▼

For more information about reserved PDK and plugin resources, refer to Reserved PDK and plugin resources.

Open and review the config/pluginspec.yaml, which contains the following sections:

pluginInfo: This section contains the plugin metadata.

Example pluginInfo section

pluginInfo:
  # This is default sample specification
  # Feel free to change it
  # Call pdk showdoc pluginspec to see the list of available fields and their description
  pluginName: 'QuickStartPlugin'
  version: '1.0.0'
  description: 'Demo plugin for QuickStart'
  author: 'none'
  supportUrl: 'none'
  category: 'Utilities'
  shell: 'ec-groovy'▼

configuration: This section contains the fields and parameters used to create plugin configurations in CloudBees CD/RO.

Example configuration section

# Plugin configuration description
configuration:
  # This is a shell used for checking connection
  shell: 'ec-groovy'
  # A script for checking connection will be generated
  checkConnection: 'true'
  # A set of fields will be added to process debug level in the configuration
  hasDebugLevel: true
  parameters:
  -
    name: config
    documentation: The name for the created configuration
    required: true
    type: entry
    label: Configuration Name
  -
    name: desc
    documentation: Description for the configuration
    required: false
    type: entry
    label: Description
  -
    name: endpoint
    documentation: Third-party endpoint to connect to.
    required: false
    type: entry
    label: Endpoint
  -
    name: credential
    documentation: A sample credential
    required: true
    type: credential
    label: Credential▼

procedures: This section contains the fields and parameters for plugin procedures.

Example procedures section

procedures:
-
  name: 'Sample Procedure'
  description: 'Sample procedure description'
  # configuration field will be generated automatically
  hasConfig: true
  parameters:
  -
    name: applicationPath
    documentation: Path to the application
    required: true
    type: entry
    label: Application Path
  outputParameters:
    deployed: 'JSON representation of the deployed application'▼

In your plugin root directory, generate the plugin code by running:

pdk generate plugin▼

The generated plugin directory structure should be similar to:

Generated plugin directory structure

.
├── README.md
├── agent
│   ├── README.md
│   └── deps
│       └── libs
│           └── flowpdf-groovy-lib-2.0.3.0.jar
├── build.gradle
├── config
│   ├── flowpdf.yaml
│   └── pluginspec.yaml
├── dsl
│   ├── procedures
│   │   ├── CreateConfiguration
│   │   │   └── steps
│   │   │       └── checkConnection.groovy
│   │   ├── SampleProcedure
│   │   │   └── steps
│   │   │       └── SampleProcedure.groovy
│   │   └── TestConfiguration
│   │       └── steps
│   │           └── checkConnection.groovy
│   └── properties
│       └── groovy
│           └── lib
│               ├── QuickStartPlugin.groovy
│               └── SampleProcedureParameters.groovy
├── htdocs
│   ├── images
│   │   └── icon-plugin.svg
│   └── pluginhelp.css
└── pages
    └── help.xml▼

Review the boilerplate code for Sample Procedure generated by PDK, by opening dsl/properties/groovy/lib/SampleProcedureParameters.groovy. This file contains the code logic for this procedure, and would be where to modify it during plugin development.

For a better understanding of how this code is generated, open config/pluginspec.yaml, and refer to procedures.name=Sample Procedure.

In your plugin root directory, build the plugin by running:

pdk build▼

This compiles the plugin image as a .zip in the build directory.

This plugin currently has no real functionality, and should not be added to your CloudBees CD/RO instance as is. However, for instructions on how you would import this file into your CloudBees CD/RO instance, refer to Install plugins from a file.

As is, this plugin has no real functionality. If you were developing an actual plugin, you would now modify the config/pluginspec.yaml and procedure code in the corresponding files. For more information, refer to Common development use cases.

If you want more practice developing plugins, you can also try the Basic Jira plugin tutorial. It demonstrates developing a functional plugin that retrieves data about issues in your Jira instance using a Groovy-based plugin.

Reserved PDK and plugin resources

Some pdk generated resources are critical to the behavior of your plugin’s interactions with CloudBees CD/RO, and thus, reserved. These reserved resources include:

Modifying these resources may result in your plugin behaving in unexpected ways or not functioning.

The .assets, META-INF, and core directories in their entirety.
The files flowpdf.yaml, Baseplugin.groovy, form.xml (under individual procedures), and deleteConfiguration.pl in their entirety.

Any block of code between the ## DO NOT EDIT THIS BLOCK markers in any generated files, such as shown in the following example:

## DO NOT EDIT THIS BLOCK === rest client imports starts ===
package FlowPlugin::CBGitRESTClient;
use strict;
use warnings;
use LWP::UserAgent;
use JSON;
use Data::Dumper;
use FlowPDF::Client::REST;
use FlowPDF::Log;
## DO NOT EDIT THIS BLOCK === rest client imports ends, checksum: 96d6a71a265e9e05f1b5eb17e5a29ac1 ===▼

Any one-line marker used to demarcate system-generated procedure code boundaries, such as shown in the following example:
```
## === step ends ===
# Please do not remove the marker above, it is used to place new procedures into this file.▼
```

Common development use cases

This section provides information about common use cases involved in plugin development, a description of how PDK handles them, and recommended user actions.

Whenever modifying your plugin config/pluginspec.yaml, ensure you run pdk generate plugin to update the corresponding workspace resources.

Add a new procedure

PDK behavior: A new folder in the dsl/procedures folder is created to store the procedure metadata. A new section is generated for the main module. A procedure is added to the dsl/promote.groovy to the list of "steps with credentials", but only if the procedure requires configuration.

Recommended Action: Change the generated boilerplate code to introduce the required logic for the new procedure.

Delete a procedure

PDK behavior: The folder with the procedure metadata is deleted. The procedure steps are removed from the dsl/promote.groovy, but the code section is not deleted.

Recommended Action: Cleanup the code in the main module code by removing the method that was previously associated with the procedure.

Add a new input/output procedure parameter

PDK behavior: The procedure specification in the procedure directory is updated (form.xml and procedure.dsl). Recommended Action Update the procedure code in the main module to incorporate the new parameter.

Rename a procedure

PDK behavior: Renaming is handled as Delete and Add action. The directory for the procedure with the old name is deleted, and a new one is created. The dsl/promote.groovy file is updated with the new procedure name and a new code block with the method name referencing the new procedure name is generated.

Recommended Action: Transfer whatever logic the old procedure method contained to the newly generated boilerplate and remove the old procedure method.

Update procedure parameter

PDK behavior: The procedure specification in the procedure directory is updated (form.xml).

Recommended Action: None.

Delete procedure parameter

PDK behavior: The procedure specification in the procedure directory is updated (form.xml).

Recommended Action: Update the procedure code (in the main module) to handle the deletion of the parameter.

Rename procedure parameter

PDK behavior: The procedure specification in the procedure directory is updated (form.xml).

Recommended Action: Update the procedure code (in the main module) to handle the new parameter name.

Configuration parameter added/renamed/removed

PDK behavior: The form.xml of the CreateConfiguration procedure is modified.

Recommended Action: None

New REST action added to configuration

PDK behavior: The form.xml of the CreateConfiguration procedure is modified.

Recommended Action: None

New REST-based auth scheme in configuration

PDK behavior: The form.xml of the CreateConfiguration procedure is modified according to the REST layout.

Recommended Action: None

Add checkConnection to configuration

PDK behavior: If there is a REST section, an auto-generated REST check connection script is added. If there is no REST section, a boilerplate step for checking the connection is generated instead.

Recommended Action: None

REST endpoint added to `restclient` section

PDK behavior: A method for this REST endpoint is generated in the REST client.

Recommended Action: Utilize the newly generated method in the procedure code.

REST endpoint removed from `restclient` section

PDK behavior: The proxy method corresponding to the REST endpoint is removed from the REST client.

Recommended Action: Cleanup the method usages from the main module code.

New parameter added to `restclient` section endpoint

PDK behavior: The method for the endpoint is regenerated in the REST client to accommodate the new parameter.

Recommended Action: Change the method call in the main module to accommodate the new parameter.

Parameter removed from REST client endpoint

PDK behavior: The endpoint method is regenerated in the REST client to accommodate the updated set of parameters.

Recommended Action: Change the method call in the main module to accommodate the changes.

New `devOpsInsight` section added

PDK behavior: A new procedure named CollectReportingData is generated along with a set of reporting dashboard scripts and forms under dsl/properties. A new module called <PluginName>/Reporting.pm is generated. The code for the CollectReportingData procedure is generated and placed in the main module.

Recommended Action: Change the reporting module to accommodate your reporting logic and change the code for the CollectReportingData procedure to provide the actual parameters required for your particular case.

New payload type added to `devOpsInsight` section

PDK behavior: A new set of dashboard scripts is added.

Recommended Action: Change the main module and the reporting module to incorporate the change in the payload types.

New parameter added to `devOpsInsight` section

PDK behavior: Forms for both CollectReportingData procedure as well as the dashboard get generated.

Recommended Action: Incorporate the new parameter in both the main module and reporting module.

Parameter removed from devOpsInsight section

PDK behavior: Forms for both CollectReportingData procedure as well as the dashboard get generated.

Recommended Action: Incorporate the new parameter in both the main module and reporting module.

Payload type in devOpsInsight section removed/renamed

PDK behavior: The folder with the dashboard scripts for the old payload type is removed.

Recommended Action: Incorporate the new parameter in both the main module and reporting module.

Install and use PDK

Setup PDK

Prerequisites

Install PDK

PDK commands

Top-level commands

pdk config

pdk generate

pdk build

pdk showdoc

pdk describe

pdk debug

Generic switches

Bash autocomplete

Generate plugin example

Reserved PDK and plugin resources

Common development use cases

Add a new procedure

Delete a procedure

Add a new input/output procedure parameter

Rename a procedure

Update procedure parameter

Delete procedure parameter

Rename procedure parameter

Configuration parameter added/renamed/removed

New REST action added to configuration

New REST-based auth scheme in configuration

Add checkConnection to configuration

REST endpoint added to restclient section

REST endpoint removed from restclient section

New parameter added to restclient section endpoint

Parameter removed from REST client endpoint

New devOpsInsight section added

New payload type added to devOpsInsight section

New parameter added to devOpsInsight section

Parameter removed from devOpsInsight section

Payload type in devOpsInsight section removed/renamed

`pdk config`

`pdk generate`

`pdk build`

`pdk showdoc`

`pdk describe`

`pdk debug`

REST endpoint added to `restclient` section

REST endpoint removed from `restclient` section

New parameter added to `restclient` section endpoint

New `devOpsInsight` section added

New payload type added to `devOpsInsight` section

New parameter added to `devOpsInsight` section