Chapters

ScopingScoping rulesResolving valuesReferencing variablesDebuggingOuptut variables

Variables

Note: this article often mentions "Machine or Cloud Target" as a single type of entity. Even if there is a difference between these two, it is only about their interface used during actual deployments. This diversity is irrelevant in this article. Think of Machines and Cloud Targets as two entities which behave in the same way when designing a deployment flow and resolving variable values.

Variables are one of the core feature of Jaws Deploy. Using variables you can:

  • use exactly the same deployment process across all environments and deployment targets - parametrize the process with variables and let Jaws Deploy automatically apply required variable values
  • avoid hardcoded configuration parameters
  • transform configuration files depending on current environment and deployment target
  • parametrize any custom logic contained in your deployment flow

Scoping

Variables are by design multi-valued entities. This means a single variable represents multiple values, which are different depending on what is the current deployment context.

Basic example: you can create a variable named InstallationDirectory with 2 values:

  • C:\deployments\myApp when deploying to Staging environment
  • /opt/myApp when deploying to Production environment

This makes deployment flow flexible. You specify your deployment logic once, parametrize it depending on the context and let Jaws Deploy do the heavy lifting of resolving proper variable values.
‍
The above example illustrates how variable scoping works - it controls the value of a variable based on current deployment context. The deployment context is simply the current machine or cloud target we're deploying to. Machines and cloud targets have assigned environments and (optionally) tags, which together make the entire deployment context. Refer to our core concepts article to learn more about machines, cloud targets, tags and environments. With the context known Jaws Deploy determines appropriate variable value to use.

To sum it up - a variable value may be scoped using following attributes:

  • environment (typical use-case)
  • tags
  • specific machine
  • specific cloud target

Scoping rules

If a variable scope has multiple attributes specified (e.g. one environment and two tags) then applying it to a certain deployment context may require additional rules. This can happen when a specific deployment context matches more than one variable value of a single variable. In such case Jaws Deploy need to decide on precedence of scoping or scoping strength.

In short: variable values with the most complex scope are chosen over values with simpler scope (if more than one value matches current context).

What does more complex scope mean? It is the combined amount and importance of attributes of a scoped value. If you use multiple attributes on a variable value - their importance sums up. The attributes importance is ordered in the following way:

  • Specific Cloud Target or Machine (most important)
  • Tag
  • Environment (least important)

Values scoped to multiple attributes will have the following strength:

  • Environment + Machine/CloudTarget (strongest)
  • Machine/CloudTarget
  • Environment + Tag
  • Tag
  • Environment

Note: it is not really practical to combine (machine + tag) in a variable value scope. Think of tags as groups of machines. Since you specified a machine on a variable value - adding one of the machine tags makes no difference. And adding a tag that does not exist on this machine makes the value never being selected.

Let's make this clear with an example based on the previously mentioned variable InstallationDirectory. Suppose you have a project with:
- 2 environments (Staging and Production)
- 1 machine in Staging (StagingServer)
- 3 machines in Production (ProdServer01, 02 and 03)
Also let's assume one of the machines in Production (ProdServer03) requires a different value of InstallationDirectory.
Here is how you would set up variable values scopes:

  • { value : 'C:\deployments\myAppStaging', scope : { Environment: [ 'Staging' ] } }
  • { value : 'C:\deployments\myAppProd', scope : { Environment: [ 'Production' ] } }
  • { value : 'C:\deployments\myAppProd_Custom', scope : { Machine: [ 'ProdServer03' ] } }

Note the following facts:

  • When deploying to any Staging server the value no. 1 is taken due to Environment match.
  • When deploying to any Production server (other than ProdServer03) value no. 2 is taken due to environment match.
  • When deploying to ProdServer03 then value no. 3 is taken. The reason is that Machine sopcing streangth is higher than Environment scoping strength. Jaws Deploy will start with matching both vales 2 and 3 for ProdServer03, but only one value can win, and here the value with higher scoping strength is chosen.
  • if you added 2 values that have the same scoping strength (e.g. Production+myCustomTag) then Jaws Deploy will throw an error during deployment. There will be 2 matching values with the same strength and there is no other way to decide which should be picked. Deployment cannot proceed as picking an arbitrary value might have severe consequences. Configure variable scopes carefully.
  • If you now added a 3rd environment (e.g. UAT) and also a new machine called UatServer, and then deployed the app to UatServer - no value will match for InstallationDirectory variable. Reason is that all values specified above have scopes that do not overlap with UatServer or its environment.

Resolving a value with multiple attributes

If there is a variable value scoped to multiple attributes then the logic combines all values using AND operator between different attributes and OR operator between vlaues of a single attribute.
Example:

