pdk Tool¶
Setup¶
Go through the following steps to set up your pdk environment.
1. Download pdk CLI from the link provided in the GitHub Public Repository for flowpdf. 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.
vagrant@commander5:/vagrant/plugindevguide$ 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/jre3. In order to use pdk set the PATH to include it. For instance,
vagrant@commander5:/vagrant/plugindevguide/docs$ 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¶
config¶
Used to configure the pdk utility for general purpose defaults - Plugin Author, Support URL etc.,
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¶
Used to show the various dependencies and their versions of pdk. This is typically used.
debug¶
Used to 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 $HOME/.flowpdf directory.
cookie-cutter¶
Used to manage Process as Code projects. This command should run from a project root (the folder that contains project.dsl file in it).
Generic Switches¶
The help switch provides the help at any level of the hierarchy. Here are some examples. The short form -h provides the same output.
vagrant@commander5:/vagrant/framework/doc/pdk/bin$ 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.
vagrant@commander5:/vagrant/framework/doc/pdk/bin$ pdk config setoption --help
Usage: pdk config setoption [-h] [-v]... optionName optionValue
Description: Set a specific configuration option
optionName Option name
optionValue Option value
The version switch provides miscellaneous version information about pdk. The short form -v provides the same output.
vagrant@commander5:/vagrant/framework/doc/pdk/bin$ 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¶
This command 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¶
This command shows the value of each of the configured items.
Usage: pdk config show
debugOn: false
verbosity: 2
pdk config setoption¶
This command is used to set the value of each item.
Usage: pdk config setoption <optionName> <optionValue>
pdk config setoption pluginAuthor "James Doe"
pdk generate¶
The pdk generate supports the following subcommands. ‘pdk generate’ 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 will be created under X. Similarly if you want to generate plugin EC-Myplugin, ‘pdk generate plugin’ should be executed from the directory EC-MyPlugin.
Usage 1: pdk generate workspace
Usage 2: pdk generate plugin
pdk generate workspace¶
This command 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:
- choose default if you want to start on a simple template. This will generate a sample procedure section in the pluginspec.
- choose rest if you want to build a rest plugin. This will generate a sample rest based procedure section in the plugin spec.
- choose reporting if you want a plugin that interfaces with Third Party to bring in data for Reporting Purposes. This will generate a reporting section in the pluginspec.
pdk generate plugin¶
This command 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. This command 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¶
Produce a list of fields available in the pluginspec and their description.
Usage : pdk showdoc pluginspec
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 pdk utility with required verbosity where appropriate.
pdk debug on¶
Debug is enabled and logs will be written to a log file called pdk.log under the pdk/bin directory. Default is lowest verbosity.
Usage: pdk debug on
pdk debug setverbosity¶
Set the verbosity level of debug log to one of info|debug|trace.
Usage: pdk debug setverbosity
pdk debug setverbosity trace
pdk debug check¶
Returns detailed information about pdk (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 pdk desc.
Usage: pdk debug check
pdk cookie-cutter¶
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 file is located). After the command runs for the first time, it saved the timestamp in the state, and uses this timestamp to determine which files were updated. The next runs will apply changes only from updated files.
The command is using session saved by ectool login command, please execute it before running the command or provide COMMANDER_SESSIONID environment variable.
Usage: pdk cc --hostname <myserver>
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 CB-Git.
- The developer should note the following pdk generated sections. These should not be OVERRIDDEN or EDITED 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 is 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 pdk upon regenerating an already generated plugin after changing its spec (i.e., pluginspec.yaml). Here is a list of common scenarios of change, pdk 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 accomodate the new parameter.
Recommended Action
Change the method call in the main module to accomodate the new parameter.
Parameter removed from restclient Section endpoint¶
pdk behavior
The method for the endpoint is regenerated in the REST client to accomodate the updated set of parameters.
Recommended Action
Change the method call in the main module to accomodate 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 (aka Reporting module) 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.