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/jre

3. 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 off

Debug is disabled and logs do not get written.

Usage: flowpdk debug off

flowpdk debug purge

Debug log gets purged.

Usage: flowpdk debug off

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.

_images/plugincodelayout.png
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.