Environment Variables

Updated 4 weeks ago by Copado Solutions

Introduction

An environment variable is a container that stores strings that are unique to a specific environment, such as Salesforce ids, integration endpoints, or usernames. This feature allows you to make commits, deployments, branch validation, and Selenium test cases environment agnostic.

How Do Environment Variables Work?

Variables have a name and a value-scope, which are unique in each environment. When you commit, the value provided for the source environment when defining the variable is replaced by the variable key (value-to-key replacement). For example: 

  • {!Environment.Org_URL} ->https://copado-dev1-dev-ed.lightning.force.com/

Then, upon deployment, the variable key is replaced by the value provided for the environment which is the destination of the deployment (key-to-value replacement). For example:

  • {!Environment.Org_URL} → https://copado-uat-dev-ed.lightning.force.com/.

To guarantee a proper replacement process in all scenarios, environment variables should have unique names and values-scope. For example, there cannot be variables in the same environment with the same value and scope.

Creating an Environment Variable from a Pipeline Record

  1. Navigate to a Pipeline record.
  2. Click on the drop-down menu in the upper right corner and select Manage Environment Variables.
  3. Click on New and give your variable a name. For example, if you want to create a variable to store username values, you can name it Username:

Please note that if you want to define a scope for your variable, you need to create it from the related list in the Environment record.
  1. Once created, provide the specific values for each of the environments in the pipeline:

If you leave any of the environments empty, you won’t be able to save the variable, and an error message will be displayed.

To remove a variable from the grid, you can click on the Del link. This will result in deleting the variable in all the environments. If you add a new variable to the grid, the variable will be created in all the environments with an empty value.

You can also mass edit the grid. Once saved, all the records will be updated. The renaming of variables is fully supported.

Creating an Environment Variable in an Environment Record

  1. Navigate to the Environment Variables related list in an existing Environment record.
  2. Click on New to create a new variable:

  1. Give your variable a name, e.g., URL,  and set a value, e.g., https://copado-uat-dev-ed.lightning.force.com/.
    Please note that environment variable values do not support RegEx or the * character.
  2. The Scope field allows you to specify where a particular variable is applied. If you want the variable to be applied to all occurrences of the value across all files, you can leave this field empty. Otherwise, if you want the variable to be applied to a specific metadata type, for instance, you can use this field to define the scope of the variable.

Scope supports a serialized list of values separated by the semicolon (;) delimiter. 

The scope options are the following:

Use Case

Expression

Example

Use this expression if you want the variable to be applied to a specific metadata type

<DirectoryName>/*

objects/*

If you use this expression, the variable will be applied to a specific item within a particular metadata type

<DirectoryName/FileName.FileExtension>

object/Account.object

Custom settings: You can choose to get variables applied to all custom settings

<CustomSettingValues/*>

CustomSettingValues/*

Custom settings: You can choose to get variables applied to a specific custom setting

<CustomSettingValues/FileName.FileExtension>

CustomSettingValues/SAP_URL__c.object

Custom Labels: The variable will be applied to all components. 

Note: You cannot specify the component since custom labels are stored in a singular file.

labels/CustomLabels.labels

The variable will be applied to Apex steps

AnonymousApex/*

AnonymousApex/*

Use this expression if you want the variable to be applied to Data deployment steps

DataDeploymentStep/*

DataDeploymentStep/*

All objects and a specific apex class

object/*;classes/accountwrapper.cls

Copado enforces a constraint on environment variables with unique scope-values and its behavior is based on the following hierarchy structure:

  • If the same value is used in two different environment variables with overlapping scope, the more specific scope will win.
  • If the scope is empty for the same value in two or more environment variables, no replacement will be done. The value should be unique if no scope is defined.
  • Scope and value combination should be unique across all environment variables.

Where Are Environment Variables Applied?

Environment variables are applied automatically in the following scenarios:

  • Commits
    When performing a Git commit, Copado searches the metadata files to match environment variable values and replaces them with the corresponding key.
    E.g. Environment variable: AdminUser = admin.user.test@company.com. In the metadata files, any references to ‘admin.user.test@company.com’ would be replaced with {!Environment.AdminUser} This then allows Copado to replace other environment variables in the metadata during a deployment.

  • Git Deployments and Promotions
    When performing a deployment from Git, Copado searches the metadata files for any matching environment variable keys and replaces them with the corresponding value.
    E.g. Environment variable: AdminUser = admin.user.uat@company.com. In the metadata files, any references to {!Environment.AdminUser} would be replaced with admin.user.uat@company.com.

  • Org to Org Deployments
    When performing an org to org deployment, Copado replaces all maps from the source environment variables with the destination environment.
    E.g. Source environment variable: AdminUser = admin.user.test@company.com Destination environment variable: AdminUser = admin.user.uat@company.com. In the metadata files, Copado will replace any references to admin.user.test@company.com with admin.user.uat@company.com’.

  • Custom Setting Deployment
    When performing a custom setting deployment step, Copado searches in the custom setting fields for any matching environment variable values and replaces them with the corresponding value of the destination environment. Check out the article Custom Settings Deployment for more information.

Environment variables can also be referenced, if required, in the following scenarios:

  • Git Snapshots
    When clicking on Take Snapshot Now in a Git snapshot, a popup appears with a checkbox called Apply Environment Variables. If checked, Copado will search the metadata files during the snapshot process for any matching environment variable values and replace them with the corresponding key.
    E.g., Environment variable: AdminUser = admin.user.test@company.com In the metadata files, any references to ‘admin.user.test@company.com’ would be replaced with {!Environment.AdminUser} This then allows Copado to replace other environment variables in the metadata during a deployment.

  • Apex Anonymous Deployment Step
    When performing an Apex Class step within a deployment, Copado searches in the script for any matching environment variable keys (e.g. {!Environment.AdminUser} ) and replaces them with the corresponding value (e.g., admin.user.test@company.com). 
    E.g. Environment variable: AdminUser = admin.user.test@company.com (value in the destination environment). In the Apex Class files, any references to {!Environment.AdminUser} would be replaced with 'admin.user.test@company.com'.

  • Data Deployment Step
    You can apply environment variables to Data deployments by adding ":applyEnv=true" to the step name.


How did we do?