This post discusses how to parameterize connection strings and values at runtime using SSIS environment variables. Although it may seem like a lot of steps, it's a one-time setup per environment and makes your SSIS projects very portable and allows for easier manageability of dynamic values that change routinely.
Applicable to: SQL Server 2012 or 2014. Screen shots shown are from SQL Server 2014.
What are SSIS Environment Variables?
SSIS Environment Variables provide the mechanism to set values at the time a package is executed. This functionality is useful for any number of things, frequently for specifying different values between Dev, QA, and Prod environments.
Note that these SSIS environment variables are a different thing than Windows environment variables, although similarly named. They're also different from "regular" variables inside an SSIS package.
This technique is applicable to SQL Server 2012 and up, and only to the project deployment mode (i.e., not package deployment mode). The concept of SSIS Configurations is no longer applicable with the project deployment mode as they've been replaced with SSIS Environment Variables. If you're just getting familiar with these concepts, please check out this overview: Getting Started with Parameters, Variables, and Configurations in SSIS 2012 (the overview blog entry has gotten to be one of my most visited pages so I figure that's a clue that I should write more on the subject, eh?).
Steps for Using SSIS Environment Variables to Parameterize Connection Strings and Values When the Package Executes
SQL Server Data Tools (SSDT) - Integration Services Project
Step 1: Create Parameters (Project or Package level as appropriate) and associate expressions, source queries, etc to these Parameters as appropriate.
Step 2: Parameterize connection strings.
Step 3: Deploy Project to the SSIS Catalog once package executes as desired within SSDT.
SQL Server Management Studio (SSMS) - Integration Services Catalogs>SSISDB
Step 4: Create Environment & set up Variables within the Environment. These should coincide with the Parameters from the SSIS project.
Step 5: Configure each Project (and Packages individually, if needed).
Step 6: Execute package in SSMS via the Catalog. Will need to manually specify which Environment to use at execution time when running in this on-demand manner.
Step 7: Create Agent Job to execute on an ongoing basis. Associate the job to the appropriate Environment so it automatically detects values which have been set.
Details for each step are below.
Step 1: Create Parameters and Associate Expressions to the Parameters (SSDT)
First thing to do is determine what elements of the package you wish to be able to vary at runtime. Or, in other words, what may need to be changed by the DBA or system admin without the SSIS developer needing to make a change in SSDT and redeploy the package.
In the example below I have 2 project-level parameters that signify a date range. Since this date range would apply to multiple packages, I made these project-level parameters rather than at the package-level:
Sidenote: in the real world, this generic name of "data extract..." would be too vague. As you'll see below, the SSIS environment variables on the server are shared across all projects, so that may influence your naming conventions if you have numerous projects to manage.
And here's an example of how a source query in my data flow has been associated to the project parameters:
Usually an SSIS project of any size ends up with at least a few project/package parameters, but it is possible that you don't have any.
Step 2: Parameterize Connection Strings (SSDT)
Note that there's a couple of different ways to handle changes to connection strings as you migrate from Dev to QA to Production. This describes one way to handle connections by grouping them with parameters.
I ensure that all connections are project level (not package level) and then I like to parameterize each of my connection strings:
In this example I've parameterized the connecting string itself. You can parameterize individual properties like server name, user name, catalog, if you prefer. This connection string is using Windows authentization so it's not set to sensitive (if it were a password you'd want to set it to sensitive so that it's encrypted).
I do like to set it to be Required which ensures it will be set in the SSIS Catalog before the package can be executed on the server.
Once you have parameterized your connections, you'll see them in the parameters pane.
Step 3: Deploy Project to SSIS Catalog
For deploying to Dev, I usually just right-click the project in SSDT and deploy to the Catalog from there.
For deploying to other environments like Prod, where you may need to hand off the deployment to someone else, I typically make use of the ISDeploymentWizard tool instead. Details on this can be found here: http://msdn.microsoft.com/en-us/library/hh231102.aspx.
Step 4: Create Environment & Set Up Each Variable (SSMS)
Once you've deployed your project to the SSIS Catalog, you'll be able to see it in SQL Server Management Studio.
Next we want to create a new SSIS Environment (assuming it doesn't already exist). Environments are usually called Dev, QA, Prod, that sort of thing, but they could of course be used differently in some situations.
For setting up new variables within the SSIS Environment, you want to have SSDT open as well as SSMS. Copy and paste the name & value for each parameter from the SSDT parameters window into the SSIS environment variable window (note: I tend to use an EV prefix but that's just a personal preference). Modify any of the values if different on the server than were used in SSDT.
Step 5: Configure Each Project (SSMS)
At this point we have an SSIS environment available with variables specified that coincide with our parameters. Now we're ready to let the project know that the environment exists (and which one to use, if there are multiple environments on the same server).
On the parameters page, we can associate each parameter for the project to the environment variable that was set up. In this example I kept the scope at the project level, but you can set them at the individual package level when appropriate.
In the screen shot above, you'll see there's one package-level parameter that is just set to "Yes." When you see this, you might be tempted to just set the connection values here too and not bother with referencing them to the SSIS environment variables. If you only have one or two projects, that method would be ok. However, if you have a larger number of SSIS projects that all make use of shared parameters and/or database connections, you'll find great benefit in changing the values of an SSIS environment variable once and allowing it to affect all projects.
Step 6: Execute in SSMS Via the Catalog (SSMS)
At this point, everything is set up. Let's run it in SSMS to see if it works.
Initially, you see alerts because SSIS doesn't presume to know which environment to use (even if only one exists). So, you want to check the box and choose the correct environment - this will always be true when a package is run on-demand like this.
Step 7: Create Agent Job and Associate Job to the Environment (SSMS)
Our last step is to set up an Agent job to run the package on a schedule.
I won't go into detail on settings for the Agent job, but the key to bringing it all together is on the Configuration page where you specify which Environment the job should use.
Note that you can also specify a parameter value directly within the Agent job. In most situations I wouldn't do this since it could be confusing if different than the environment variable or the project configuration, but it is nice flexibility to have if used with caution.
You Might Also Like...
Getting Started With Parameters, Variables & Configurations in SSIS 2012