############# 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 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=] [--description=] [--plugin-name=] [--author=] [--support-url=] 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. .. image:: images/plugincodelayout.png :align: center 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). .. code:: perl ## 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 === .. code:: perl ## === 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 /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.