Connection references and environment variables

A Power Platform solution that hard-codes connection IDs and configuration values is a solution that needs manual fixup every time it deploys to a new environment. Connection references and environment variables are the two mechanisms that make solutions truly portable — abstracting environment-specific details so the same solution package deploys to dev, UAT, and production cleanly.

Connection references.

A connection reference is a solution component that abstracts the kind of connection a flow or app needs without binding to a specific connection instance.

Example: a Power Automate flow that calls SharePoint. In dev, the flow connects to Dev SharePoint Site; in UAT, UAT SharePoint Site; in prod, Prod SharePoint Site. Without connection references, deploying the flow across environments means manually re-pointing the connection each time — error-prone and slow.

With connection references:

• The flow references a connection reference (e.g. cr_SharePointConnection) instead of a specific connection.
• The connection reference declares the connector type (SharePoint) without the specific credentials.
• At import time to each environment, the connection reference is bound to an environment-specific connection (the dev SharePoint connection in dev, etc.).
• The flow code stays the same; the binding differs per environment.

Lifecycle.

• Create the connection reference in the development environment, bound to a dev connection.
• Use the connection reference in flows / apps instead of direct connections.
• Export the solution as managed.
• Import to UAT / prod — the import process prompts for the target environment's connection to bind to the reference.
• Automate the binding in pipelines using the Power Platform CLI or solution import parameters.

Environment variables.

An environment variable abstracts a configuration value — a URL, an API key (via secured environment variable), a numeric threshold, a feature flag — so it can differ per environment.

Example: a flow that calls an external API. The API URL is https://api-dev.example.com in dev, https://api-uat.example.com in UAT, https://api.example.com in production. Without environment variables, the URL hard-codes; deploys break.

With environment variables:

• The flow references an environment variable (e.g. cr_ApiBaseUrl).
• The variable's default value in the solution is the dev URL.
• On import to each environment, the import asks for the environment-specific value (or accepts the default).
• The flow uses the variable's value at runtime.

Variable types.

• String — text values (URLs, names, identifiers).
• Number — numeric values (thresholds, counts).
• Boolean — Yes/No flags.
• JSON — structured configuration.
• Data source — references to specific Dataverse environments or tables.
• Secret — secured values pulled from Azure Key Vault. The variable points to a Key Vault URL and secret name; runtime fetches the value at execution. Used for API keys, connection strings, anything sensitive.

The combined effect. A well-designed solution uses both:

• Connection references for every external connection (SharePoint, SQL, third-party APIs, even Dataverse environments).
• Environment variables for every value that differs per environment.

The result: the same managed solution package deploys to any environment without modification. Bindings happen at import time, automated via CI/CD pipelines.

Pipeline automation. In Azure DevOps or GitHub Actions:

• The pipeline holds environment-specific bindings as variables / secrets.
• During import, the bindings are supplied through the pac solution import parameters or the Power Platform Build Tools task.
• The same solution artefact, imported with different binding parameters, produces correctly-configured deployments.

Common pitfalls.

• Some Flows still bound to specific connections. Migrating an existing flow to use a connection reference requires explicit migration — Microsoft has improved this but legacy flows may still need cleanup.
• Environment variables not parameterised in pipeline. If the pipeline imports with default values only, the wrong environment's defaults land in production. Always supply environment-specific values at import.
• Secret variables not properly secured. If treating sensitive values as plain string variables, they're visible in solution exports. Use Key Vault-backed secret variables.
• Renamed connection references. Renaming after deployment leaves orphan references in environments; cleanup is manual.

Operational discipline. From day one of a Power Platform solution build, use connection references and environment variables for everything environment-specific. The investment is small at design time; ignoring it produces deploy pain forever.