{ value = "test", scope = { Environment: ['Staging', 'UAT'], Tag : ['tag_A', 'tag_B'] }

Jaws Deploy engine will use the following logic to determine if a specific deployment context matches this value:

( context.Environment == 'Staging' OR context.Environment == 'Production' )
AND
(context.Tags.Contains('tag_A') OR context.Tags.Contains('tag_B') )

Note that current context is determined by the machine we're deploying to, and a machine may have multiple tags assigned, hence the context.Tags.Contains logic.

Referencing variables

Deployment steps

Every deployment step is based on a step template, which includes a GUI JSON definition. Jaws Deploy renders it when you're editing a project step in the app UI. All step-template-based text inputs in this UI allow you to use variables using the following syntax:

#{VAR.variable_name}

Example:

Deployment scripts

Every PowerShell deployment script has access to a broad set of context values, including variables (which values are already resolved depending on current deployment context). Reference variables using the following syntax:

$Jaws.Parameters["VAR.variable_name"].Value

Example:

Nesting variable values

When editing workspace or project variables it is possible to nest variable values one inside another. The values will be resolved based on the deployment context as usual. Use the following syntax:

#{VAR.variable_name}

Example:

Debugging variable values

If you need to debug variable values or scoping rules you can add a special variable to your project:
- variable type: Boolean
- variable name: __debug
- variable value: true

Once this variable is added create a new release (keep in mind changes to variables always require creating a release) and run a deployment. The deployment log will include entire context for every step and every machine (note Install path and __debug variables):

9:19:40 PM [Debug] Starting remote step runner
9:19:40 PM [Information] Skipping package upload - no packages to upload
9:19:40 PM [Information] Preparing script to be executed on agent 1d1b94ae-1ca2-4780-8d70-8af7b7080e31 / Web server EU 001
9:19:47 PM [Debug] Running script
9:19:47 PM [Debug] =============================================Script context dump - agent
---------------------------------------------Parameters:
CONTEXT.CurrentStep.Index: [Number] 1
CONTEXT.CurrentStep.Skipped: [Boolean] False
CONTEXT.CurrentStep.StepId: [Text] 054a71b9-4235-4e9f-9a5b-375fdbca1e98
CONTEXT.CurrentStep.StepName: [Text] Prepare deployment environment
CONTEXT.DeploymentDate: [Date] 07/21/2025 19:19:40
CONTEXT.DeploymentId: [Text] ce8a62e1-75c4-46a2-98a5-63973d5ab1ea
CONTEXT.EnvironmentId: [Text] 4d7d330d-4876-437c-852f-3d75c2be243f
CONTEXT.EnvironmentName: [Text] Staging
CONTEXT.MachineId: [Text] 1d1b94ae-1ca2-4780-8d70-8af7b7080e31
CONTEXT.MachineName: [Text] Web server EU 001
CONTEXT.ProjectId: [Text] 139828d9-b8a6-4c92-b3d4-ca725d7e786d
CONTEXT.ProjectName: [Text] Onyx Web Api
CONTEXT.ReleaseVersion: [Text] 0.0.16
STEP.ScriptBody: [Script] Write-Host "Starting logic..."
VAR.Install path: [Text] /opt/web/onyx
VAR.__debug: [Boolean] True

Output variables

Output variables allow you to carry values computed in a deployment step over to other steps in the same run. This is achieved using the built-in PowerShell function:

function Set-JawsOutputValue {  
param (
[Parameter(Mandatory)] [string] $Name,
[Parameter(Mandatory)] [object] $Value,
[jawsdeploy.common.Scripting.VariableType] $Type = [jawsdeploy.common.Scripting.VariableType]::Text,
[jawsdeploy.common.Scripting.VariableOutputScope] $Scope = [jawsdeploy.common.Scripting.VariableOutputScope]::Machine
)
... }

Note that PowerShell is based on .NET which allows strong-typing of variables, which is covered by this function. If you don't want to rely on variable types just leave the default (Text). All available types are:

Text, Number, Secret, Boolean, Date, Map

Possible values for $Scope are (explained later in the examples below):

Machine, Global

Here is how you can use it within a deployment step script (assuming type of the variable is the default text and scope is Machine):

$myValue = "Custom value to use in next deployment steps"
Set-JawsOutputValue -Name "myOutputValue" -Value $myValue

The above call creates variable named myOutputValue, of type Text and scope equal to Machine. This scope means that the output variable will be named after the current machine that runs this code (which implies that running this stepo on multiple machines will create multiple variables, each named after the machine). Variable name will also include the step name, which allows having same variable applied to context in different deployment steps, without overwriting the value. How to access this variable value created on machine named "ProdServer01":

$Jaws.Parameters["OUTPUT.Step.Step name.ProdServer01.myOutputValue"].Value

Assume now every machine produces own unique value for this variable, and in next step you'd like to access the value created on the same machine that is running currently (in other words: carry over the variable value and maintain machine context). In such case reference the variable value using special machine name: ThisMachine. Jaws Deploy will make sure the value referenced via this special name is synchronized to the current machine. E.g.: if there are 2 machines, ProdServer01 producing value X and ProdServer02 producing value Y, then in the next step a value referenced by ThisMachine will be X when called on ProdServer01 and Y when called on ProdServer02. PowerShell code snippet:

$Jaws.Parameters["OUTPUT.Step.Step name.ThisMachine.myOutputValue"].Value

The other scope value Global allows you to create variable values which are the same for all machines. Create and read the value using the following code:

# create
$myValue = "Custom value to use in next deployment steps"
Set-JawsOutputValue -Name "myOutputValue" -Value $myValue -Scope [jawsdeploy.common.Scripting.VariableOutputScope]::Global

# access in next deployment steps
$Jaws.Parameters["OUTPUT.Step.StepName.Global.myOutputValue"].Value