Output variables

Last updated

Some variables might be dynamic - for example, a value that needs to be calculated, or a value that is the output of running a command. For these scenarios, Octopus supports output variables.

Offline Package Drop
Offline drops do not support passing output variables from a deployment package step to another step as part of the same deployment script.

Output variables can be set anywhere that Octopus runs scripts - for example, the Script Console, or package scripts and script steps in a deployment. See below for examples of setting output variables in each of the different scripting languages supported by Octopus.

For example, you might have a standalone PowerShell script step called StepA that does something like this:

Set-OctopusVariable -name "TestResult" -value "Passed"
Octopus.SetVariable("TestResult", "Passed");
set_octopusvariable "TestResult" "Passed"
Octopus.setVariable "TestResult" "Passed"

You can then use the variable from other steps, either in variable binding syntax:

#{Octopus.Action[StepA].Output.TestResult}

Or other scripts:

$TestResult  = $OctopusParameters["Octopus.Action[StepA].Output.TestResult"]
var testResult = Octopus.Parameters["Octopus.Action[StepA].Output.TestResult"]
testResult = $(get_octopusvariable "Octopus.Action[StepA].Output.TestResult")
let testResult = Octopus.findVariable "Octopus.Action[StepA].Output.TestResult"

System output variables

After a step runs, Octopus captures the output variables, and keeps them for use in subsequent steps. In addition to variables that you create yourself using Set-OctopusVariable, Octopus also makes a number of built-in variables available. Here are some examples of commonly used built-in output variables:

  • For NuGet package steps:
    • Octopus.Action[StepName].Output.Package.InstallationDirectoryPath - the path that the package was deployed to
  • For manual intervention steps:
    • Octopus.Action[StepName].Output.Manual.Notes - notes entered in response to the manual step
    • Octopus.Action[StepName].Output.Manual.ResponsibleUser.Id
    • Octopus.Action[StepName].Output.Manual.ResponsibleUser.Username
    • Octopus.Action[StepName].Output.Manual.ResponsibleUser.DisplayName
    • Octopus.Action[StepName].Output.Manual.ResponsibleUser.EmailAddress

Output from multiple machines

Output variables become more complex when multiple machines are involved, but they can still be used.

Imagine that an output variable was set by a script which ran on two machines (Web01 and Web02) in parallel, and that both set it to a different value. Which value should be used in subsequent steps?

In this scenario, the following output variables would be captured:

Name Value Scope
Octopus.Action[StepA].Output[Web01].TestResult Passed
Octopus.Action[StepA].Output[Web02].TestResult Failed
Octopus.Action[StepA].Output.TestResult Passed Machine: Web01
Octopus.Action[StepA].Output.TestResult Failed Machine: Web02
Octopus.Action[StepA].Output.TestResult Passed
Octopus.Action[StepA].Output.TestResult Failed

Note that for each output variable/machine combination:

  • A variable is created with the machine name contained in the variable name: this allows you to reference output variables from set by one machine from another machine
  • A variable is created that is scoped to the machine. This way Web01 will always get the value Web01 set, and Web02 will get the value Web02 set
  • A variable is created with no scope, and no differentiator in the name. When referencing this value, the result will be indeterministic, but it allows scripts to use the value without knowing which machine set it

For some practical examples of using output variables, and how scoping rules are applied, see the following blog posts:

Setting output variables using scripts

You can set output variables using any of the scripting languages supported by Octopus. In each case we make special functions available to your scripts by bootstrapping them with a template defined in the open-source Calamari project.

PowerShell

PowerShell Bootstrapping

From a PowerShell script, you can use the PowerShell CmdLet Set-OctopusVariable to set the name and value of an output variable. The CmdLet takes two parameters:

  • [string]$name - the name you want to give the output variable following the same naming conventions used for input variables
  • [string]$value - the value you want to give the output variable

For example:

PowerShell

Set-OctopusVariable -name "TestResult" -value "Passed"

C#

ScriptCS Bootstrapping

From a C# script, you can use the public static void SetVariable(string name, string value) method to set the name and value of an output variable.

C#

Octopus.SetVariable("TestResult", "Passed");

Bash

Bash Bootstrapping

In a Bash script you can use the set_octopusvariable function to set the name and value of an output variable. This function takes two positional parameters with the same purpose as the PowerShell CmdLet.

Bash

set_octopusvariable "TestResult" "Passed"

F#

F# support is available in Octopus Deploy 3.4 (or newer).

FSharp Bootstrapping

From a F# script, you can use thesetVariable : name:string -> value:string -> unit function to collect artifacts. The function takes two parameters with the same purpose as the PowerShell CmdLet.

F#

Octopus.setVariable "TestResult" "Passed"