Current limitations and requirements
You will need to have an Enterprise license to use this feature.
Using environment variables allows people with information in their metadata that's specific to one org to keep it that way during a deployment. For example, the email address
[email protected] might exist in a dev org, but it should be
[email protected] in a production org. Or, you might want different IP address ranges in your metadata, depending on whether the metadata is in a dev or production org. Previously, this would need to be a manual change after the deployment, but environment variables allow the user to define where they want changes to be made, what value to find, and what to replace it with. This feature applies to both manual deployments and continuous integration deployments, and for deployments to orgs or source control.
To configure environment variables, go to the My Account section, then find Environment variables on the left-hand side. There will be a dropdown to select the target org, along with tables of existing environment variables you have access to.
A concrete example of this could be replacing the Login IP Ranges in the Admin Profile Metadata. If the dev admin IP range was
100.100.100.100 and the prod admin IP range was
188.8.131.52, then an environment variable could be created with the prod org as a target. You must be the owner of an org connection to add or edit an environment variable with that connection as the target. We would set this up by doing the following:
Choose your target org connection from the dropdown menu and click "Add Target". (Notice that two different users' connections to the same org are considered distinct org connections.)
Select the Metadata "Profile" and Item "Admin" from the respective dropdown menus. Note that you can only select a Field for specific metadata types like "Custom Metadata" and "Remote Site Settings". By default, the environment variable will be applied to the whole item.
For each replacement that you want to make, type in the value to find and the value to replace with, and click "Add Environment Variable".
Each variable will display in a list below the environment variable addition options. These can be deleted by clicking the red bin icon next to their entry. Note that you cannot create conflicting entries (i.e. variables that have the same target value to find in the same metadata type and item).
You can also choose "Any item" instead of an item name to perform the replacement on all instances of the chosen metadata type. Please note that you cannot modify XML tags within metadata using this feature, only the properties encompassed by the tags. For example, you cannot find and replace
<value>SomeStringHere</value>. Instead, you would have to find
SomeStringHere without the surrounding tags.
Once your environment variables are configured, they will automatically be used in any deployment (manual and CI) that has the chosen target org connection*, even if the connection is a delegated connection, so long as the metadata item they are configured for is selected as part of the deployment. For instance, in the example above, the Admin Profile would need to be selected as part of the deployment package in order for the environment variable replacing the login IP ranges to take effect.
*Please note that two connection with different usernames that connect the same organization are treated as different org connections.
While only the owner of the target environment can create or edit environment variables on that environment, any user in the team who either owns or has delegated access to the connection to the target org can use its environment variables.
For manual deployments, the environment variables that will be applied to a deployment can be viewed in the Problem Analysis and Environment Variables screen, as shown below:
You can check the result of the replacement by downloading the deployment ZIP file at the deployment summary stage. Once you've confirmed the variables are being applied as intended, proceed as normal, and the replacements will be made during the deployment.