Continuum Plugin Arguments and Variables
Overview
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 with0
, (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 forphasedata['__PHASENAME']['__STAGENAME']['__STEPNUM']
__STAGEDATA
- Shorthand forphasedata['__PHASENAME']['__STAGENAME']
to reference any Step explicitly__PHASEDATA
- Shorthand forphasedata['__PHASENAME']
to reference any Stage explicitly__FIRSTSTEPDATA
- Shorthand forphasedata['__PHASENAME']['__STAGENAME']['__FIRSTSTEPNUM']
to reference data in the first Step__PREVSTEPDATA
- Shorthand forphasedata['__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 keymy_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!