flowpdk Tool¶
Setup¶
Go through the following steps to set up your flowpdk environment.
1. Download flowpdk 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. flowpdk 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 flowpdk 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/flowpdk/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:
flowpdk (CLI)
flowpdk config (config command)
flowpdk config listoptions (config with listoptions as a subcommand)
Top Level Commands¶
config¶
Used to configure the flowpdk 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 flowpdk. This is typically used
debug¶
Used to Turn on/off/purge logs written by the flowpdk utility with required verbosity where appropriate. When debug is enabled logs will be written to a log file called flowpdk.log under the flowpdk/bin directory
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/flowpdk/bin$ flowpdk --help
Usage: flowpdk [-hv] [COMMAND]
Commands:
config Configure the flowpdk 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 flowpdk spec which contains its dependencies
debug Turn on/off/purge logs written by the flowpdk utility with required verbosity where
appropriate. When debug is enabled logs will be written to a log file called flowpdk.
log under the flowpdk/bin directory.
vagrant@commander5:/vagrant/framework/doc/flowpdk/bin$ flowpdk config setoption --help
Usage: flowpdk 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 flowpdk. The short form -v provides the same output.
vagrant@commander5:/vagrant/framework/doc/flowpdk/bin$ flowpdk --version
flowpdk 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¶
flowpdk config¶
This command supports the following subcommands.
listoptions List available configuration options
show Show currently saved configuration
setoption Set a specific configuration option
flowpdk config listoptions¶
This command lists items that can be configured for the flowpdk as a one time setup.
Usage: flowpdk 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.
flowpdk config show¶
This command shows the value of each of the configured items.
Usage: flowpdk config show
debugOn: false
verbosity: 2
flowpdk config setoption¶
This command is used to set the value of each item.
Usage: flowpdk config setoption <optionName> <optionValue>
flowpdk config setoption pluginAuthor "James Doe"
flowpdk generate¶
The flowpdk generate supports the following subcommands. ‘flowpdk generate’ is sensitive to the directory from which it is executed. For example if you execute ‘flowpdk 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, ‘flowpdk generate plugin’ should be executed from the directory EC-MyPlugin.
Usage 1: flowpdk generate workspace
Usage 2: flowpdk generate plugin
flowpdk 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: flowpdk generate workspace
Usage 2: flowpdk 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.
flowpdk generate plugin¶
This command generates a plugin in the workspace using the spec defined in pluginspec.yaml.
Usage: flowpdk 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.
flowpdk build¶
This command builds a plugin. This command should be executed from the root directory of the plugin workspace.
Usage: flowpdk build plugin
flowpdk showdoc¶
This command is used to show documentation corresponding to various aspects of flowpdk.
flowpdk showdoc pluginspec¶
Produce a list of fields available in the pluginspec and their description.
Usage : flowpdk showdoc pluginspec
flowpdk showdoc toolkit¶
Show the full help for flowpdk utility in one page.
Usage: flowpdk showdoc toolkit
flowpdk describe¶
Show the version of all the dependencies of flowpdk.
Usage: flowpdk describe
Layout version: 1.0.10
Language core perl version: 1.1.11
flowpdk debug¶
This command is used to manage the creation of logs written by the flowpdk utility with required verbosity where appropriate.
flowpdk debug on¶
Debug is enabled and logs will be written to a log file called flowpdk.log under the flowpdk/bin directory. Default is lowest verbosity.
Usage: flowpdk debug on
flowpdk debug setverbosity¶
Set the verbosity level of debug log to one of info|debug|trace.
Usage: flowpdk debug setverbosity
flowpdk debug setverbosity trace
flowpdk debug check¶
Returns detailed information about flowpdk (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 flowpdk desc.
Usage: flowpdk debug check
Generated Code¶
Reserved Sections¶
The workspace of a plugin generated by flowpdk has a code layout as in the picture below. The name of the plugin here is CB-Git.

- The developer should note the following flowpdk 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 flowpdk upon regenerating an already generated plugin after changing its spec (i.e., pluginspec.yaml). Here is a list of common scenarios of change, flowpdk behavior in each scenario and what the developer is recommended to do for it.
Add a new Procedure¶
flowpdk 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¶
flowpdk 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¶
flowpdk 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¶
flowpdk 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¶
flowpdk behavior
The procedure specification in the procedure folder is updated (form.xml).
Recommended Action
No action required.
Delete Procedure Parameter¶
flowpdk 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¶
flowpdk 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¶
flowpdk behavior
The form.xml of the CreateConfiguration procedure is modified.
Recommended Action
No Action Required.
New REST action added to Configuration¶
flowpdk behavior
The form.xml of the CreateConfiguration procedure is modified.
Recommended Action
No Action Required.
New REST based Auth Scheme in Configuration¶
flowpdk behavior
The form.xml of the CreateConfiguration procedure is modified according to the REST layout.
Recommended Action
No Action Required.
Add checkConnection to Configuration¶
flowpdk 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¶
flowpdk 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¶
flowpdk 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¶
flowpdk 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¶
flowpdk 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¶
flowpdk 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¶
flowpdk 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¶
flowpdk 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¶
flowpdk 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¶
flowpdk 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.