Migrating ADF Global Parameters to Fabric Variable Libraries - A Practical Guide
If you're moving pipelines from Azure Data Factory or Synapse into Microsoft Fabric, global parameters are one of the first things that will trip you up. Fabric Data Factory doesn't have them. Every pipeline that references @pipeline().globalParameters.SomethingImportant will need to point at something else, and that something else is a variable library.
We've done a fair few of these migrations now for Australian clients, mostly mid-sized organisations with somewhere between 30 and 300 ADF pipelines that grew organically over five or six years. Global parameters are rarely the hardest part of the migration. But they're the part that touches the most pipelines, and if you handle them badly you end up with environment-specific values hardcoded all over Fabric, which is worse than where you started.
Here's how variable libraries work, how the migration goes in practice, and the things I wish someone had told us before the first one.
Why global parameters existed in the first place
In ADF, global parameters were the standard way to hold values that were the same across many pipelines but differed between environments. Typical examples:
- Storage account names or container paths
- SQL server names and database names
- Key Vault URLs
- Email addresses for failure notifications
- Feature flags like "run the full load" versus "run incremental"
You'd set them once at the factory level, and when you deployed from dev to test to prod through ARM templates or the ADF publish process, you'd override them per environment. It worked. The CI/CD story around overriding them was a bit painful, but most teams eventually got a pattern going.
What variable libraries are
A variable library is a Fabric item that lives in your workspace. It holds a set of named, typed variables, and it can hold multiple value sets, one per environment or stage. Each workspace has an active value set, so the same variable library deployed to your dev workspace and your prod workspace returns different values depending on which value set is active in each.
Variables are typed. You'll see types like string, integer, number, boolean, datetime and GUID, plus item references that point at other Fabric items. Typing matters more than it sounds. In ADF, a lot of global parameters were strings holding numbers or booleans, and expressions did implicit conversion. In Fabric you get to be explicit, and you should be.
In a pipeline, you add the variable library variables you need in the pipeline's library variables section, and then reference them in expressions with @pipeline().libraryVariables.YourVariableName.
The big difference from ADF global parameters is scope. Global parameters belonged to a factory. Variable libraries belong to a workspace and can be consumed by more than just pipelines. Other Fabric items are adding support for them too, which means you can end up with one place to hold environment configuration across pipelines, notebooks and other workloads. That's a genuine improvement over ADF, where pipeline config and notebook config usually lived in completely separate places.
How the migration actually goes
Microsoft's documentation walks through the conversion, and if you're using the ADF-to-Fabric migration tooling, a lot of this can be done for you. But regardless of the tooling, the shape of the work is the same.
1. Inventory your global parameters.
Before you touch anything, export the list of global parameters from each factory, along with their values in every environment. If you've been overriding them through ARM template parameter files, pull those too. You need the full matrix: parameter name, type, dev value, test value, prod value.
This step sounds trivial. It rarely is. On one migration, we found 47 global parameters in the factory, of which about 15 were no longer referenced by any pipeline. Another five had prod overrides that nobody on the current team knew about. One of those was a hardcoded SFTP password, which turned into its own separate conversation.
2. Find where each one is used.
Search the pipeline JSON for globalParameters. You'll get a count per parameter. This tells you which ones matter and which ones you can drop. It also tells you which pipelines will need editing.
3. Create the variable library.
Create a variable library in your Fabric workspace and add a variable for each global parameter you're keeping. Use the same names where you can. It makes the expression replacement mechanical and makes code review easier.
Set the correct types. Then create value sets for each environment and populate them from your inventory.
4. Update the pipelines.
For each pipeline, add the library variables it needs, then replace every @pipeline().globalParameters.X with @pipeline().libraryVariables.X. If you're doing this at scale, it's worth scripting the find-and-replace over the pipeline definitions rather than clicking through the UI. Just test the result.
5. Set the active value set per workspace.
In each workspace (dev, test, prod), make sure the right value set is active. Then run your pipelines and check they're picking up the correct values. A pipeline in prod reading the dev storage account is the kind of thing that can go unnoticed for a surprisingly long time if the dev account has similar-looking data.
Things to watch out for
Don't migrate secrets into variable libraries. If you were storing anything sensitive in global parameters (and I've seen connection strings, API keys and passwords in there more times than I can count), this is your chance to fix it. Secrets belong in Azure Key Vault, accessed through Fabric connections. A variable library is configuration, not a vault. Anyone with access to the workspace can see the values.
Watch the type conversions. Expressions that worked in ADF because everything was a string may behave differently when the variable is a real integer or boolean. Things like @equals(pipeline().globalParameters.IsFullLoad, 'true') will need rewriting if IsFullLoad becomes a proper boolean. Test the branching logic carefully, especially in If Condition and Switch activities.
Consider the deployment pipeline story up front. Variable libraries are designed to work with Fabric deployment pipelines and Git integration. Decide early whether you're promoting through Fabric deployment pipelines or through Git and your own CI/CD, and make sure the active value set is handled correctly in each target workspace. We've seen teams get the library right and then accidentally deploy with the wrong active value set, which silently points prod at dev resources.
Linked service parameters are a separate problem. In ADF, a lot of environment-specific config actually lived in linked services, not global parameters. Fabric replaces linked services with connections, and those need their own migration plan. Don't assume moving global parameters covers all your environment config.
Resist the urge to put everything in one giant library. It's tempting to create one variable library per workspace with every setting anyone could ever need. That gets messy. We usually group by domain: one library for storage and lakehouse references, one for notification settings, one for source system config. Smaller libraries are easier to reason about and easier to review when someone changes a value.
Check feature coverage before you commit. Variable library support across Fabric item types has been expanding, and not everything was supported on day one. If you have notebooks or dataflows that need the same config, check the current documentation for what can consume variable libraries before you design around them.
Is this better than global parameters?
Mostly, yes. Having typed variables, explicit value sets and the ability to share configuration across item types is cleaner than what ADF offered. Having the active value set tied to the workspace also matches how most teams actually think about environments: "this is the prod workspace, so it uses prod settings."
What I miss is a little of the simplicity. In ADF, a global parameter was right there in the factory settings. In Fabric, you now have a separate item, value sets, an active selection and pipeline-level declarations. For a small team with five pipelines, that's more ceremony than they need. For a team with 200 pipelines and three environments, it's exactly the right amount of structure.
Where to start
If you're planning an ADF to Fabric migration, do the global parameter inventory first, before anything else. It's a cheap exercise that tells you a lot about the health of your existing factory: how much dead config there is, where secrets are hiding, and how consistent your environments really are.
If you want help with the broader migration, our Microsoft Data Factory consultants have done enough of these to know where the bodies are buried, and our Microsoft Fabric consultants can help design the workspace and deployment structure around it so the variable libraries actually make sense across environments.
Microsoft's reference documentation is here: Migrate global parameters to variable libraries.