Configure environment variables and connection references
The solution you export from development has to work in test and production, even though each environment reaches different data through different connections. In this unit, you learn how to decide which settings belong in environment variables or connection references, choose a data type for each variable, and control which values travel with the solution.
Decide where each environment-specific setting belongs
Most of an agent stays the same as it moves from development to production. A few external references change: the site that holds a list, a limit that differs between test and production, or the credentials a connector uses. Keep these values out of the components that use them. A value hard-coded in a flow means changing the flow in every environment, which is the kind of customization outside development that your lifecycle plan rules out.
Power Platform stores these values in two kinds of solution components:
- Environment variables: An environment variable stores a key and a value that other components read as input. The variable travels in the solution, and its value can differ in each environment. One variable can serve several components, such as an agent and a flow, so updating one value updates all of them.
- Connection references: A flow in a solution binds to a connection reference instead of directly to a connection, which is the stored authentication credential for a connector. Each environment supplies its own connection, and the flow doesn't change.
A connection reference isn't a type of environment variable, but the two can work together. A connection handles only authentication. It doesn't record which site, list, or library an action uses, so an action on a connector like SharePoint needs both a connection and the site and list that the action uses. For example, suppose the HR agent's leave-balance flow reads a SharePoint list, and test and production each use their own list. A connection reference supplies the connection in each environment, and data source environment variables supply the site and the list.
Some connectors work the other way. When a connection already contains the server and database, such as a SQL Server connection that uses basic SQL authentication, those values come from the connection that the connection reference points to. Don't add environment variables for them.
Environment variables fit key-value settings that are likely to differ between environments. Relational configuration data stored in custom tables is better suited to a data migration tool, because solutions don't carry the data in Dataverse tables.
Choose a data type for each environment variable
To create an environment variable in a solution in Power Apps, select New > More > Environment variable, and then enter a display name, a unique name, and a data type. The data type determines what the value holds and which components can use it.
| Data type | Use it for |
|---|---|
| Decimal number | A numeric setting, such as a limit. |
| Text | A string, such as an address or an identifier. |
| JSON | A structured value with several properties. |
| Two options | An on or off setting. |
| Data source | A connector parameter that the connection doesn't provide, such as a SharePoint site or list. |
| Secret | A credential or key stored in Azure Key Vault. |
Two types need extra setup. A data source variable requires you to select a connector, a connection, and a parameter type. The variable uses the connection only to list the values you can choose, such as the sites you have access to, and doesn't store it.
With a secret variable, the secret itself stays in Azure Key Vault, and the variable stores a reference to its location. Flows, Copilot Studio agents, and custom connectors can use secret variables. The key vault must be in the same tenant as Power Platform and configured so that Power Platform can read the secret. Consider a separate key vault for each environment to limit the impact of a breach. Learn more in Use environment variables for Azure Key Vault secrets.
For every type, give each variable a unique display name so makers can tell variables apart, and keep values within the 2,000-character limit.
Control which values travel with the solution
An environment variable can hold two values, and the difference between them decides what arrives in each environment.
| Value | Where it's stored | When the variable uses it |
|---|---|---|
| Default value | In the variable's definition | When there's no current value |
| Current value | In a separate value record, with at most one for each definition | Whenever it exists, even if a default value is also present |
Keep current values out of the exported solution
Include the definition in your solution, and leave the current value out. Provide the value for each target environment during deployment instead. In the target environment, the definition is then part of the managed solution, and the value is an unmanaged record that belongs to that environment. Because the two are stored separately, a solution update that changes the default value doesn't overwrite the current value set in the target environment.
To keep a current value in development without exporting it:
- In the solution, select the environment variable to display its properties.
- Under Current Value, select … > Remove from this solution.
A current value that ships in a managed solution is harder to remove. To delete it, you exclude the value from the solution in development, export a new version, and import that version as an upgrade.
Supply values during deployment
When you import the solution, the import shows its environment variables:
- No default value and no current value: The import prompts for a value.
- Any other variable: The value appears prefilled, with a label that shows whether it comes from the solution, the target environment, or the default value.
Pipelines show the same values, and they validate connections and environment variables before the deployment begins.
Connection references follow a similar pattern:
- During import: You provide a connection for each connection reference, so the flows that use them can turn on automatically after the import completes.
- In a pipeline deployment: A connection reference that has no value in the solution or in the target environment can't be updated. After a deployment sets a value, you can update it in the target environment.
Check values after deployment
When a variable has no value after deployment, a notification appears. Set the value so the components that depend on the variable don't fail.
To check a value in a test or production environment, look in the Default solution, because a managed solution doesn't display the value.
Read environment variables in standard harness agent logic
On the standard harness, an agent uses environment variables the same way it uses topic, global, and system variables, except that environment variables are read-only in Copilot Studio. An administrator changes values in Power Apps. To use a variable in a Power Fx formula, add the Environment. prefix to its name. In a node such as Send a message, select Insert variable, and then select the Environment tab to choose a variable.
The published version of an agent includes the environment variable values from when you published it. After an administrator updates a value, republish each agent that uses the variable so the change takes effect at runtime. Secret variables are the exception. The agent retrieves secrets at runtime, so a changed secret doesn't require republishing. Before an agent can read a secret, the key vault must authorize Copilot Studio to use it, either for specific agents or for every agent in an environment.
Environment variable errors appear in the test chat and when you publish. They don't appear in the topic list, because environment variables aren't topic variables.
With values supplied at deployment, one managed artifact can serve test and production, and a pipeline can move it through each stage.