Properties are a foundational feature that provides CloudBees CD with incredible flexibility.
This article provides some property storage examples. Taken from the perspective of a pipeline task, each sample syntax may or may not be useful, so this article outlines why these property types may or may not be appropriate to use from within a pipeline, and if not, where their use may be considered.
Solution
You can store a piece of data nearly anywhere in the CD system hierarchy. You should be able to retrieve such properties using a full path, a known "my" shortcut, or by knowing which related elements help identify it’s location under a common getProperty request.
Consider the following setProperty examples (relying on /my shorcut syntax):
-
ectool setProperty x1 --value 10
-
ectool setProperty /myJob/x2 --value 20
-
ectool setProperty /myProcedure/x3 --value 30
-
ectool setProperty /myTask/x4 --value 40
-
ectool setProperty /myTaskRuntime/x5 --value 50
-
ectool setProperty /myFlowRuntime/x6 --value 60
-
ectool setProperty /myStageRuntime/x7 --value 70
Each pipeline task will be launched as it’s own individual job, using a transitory procedure, with the 1 step for that procedure being the code written for the task command definition. With that in mind, let’s review how these possible property settings are stored and which syntax are appropriate from inside a pipeline task, and if not, where they would be more useful.
Less Useful Syntax inside Pipeline Tasks
x1 - a "step-level" property
-
A property usage with this syntax will be stored at the step-level
-
For a typical procedure, the direct path to this property would be: /projects/<projectName>/jobs/<jobID>/steps/<stepname>/x1
-
You could reference this property via the API using:
ectool getProperty x1 --project <projectName> --jobs <jobId> --stepName <stepName>
-
However, since a pipeline task relies on a transitory procedure run, there is no fixed access point to retrieve this property after the step has completed. As such, this is not an ideal syntax to use from inside a pipeline task.
-
Within the same step, you might later reference x1 directly using:
ectool getProperty x1
But you could more easily write your task to run under a shell or language that leverages a local variable instead. Consider, if you don’t need this property to persist beyond the task’s execution, then it is best for overall system performance not to be storing such properties inside of the database using a setProperty request. -
If this syntax were being used inside a larger procedure, where a subsequent step intends to access such a property, that step code could access this "step-level" x1 property using this shorter path syntax: /myJob/steps[<stepname>]/x1 Note that this does require the name of the step to be known, which means hard-coding a dependency you may prefer to avoid.
-
From the pipeline runtime UI, you can find this property by looking at the jobDetails for the task, selecting the Step, and clicking on the Properties tab
/myJob/x2 - a "job-level" property
-
The "myJob" shortcut will place a property at this path: /projects/<projectName>/jobs/<jobId>/x2
-
Within any step of the same job, you could find this property using this shortened syntax:
ectool getProperty /myJob/x2
-
Therefore, outside of a pipeline stage, this is a better location to store properties you intend to share within your job run than a step-level property shown above, but within a pipeline task, this still suffers from the task being launched through a transitory procedure that only has 1 step. So the use of this type of property syntax has low value for pipeline task coding
-
From the UI, you can find this value by looking at the jobDetails and clicking on the Properties tab
/myProcedure/x3 - a "procedure-level" property
-
This context is unlikely useful in a pipeline task, as the "procedure" involved would only be temporary
-
Outside of a pipeline, this syntax can be beneficial if you want to set or get data affixed to a given procedure. Examples might be where some perpetual counter is being kept for your process, or perhaps to record something like a "last-usage timestamp" or the jobId of the last time this procedure was run.
-
Outside of a pipeline task, the full path to this type of property would typically be /projects/<projectName>/procedures/<procedureName>/x3
-
From the UI, the current value using the Property Browser for the procedure, or under the "Customer Procedure Properties" section in the Commander/Platform side UI
More Useful Syntax inside Pipeline Tasks
/myTask/x4 - a "task-level" property
-
This is somewhat similar to the "procedure-level" x3, but in this case you are storing the property tied to the pipeline task instead of a procedure, and therefore, this more likely to be applicable for use within a pipeline
-
The full path to this property would be: /projects/<projectName>/pipelines/<pipelineName>/stages/<stageName>/tasks/<taskName>/x4
-
Shortcut paths to this property could be: /myTask/x4 OR /myPipeline/stages/<stageName>/tasks/<taskName>/x4
-
From the UI, you can find the current value by looking at the task definition and clicking on the property browser
/myTaskRuntime/x5 - a "task-level" runtime property
-
Any data meant to be stored during a pipeline run could use such a property.
-
The full path to this property would be: /projects/<projectName>/flowRuntimes["<Pipeline Instance name>"]/stages/<stageName>/tasks/<taskname>/x5
-
The shortcut path to referencing this property within the same task would be: /myTaskRuntime/x5
-
From the UI, you can find the current value by looking at the pipelineRun output, and clicking on the dots for the task to view the associated property
/myFlowRuntime/x6 - a pipeline runtime property
-
Any data meant to be stored during a pipeline run that is intended to be shared across tasks might use such a property, and as such, is a commonly used form of property inside a pipeline
-
The full path to this property would be: /projects/<projectName>/flowRuntimes["<Pipeline Instance name>"]/stages/<stageName>/x6
-
The shortcut path to this property would be: /myFlowRuntime/x6
-
From the UI, you can find the current value by looking at the pipelineRun output, and clicking on the dots for the stage to view the associated property.
/myStageRuntime/x7 - a pipeline stage runtime property
-
Any data meant to be stored during a pipeline run that is intended to be shared across tasks in a stage, or different stages in the same pipeline might use such a property. So this is a commonly used form of property inside a pipeline, and is not that different than using the FlowRuntime property
-
The full path to this property would be: /projects/<projectName>/flowRuntimes["<Pipeline Instance name>"]/stages/<stageName>/x7
-
The shortcut path to this property would be: /myStageRuntime/x7
-
From the UI, you can find the current value by looking at the pipelineRun output, and clicking on the dots for the stage to view the associated property
-
Currently, this property will only show the latest value, not any instances stored on a particular run of the stage involved.