############### Plugin Concepts ############### Terminology ############ Plugin Code Layout ================== Refers to organizing the different parts required to build a plugin as follows during Developer Design Time. * Meta data file that contains Plugin specific name, version and description. * Meta data file that contains Procedure related parameters and UI related form elements. * Procedure code implementation. * Third Party Libraries. * Promotion scripts. * Setup scripts that go hand in hand with promotion. * Help File Documentation. * plugin icon. Plugin Build ============= Refers to the process of building a plugin the output of which is a zip file. Plugin Provisioning and Install =============================== Refers to the process of exploding the zip file of the plugin on the server, including the expansion and merge of plugin metadata into an object structure in the file system and applying as an import to the Flow RDBMS. After this step the plugin is still not usable until it is promoted. Plugin Promotion ================ Refers to the process of promoting a plugin version so it is usable, which among other things could include the import of the object structure created in install into the RDBMS and the creation of a Plugin Project whose name is a concatenation of the Plugin Key (a plugin's unique identifier) and the version of the Plugin. Where warranted (for example where there are no version conficts), install is automatically followed by the promotion process. After this step the plugin is still not usable until it is configured, with the exception of plugins that do not have a configuration procedure defined. Since flow supports more than one version of a plugin to exist in the system, the logic for install/promotion is covered in a separate section below. Plugin Configuration ==================== Refers to the process of setting up the plugin configuration procedure so it can be used. After this step the plugin is usable provided the integration with the third party does not expect the third party software to be co-located on the Agent machine. Otherwise the agent setup below should be performed. The point to note is that after a Plugin Configuration has been performed it does not mean the plugin is necessarily usable (see Agent Setup). Plugin Agent Setup =================== Refers to the process of making sure that the Flow Agent is co-located with the Third Party software, where this is warranted. For example a plugin that is implemented using a Rest API integration with the Third Party does not require this setup, whereas a plugin that is implemented using a CLI integration might. In addition the agent resource information which runs the commands in the procedure step, should be registered in the Flow server. Plugin Runtime Shell ==================== Refers to the program that executes the commands in a procedure step, on the Flow Agent. Typically the commands are in a scripting language and the Shell an interpreter that can execute that language. In this sense the Runtime Shell ties back to a programming language. Currently there are 2 runtime shells supported for plugins - ec-perl and ec-groovy. Plugin Publish to Catalog ========================== Refers to an internal process in CloudBees Flow where a tested plugin gets published to a Catalog. After being published, a plugin can be downloaded directly from a website or using the "View Catalog" functionality in the CloudBees Flow. Concepts ######### Plugin Metadata ================== The following snippet from plugin.xml provides the salient metadata of a plugin that pertains to its identity, compatibility with Flow versions and its support level. Note the following: * The plugin key represents a **unique system identifier** which is used internally by Build, Install and Promotion Processes. * The plugin label represents the user friendly name of the plugin key that can be typically used in a UI. It has the flexibility to be changed. * The @ symbols provided here are wild cards which get resolved when the plugin gets built. .. code:: xml @PLUGIN_KEY@ @PLUGIN_VERSION@ WebLogic Application Server configurations.xml EC-WebLogic_help.xml CloudBees http://www.electric-cloud.com/support Application Server war/ecplugins.weblogic.ConfigurationManagement/ecplugins.weblogic.ConfigurationManagement.nocache.js Plugin Versioning ================= Plugins use a version nomenclature of the form X.Y.Z.W and as follows: * X — Major version, Y — Minor version, Z — Patch version, W — Build version. * Major releases normally include significant new features, support only a certain version of CloudBees Flow or have changes that are **not backwards compatible** . * Minor releases may include fixes and new features. * Patch (Maintenance) releases will only include bug fixes. * Build version basically increments the counter for a given Major, Minor and Patch version, during the development cycle as new builds get created. Install and Promotion Logic =========================== Plugin Versions play an important role in the installation and promotion of a plugin version. These are general principles that govern promotion of a plugin version. * A plugin with either a Higher Major or Minor version (than an already existing plugin) will be installed but not promoted. * A plugin with Higher Patch version and the same Major and Minor version (as an already existing plugin) will get installed and promoted, after uninstalling the existing plugin. * A plugin with Higher Build version and the same Major, Minor and Patch version (as an already existing plugin) will get installed and promoted, after uninstalling the existing plugin. The following table is provided for further clarity. Assume the following: * A = X.Y.Z.W = Version of **Existing Plugin** in the System. * B = X1.Y1.Z1.W1 = Version of **Plugin to be installed**. ================================= ========================= CASES OUTCOME ================================= ========================= X1 > X B will be Installed, Not promoted. A will exist and not be overwritten. A will remain as the active version, until demoted and B is promoted. X1 = X and Y1 > Y Same as above. X1 = X, Y1 = Y and Z1 > Z A will be uninstalled. B will be installed and promoted. X1 = X, Y1 = Y, Z1 = Z and W1 > W Same as above. ================================= ========================= Architecture ############## Content ======== A Plugin is characterized by its metadata and by the Flow project that encapsulates its features and exposes them as Procedures. The plugin project is like a Flow project, but whose name is suffixed by the version of the plugin. .. image:: images/plugin-characteristics.png :align: left Install ======= The diagram below represents the details of what happens in a plugin install. The key point to note is that the install entails uploading all objects required at runtime, to the RDBMS or the Filesystem as required. .. image:: images/plugin-install-process.png :align: left Promotion ========= The diagrams below represents what a plugin promotion entails. The key point is that only one version of a plugin can be active/functional at a time. The first diagram, shows an upgrade, where in a Higher Version gets promoted, after the lower version is demoted. The second diagram shows a downgrade, where in a Lower Version gets promoted, after the higher version gets demoted. Note that the downgrade scenario in the second diagram is typically performed manually where such a situation is warranted. .. image:: images/plugin-upgrade.png :align: left .. image:: images/plugin-downgrade.png :align: left Procedure Structure =================== A Plugin procedure consists of one or more steps, each executing on a flow agent (aka agent resource). Where necessary different steps can run on different agents. .. image:: images/plugin-structure.png :align: left Procedure Step Execution ======================== The diagram below represents the typical flow of execution in a plugin. There are 2 key points to note: * The various parameter values at runtime required by a procedure step can come from anywhere in the execution Hierarchy. * The Framework provides the APIs required to perform all the operations mentioned below. .. image:: images/plugin-execution.png :align: left