Environment variables available in preview!

Applications and Flows often require different configuration settings across environments. Today we’re excited to announce the ability to transport your application configuration data from one environment to another with solutions! Historically, configuration data was stored in custom entities as record data and required various tools such as the configuration migration utility to migrate. While such tools still serve valid use cases, Environment variables offer a streamlined way to transport key-value pairs in a solution. Because they’re solution components, they can be managed in source control along with your other customizations. As an added benefit, performance is much better than using data import.

At the time of this posting, Environment variables may not be available in all regions. 

When should I use Environment variables today?

The initial preview is targeted primarily for professional developers and administrators. You can still make use of them in canvas apps and flows today, however, these citizen developer experiences will become much simpler as we develop new interfaces.

Some examples include:

• When an input parameter needs to change across environments and should not be hard-coded. For example, a URL that points to a different resource in development and production environments.
• If you’re building a solution where your customer is required to provide an input value.
• Application setup pages.
• When multiple components require the same input. Instead of entering that input multiple times, reference the environment variable. If the value needs to change, make an update in one place.
• If you need to update configuration values without modifying code or if the person managing the configuration is not familiar with coding. For example, a plugin that references a blob store location could be updating without directly modifying the plugin.

What does the road map look like?

The next step is for native integrations within canvas apps, flow, and custom connectors. For example, use an environment variable to store the SharePoint site URL and list. Those components would simply reference the environment variable instead of being written to the component directly. Values can then change from environment to environment or even within the same environment without editing the referencing component. Or you could define an environment variable and have a simple mechanism to reuse it in multiple steps or components. We have other ambitions as well, which will be communicated in the future.

When shouldn’t I use Environment variables?

• To transport secure data such as passwords or other secrets.
• If several values are required for one definition.
• When relationships need to be formed between configuration entities and entities for record data. Environment variables are best suited for key-value pairs and new relationships cannot be created.

How they work

Environment variables can be managed through the modern solution interface or through code. A separate JSON file is created within your solution package, which can also be managed in source control. We also support export to Excel from a model-driven app. After creating Environment variables in Common Data Service for apps,  you can consume them by retrieving data from the Environment Variable Definition and Environment Variable Value entities. To fetch a specific value, you can query by the ‘SchemName’ as that is constant across environments.

Default value

This field is part of the Environment variable definition entity is not required. Set a default value for the value to be used in production or when the values should remain the same across different environments. The Environment variable definition will be represented in the customizations.xml in your solution file.

Value

This field is optional and is a part of the “Environment variable value” entity. Also known as a current value or override value. Set this when you’d like to override the default value in your current environment. Remove the value from your solution if you don’t want this value used in the next environment. While it is typically unhealthy to modify solution components in production environments, you may enter a current value in the production environment without introducing unhealthy behaviors to the consuming component or the Environment variable definition. Note: a 1:1 relationship is currently enforced between the Environment variable definition and the Environment variable value. A value also cannot exist without a definition.

Why is there a default value and a value? This allows you to service the definition and default value separately from the current value. It also allows us to extend the functionality in the future to support multiple values scoped to a specific run time context. A separate JSON file added to your solution file that stores the values.

Note: The above is only a recommendation on how to use default values and values. If using both, you will need to handle the logic to determine which value should be used. 

Notifications

When Environment variables do not have any values, users with access to the variables will see a notification. This is a reminder to set the value(s) so that components dependent on variables do not fail. It also allows ISV’s to ship variables without values and the customer will be prompted to input the value(s). Note: we recommend ISV’s build their own interfaces when customers are required to provide values. Notifications will help prevent failures if that step is skipped. 

Current limitations

• Caching. Plugins will need to run a query to fetch the values.
• Canvas apps and flows can consume Environment variables just like entity record data. In the future we plan to build additional actions into canvas app and flow designers. This will simplify authoring and provide better visibility into environment variables being used by a specific app or flow.
• Key vault integration for secrets. Currently Environment variables should not be used to store secure data such as passwords and keys.
• Data types are validated in the modern solution interface only, but not currently on the server.

Example: Use Environment variables in a flow

As of this writing, environment variables can be retrieved in the same way as other Common Data Service or Dynamics 365 for Customer Engagement records via oData or fetchXML queries. The following demonstrates how to send an email to one address in a test environment and to a different email in your production environment without needing to modify the flow. Note: this has been simplified as a step-by-step process for demonstration purposes; you would likely build your flow to be more dynamic.

Create the Environment variable

1. Go to https://make.powerapps.com or https://flow.microsoft.com
2. Go to Solutions and create a new solution.
3. Create a new Environment variable and name it email.
4. In the default value field enter the email address to be used in production. In the value field, enter a different email address to use for local testing in your development environment. Take note of the Name (ie: cb_Email). This is the schema name and you will need it later.

Create the flow

1. Create a flow from the same solution used above. Select a trigger of your choice.
2. Initialize a variable. Set the Name to the Schema Name of your environment variable (step 4 above). Initializing a variable is optional, but it demonstrates how to use a local variable to store either the default value or current value of the environment variable for use in subsequent steps.
3. Make sure you’re using the “Common Data Service (current environment)” and add a “List records” step.
4. Select “Environment Variable Definitions” for Entity name.
5. In the filter query, type schemaname eq ‘cb_Email’ (use the actual Schema Name of the Environment variable you created).
6. Add a step Set variable. 
7. Set Name = cb_Email, which is the local variable created in step 2. Set Value = Default Value from the dynamic properties available from the list records step. Note flow will add an ‘Apply to each’ condition, but this will not loop through additional objects since you’ve already set the ‘List records’ query to return one object. 

Check if a current value exists

1. Add another List records step and choose Environment variable value for the entity. In the Filter query, enter _environmentvariabledefinitionid_value eq and add the Environment Variable Definition from the dynamic content list. Note, this will add another ‘Apply to each’ condition.
2. Add an action for Set variable. Select the same variable used previously ie: cb_Email. Then set Value to Value from the dynamic content under List records 2. 
3. At this point the flow has initialized a new local variable, set the value to the default value of the Environment variable (if present), then set the local variable value to the Environment variable value (if present). You now can create additional logic, or add a final send email step.
4. Add a final step for Send email. In the To line, insert the local variable.
5. Save and Test the flow.

Migrate your solution

1. Navigate back to your solution. Since you want to use the default value of the Environment variable in your production environment, we’re going to remove the value from the solution so that it won’t be migrated. The current value will still be the value that’s used in your current environment, even though it’s not in your solution because it still exists in the Common Data Service database.
2. Export your solution and then import to another environment. Note you can also use the PowerApps build tools if you’d like to automate migration in Azure DevOps.

For the latest and detailed information about this feature, see the feature documentation at Use environment variables.