Continuum Plugin Arguments and Variables

Last updated
Save as PDF

Overview

Just like Tasks in Automate, Flow Plugins accept and rely upon the arguments in this article. And just like Tasks, Flow allows for variables to be defined in the arguments of a Plugin.

Just like Tasks in Automate, Flow Plugins accept and rely upon arguments, and just like Tasks, Flow allows for Variables to be defined in the arguments of a Plugin.

While the inner workings of a Plugin often vary considerably, the Flow interface to a plugin is consistent. Required (or common) arguments often have an individual field for entering a value, while all Plugins support an Additional Arguments document as a JSON formatted string.

The Basics

While a Pipeline is processing, the Workspace of the Pipeline Instance is an ever-expanding dictionary of data collected during the run. Additionally, Globals defined on the Project and Pipeline, as well as any data passed when the Pipeline was initiated, are all available for variable evaluation.

Although the implementation in Automate is a little more robust, the basics for referencing variables here may be useful.

Basic variable escape syntax is a variable name enclosed in the following brace format:

[$ variable $]

Wait! This Causes an Error in my Plugin!

Since Additional Arguments are in JSON format, the document is subject to syntax validation. In cases where the variable would replace with something other than a string, such as an array or object within the structure of the JSON, the JSON becomes invalid. For example:

{
    "params": [$ globals["foo"] $]
}

This is invalid JSON and won't be accepted by the Stage editor!

Not to worry. Data can also be referenced using a JSON-friendly syntax as follows:

{
    "params": {
        "Ref": "globals["foo"]"
    }
}

When used this way, the entire subsection will be replaced with the found value, and this syntax passes JSON validation.

In the Workspace document, the globals section is defined on the Pipeline Definition, whereas globals defined on a Project Definition are available in the projectglobals section.

"Phase Data"

The phasedata section of the Pipeline Instance Workspace is an internal storage mechanism, segregating information generated by plugins into a unique location depending on their order in the pipeline flow.

Here's an example of a phasedata section:

"phasedata": {
    "build phase": {
        "jenkins build stage": {
            "0": {
                "build": 250
            }
        }
    }
}

Due to the dynamic nature of Pipelines using a multitude of plugins, and the scope of what different plugins can to, the methods of accessing the results of a plugin may vary. Consult the specific plugin documentation for more details.

Constants

Constants are very special, as they can be placed anywhere in a value, either inside or outside
a [$ variable $]. Constants are replaced before variables are evaluated, so in most cases they are used to enable 'dynamic' variables.

Constants are most helpful - in fact essentially required - to access dynamically created data in the phasedata section of the Workspace.

__PIID - ID of the current Pipeline Instance
__PINAME - Name of the current Pipeline Instance
__PINUMBER - The auto-incrementing Instance number. (Ascending within a Group.)
__PIURL - The url to the pipeline instance page within Continuum
__CONTINUUMURL - The base url the Continuum webserver
__PHASENAME - Name of the current Phase
__STAGENAME - Name of the current Stage
__STEPNUM - Current Step number (0 based)
__PROJECTID - ID of the current Project
__PROJECTNAME - Name of the current Project
__PROJECTVERSION - Version of the current Project
__DEFINITIONID - ID of the Pipeline Definition
__DEFINITIONNAME - Name of the Pipeline Definition
__GROUP - Group of the current Pipeline Instance
__CHANGECOUNT - Number of Changes on the Manifest of the Pipeline Instance
__WORKITEMCOUNT - Number of Workitems on the Manifest of the Pipeline Instance
__DURATION - Duration so far of the Pipeline Instance
__EPOCH - Integer timestamp of the current time
__UTCNOW - UTC timestamp of the current time
__LOCALNOW - Localized timestamp of the Continuum server

The following shorthand constants are also available:

__FIRSTSTEPNUM - Replaces with 0, (So you don't have to remember Steps are zero-based!)
__PREVSTEPNUM - Equivalent to __STEPNUM - 1

Finally, these shorthands replace with a value that includes the phasedata evaluation. Therefore, these should always be used inside variable brackets.

__STEPDATA - Shorthand for phasedata['__PHASENAME']['__STAGENAME']['__STEPNUM']
__STAGEDATA - Shorthand for phasedata['__PHASENAME']['__STAGENAME'] to reference any Step explicitly
__PHASEDATA - Shorthand for phasedata['__PHASENAME'] to reference any Stage explicitly
__FIRSTSTEPDATA - Shorthand for phasedata['__PHASENAME']['__STAGENAME']['__FIRSTSTEPNUM'] to reference data in the first Step
__PREVSTEPDATA - Shorthand for phasedata['__PHASENAME']['__STAGENAME']['__PREVSTEPNUM'] to reference data in the previous Step

Remember, Stages run in parallel, that's why there is no such thing as FIRSTSTAGE or PREVSTAGE.

Viewing the Workspace

Usually, the best way to determine how to access data, and what data is actually available, is to simply inspect the Workspace. While developing a pipeline, you'll be going through iterations of - add a step, initiate, analyze, repeat. On the Pipeline Instance details page, the Workspace tab shows the entire workspace document. Everything in the workspace is available for variable evaluation!

Staying Sane

While a Pipeline is active, the Workspace is an ever-changing document. Also, since each Pipeline is completly custom, every Workspace is different. It's easy to fall into the trap of trying to figure out brute force ways to access "the data from the second stage in the first phase" or other extremely complex mappings.

If your find yourself in this quandry, take a step back and remember the phasedata section is purposefully and intentially very rigid, and therefore yes, it's a little difficult to get at data from previous Phases, Stages or Steps.

That's why many Plugins have the ability to write relevant data to another location in the Workspace... so you will know exactly where to look!

If the plugin in question doesn't have this option, you can always fall back on the Flow - Set Data function, which allows you to take any data evaluation and copy it to another more easily accessible location.

For example:

A stage in the first phase calls your Jenkins 'compile' job.
That data will be available as: [$ __STEPDATA['build'] $]

But way later in the pipeline, you can't easily say [$ phasedata['My First Phase']['Some Stage']['2']['build'] $] to reference that build number. Phase name, Stage names and Step ordering may evolve and should never be hardcoded into your logic.

The better approach is, immediately following your 'compile' job:

Use Flow - Set Data to put the result of [$ __STEPDATA['build'] $] in a Workspace key my_compile_buildnumber.
Now, anywhere in the rest of the whole pipeline, you can easily reference [$ my_compile_buildnumber $].

It's your data. Don't go crazy trying to access it, rather stick it right where you want it!