Tool

Setup

Go through the following steps to set up the environment.

  1. Download pdk CLI from the link provided in the GitHub Public Repository for pdk. The name of the zip file is called flowpdf-cli.zip. Unzip it.

  2. pdk CLI requires a JRE (with a Java version of 1.8.0_181 or higher) and expects the JAVA_HOME environment variable to be set to the install path of the top folder that contains the java binary. For example, if java is under /opt/electriccloud/electriccommander/jre/bin then JAVA_HOME should look like the following snippet.

    $ ls -lrt /opt/electriccloud/electriccommander/jre/bin | grep java
    
    -r-xr-xr-x 1 vagrant vagrant 128791 Mar 15  2017 javaws
    -r-xr-xr-x 1 vagrant vagrant   7734 Mar 15  2017 java
    vagrant@commander5:/vagrant/plugindevguide/docs$ echo $JAVA_HOME
    /opt/electriccloud/electriccommander/jre
  3. In order to use pdk set the PATH to include it. For instance,

    $ echo $PATH
    
    /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/opt/electriccloud/electriccommander/bin:/vagrant/framework/pdk/bin

Command hierarchy

The CLI is structured as a hierarchy of commands with each top level command having subcommands and additional switches/options that control the output of the command. This is a list of all top level commands and their purpose. The following is an example of a hierarchy:

pdk (CLI)
    pdk config (config command)
            pdk config listoptions (config with listoptions as a subcommand)

Top-level commands

Command Description

config

Used to configure the pdk utility for general purpose defaults—​plugin author, support URL, and so on.

generate

Used for one of the following scenarios:

  • Generate a plugin workspace containing an empty starter plugin spec for a new plugin, the first time.

  • Generate the boilerplate code for a plugin after filling/modifying the plugin spec, during the course of plugin development.

build

Used to build the plugin.

showdoc

Used to show the description of the various fields that make up the plugin spec. This can be used as a reference during plugin procedure interface development.

describe

Shows the various dependencies and their versions of pdk. This is typically used.

debug

Turns on/off/purge logs written by the utility with required verbosity where appropriate. When debug is enabled logs are written to a log file called pdk.log under the $HOME/.flowpdf directory.

cookie-cutter

Manages process as code projects. This command should run from a project root: the folder that contains project.dsl file in it.

Generic switches

  • --help or -h provides the help at any level of the hierarchy. Here are some examples.

    $ 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 1.0.0
    toolkit version 1.0.0
    Build Timestamp: 2019-06-19T15:01:45.409+0300
    Build Number: 138
    Commit: a1104bcf6b44276ce93a44876eff27c29e701f05
    Built with Java: 1.8.0_201

Command list

pdk config

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 items 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 of the configured items.

    Usage: pdk config show
    
    debugOn: false
    verbosity: 2
  • pdk config setoption: sets the value of each item.

    Usage: pdk config setoption <optionName> <optionValue>
    
    pdk config setoption pluginAuthor "James Doe"

pdk generate

This command is sensitive to the directory from which it is executed. For example, if you execute pdk generate workspace from directory X and call your plugin EC-Myplugin, the workspace called EC-Myplugin is created under X. Similarly if you want to generate plugin EC-Myplugin, generate plugin should be executed from the directory EC-MyPlugin.

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. The first one is in interactive mode and the second one is passing the values required to generate the workspace on the command line.

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

    When generating the workspace choose the following types based on your use case.

    • default: starts on a simple template. This generates a sample procedure section in the plugin spec.

    • rest: builds a rest plugin. This generates a sample rest based procedure section in the plugin spec.

    • reporting: interfaces with third party to bring in data for reporting purposes. This generates a reporting section in the plugin spec.

  • pdk generate plugin: generates a plugin in the workspace using the spec defined in pluginspec.yaml.

    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 builds a plugin and should be executed from the root directory of the plugin workspace.

Usage: pdk build plugin

pdk showdoc

This command is used to show documentation corresponding to various aspects of pdk.

  • 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 help for utility in one page.

    Usage: pdk showdoc toolkit

pdk describe

Show the version of all the dependencies of pdk.

Usage: pdk describe

Layout version: 1.0.10
Language core Perl version: 1.1.11

pdk debug

This command is used to manage the creation of logs written by the utility with required verbosity where appropriate.

  • pdk debug on: enable debug and write logs to pdk.log under the /bin directory. Default is lowest verbosity.

    Usage: pdk debug on
  • pdk debug off: disable debug and do not write logs.

    Usage: pdk debug off
  • pdk debug purge: purge debug logs.

    Usage: pdk debug off
  • pdk debug setverbosity: set the verbosity level of debug log to one of infotrace.

    Usage: pdk debug setverbosity
    
    pdk debug setverbosity trace
  • pdk debug check: Returns detailed information about (for example build timestamp, commit id), its dependencies (for example Perl library version, groovy library version) and its runtime environment (for example Java version). Note that this command provides more detailed information than desc.

    Usage: pdk debug check

Aliases: cc

The command executes incremental update for the project. It saves its state under folder .cdproj that is located under the project root, in the same folder where project.dsl is located. After the command runs for the first time, it saves the timestamp in the state, and uses this timestamp to determine which files were updated. The next runs applies changes only from updated files. The command is using session saved by ectool login command, execute it before running the command or provide COMMANDER_SESSIONID environment variable.

Usage: pdk cc --hostname 

pdk watchpatch

Access to live plugin update functions. The command hangs in the background and waits until a file in the plugin directory is saved and then updates the corresponding property on the CloudBees CD server. Only properties in the dsl/properties folder are supported.

Usage: pdk watchpatch  --hostname mydevserver

Generated code

Reserved sections

The workspace of a plugin generated by pdk has a code layout as in the picture below. The name of the plugin here is EC-Git.

image

Note the following pdk generated sections. Do not OVERRIDE or EDIT at any time.

  • The folders called .assets, META-INF and core (under properties/perl) in their entirety.

  • The files flowpdf.yaml, Baseplugin.groovy, form.xml (under individual procedures) and deleteConfiguration.pl in their entirety.

  • Any block of code that is in between the markers as mentioned below in any of the generated files. See first snippet below.

  • Any one line marker that are used to demarcate system generated code boundaries. See second snippet below.

## 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 ===
## === step ends ===
# Please do not remove the marker above, it is used to place new procedures into this file.

Regeneration after a spec change

This section provides information about the behavior of upon regenerating an already generated plugin after changing its specification, pluginspec.yaml. Here is a list of common scenarios of change, behavior in each scenario, and what the developer is recommended to do for it.

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 (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 folder 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 a Delete and Add. The folder 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 mentioning 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 folder is updated (form.xml). Recommended Action: No action required.

Delete procedure parameter

pdk behavior: The procedure specification in the procedure folder 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 folder is updated (form.xml). Recommended Action: Update the procedure code (in the main module) to handle the new parameter name.

New configuration parameter added/renamed/removed

pdk behavior: The form.xml of the CreateConfiguration procedure is modified. Recommended Action: No Action Required.

New REST action added to configuration

pdk behavior: The form.xml of the CreateConfiguration procedure is modified. Recommended Action: No action required.

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: No action required.

Add checkConnection to configuration

pdk behavior: If there is REST section, an auto-generated REST check connection script is added. If there is no REST section, a boilerplate step for checking connection is generated instead. Recommended Action: No action required.

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 method for the endpoint 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 accomodate 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 main module as well as in the 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 main module as well as in the 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 main module as well as in the reporting module.