Custom SSIS workflow task

I have a ton of containers that all follow this same basic premise:

When I pull data from a remote database I first blank out a collector table, copy the data from the remote DB to the collector, count the rows in the collector, and if there are enough rows then I merge into the real table. If not, I send an email with an error message.

Instead of repeating this over and over I would like to make a custom component. I think this is just a filter component I would make, but what I'm not really sure of is how to replicate the Data Flow Task piece. Are there any good examples somebody could point me to, or even just let me know what I want to do isn't possible?

Solution

When I see problems like this, Biml tends to offer the lowest barrier to creating a simple, repeatable solution. Biml is free, all it costs you is a registration email and install BimlExpress into whatever version of Visual Studio/SSDT you are working with.

I assume that I'm going to collect the data from AdventureWorks2014 Sales.Currency table and transport it to a table in tempdb called dbo.SalesCurrency.

I defined it as

CREATE TABLE dbo.SalesCurrency
(
    CurrencyCode nchar(3) NOT NULL
,   Name nvarchar(50) NOT NULL
,   ModifiedDate datetime NOT NULL
);

Given that, let's look at some Biml concepts. Biml is an XML based dialect that describes the business intelligence artifacts (and then some). If you ever did classic ASP development with the mix of scripting and tags, it's a similar concept but much nicer due to the .NET integration.

<# #> this is a multi-line block
<#= #> is a single line expression

Great, how do I use it? Assuming you've installed BimlExpress, open an SSIS project and right click on the Project section and select Add New Biml File. Do that twice and we'll rename the second one. The first one is a driver, the second one is the worker.

Brains biml

<Biml xmlns="http://schemas.varigence.com/biml.xsd">
    <Connections>
        <OleDbConnection Name="Source" ConnectionString="Data Source=localhost\dev2017;Initial Catalog=AdventureWorks2014;Provider=SQLNCLI11.0;Integrated Security=SSPI;" />        
        <OleDbConnection Name="Target" ConnectionString="Data Source=localhost\dev2017;Initial Catalog=tempdb;Provider=SQLNCLI11.0;Integrated Security=SSPI;" />        
    </Connections>
<#
string sourceQuery = "SELECT * FROM Sales.Currency;";
string targetSchemaTable = "[dbo].[SalesCurrency]";
string templateName = "so_56050574_include.biml";
dynamic customOutput;
#>
    <Packages>
        <#= CallBimlScriptWithOutput(templateName, out customOutput, sourceQuery, targetSchemaTable) #>
    </Packages>
</Biml>

The first line is just xml namespace.

The next block, the Connections collections I define my Source and Target connections. I'm very creative and named them Source and Target

The next lines look a lot like C# because they are. I define my source query, fully qualified target table name, square brackets included and the name of my template file. The final variable, customOutput isn't used in here but it's a bag that allows me to pass information back from the template file - namely the name of the SSIS package it built.

I then define a Packages collection and make a single package. The package I make is defined by whatever I send to CallBimlScriptWithOutput and I then use the variables I just defined.

It looks complex but it's not. Why I like this approach is that instead of hard coding these values into my driver program, it allows me to take a metadata driven approach to development. I could look these values up from a spreadsheet, Sharepoint List, webservice, whatever I feel like (or my client offers as a repository).

Worker biml

I name this file so_56050574_include.biml and while there's plenty of text in there, it's fairly straight forward.

The first line helps the Intellisense during the Biml design experience. The next two lines specify that these variables are going to be passed in - like a function call. I'll be able to use them like a .NET variable within the scope of this file.

The next few lines are a little funky but SSIS doesn't like duplicated names and it also doesn't like "bad" characters in names. I specify the package name will be Populate Collector and then I make the target table safe for SSIS. All the way at the bottom of the file, you'll see I have made a tiny method called MakeSsisSafeName which I use to sanitize the package name.

I create a Package and give it a good name. That Package has a Container. Within the Container, I create a handful of SSIS Variables that I'll need to do my work. That Container has tasks of Execute SQL Task -> Data Flow Task -> Execute SQL Task -> Execute SQL Task --> Send Mail Task

<#@ template designerbimlpath="/Biml/Packages" #>
<#@ property name="SourceQuery" type="string" #>
<#@ property name="TargetSchemaTable" type="string" #>

<#
string packageName = string.Format("Populate Collector {0}", MakeSsisSafeName(TargetSchemaTable));
CustomOutput.PackageName = packageName;
#>
<Package Name="<#= packageName #>" ConstraintMode="Linear">
    <Tasks>
        <Container Name="SEQC Collector" ConstraintMode="Parallel">
            <Variables>
                <Variable Name="RowCount" DataType="Int64">0</Variable>
                <Variable Name="QueryEmpty" DataType="String">TRUNCATE TABLE <#=TargetSchemaTable#></Variable>
                <Variable Name="QueryCount" DataType="String">SET NOCOUNT ON; SELECT COUNT_BIG(1) AS rc FROM <#=TargetSchemaTable#></Variable>
                <Variable Name="QuerySource" DataType="String"><#=SourceQuery#></Variable>
                <Variable Name="TargetSchemaTable" DataType="String"><#=TargetSchemaTable #></Variable>
            </Variables>
            <Tasks>
                <ExecuteSQL Name="SQL Empty Collector Table" ConnectionName="Target">
                    <VariableInput VariableName="User.QueryEmpty" />
                </ExecuteSQL>
                <Dataflow Name="DFT Populate Collector Table">
                    <Transformations>
                        <OleDbSource Name="OLESRC Query" ConnectionName="Source">
                            <VariableInput VariableName="User.QuerySource" />
                        </OleDbSource>
                        <OleDbDestination Name="OLEDST Target" ConnectionName="Target">
                            <TableFromVariableOutput VariableName="User.TargetSchemaTable" />
                        </OleDbDestination>
                    </Transformations>
                    <PrecedenceConstraints>
                        <Inputs>
                            <Input OutputPathName="SQL Empty Collector Table.Output" EvaluationValue="Success" />
                        </Inputs>
                    </PrecedenceConstraints>
                </Dataflow>
                <ExecuteSQL Name="SQL Count Collector Table Rows" ConnectionName="Target" ResultSet="SingleRow">
                    <VariableInput VariableName="User.QueryCount" />
                    <Results>
                        <Result Name="0" VariableName="User.RowCount" />
                    </Results>
                    <PrecedenceConstraints>
                        <Inputs>
                            <Input OutputPathName="DFT Populate Collector Table.Output" EvaluationValue="Success" />
                        </Inputs>
                    </PrecedenceConstraints>
                </ExecuteSQL>
                <ExecuteSQL Name="SQL Merge Collector Data" ConnectionName="Target">
                    <DirectInput>SELECT 1; -- simulate merge</DirectInput>
                        <PrecedenceConstraints>
                            <Inputs>
                                <Input OutputPathName="SQL Count Collector Table Rows.Output" EvaluationOperation="ExpressionAndConstraint" EvaluationValue="Success" Expression="@[User::RowCount] &gt; 0" />
                            </Inputs>
                        </PrecedenceConstraints>
                </ExecuteSQL>
                <!--
                <SendMail Name="Send Mail" ToLine="[email protected]" ConnectionName="Target" Subject="Subject line">
                    <DirectInput>Body here, I think</DirectInput>
                        <PrecedenceConstraints>
                            <Inputs>
                                <Input OutputPathName="SQL Count Collector Table Rows.Output" EvaluationOperation="ExpressionOrConstraint" EvaluationValue="Success" Expression="@[User::RowCount] == 0" />
                            </Inputs>
                        </PrecedenceConstraints>
                </SendMail>
                -->
                <ExecuteSQL Name="SQL Pretend I send mail" ConnectionName="Target">
                    <DirectInput>SELECT 2; -- simulate merge</DirectInput>
                        <PrecedenceConstraints>
                            <Inputs>
                                <Input OutputPathName="SQL Count Collector Table Rows.Output" EvaluationOperation="ExpressionAndConstraint" EvaluationValue="Success" Expression="@[User::RowCount] ==0" />
                            </Inputs>
                        </PrecedenceConstraints>
                </ExecuteSQL>
            </Tasks>
        </Container>
    </Tasks>

</Package>

<#+
private static string MakeSsisSafeName(string name)
{
    return name.Replace("/", "_").Replace("\\", "_").Replace(":", "_").Replace("[", "_").Replace("]", "_").Replace(".", "_").Replace("=", "_").Trim();
}
#>

Right click on the BimlScript brains file and select Generate SSIS Package

That should build out a package like this and hey, it works!

What's not covered

I don't know how you actually use this. Maybe you have one big package with lots of containers and your vision is to just push the button and have another template container added. Biml won't do that. It doesn't merge two SSIS packages - it overlays one with current definition. But, the way I defined all of this, you should be able to copy the generated Container and paste it into an existing SSIS package - assuming it has two connections named Source and Target.

Connections can also be tricky. If you're collecting data from N source servers then you'll likely want a looping mechanism to change out the Source value. That's not hard. But if the source data you're pulling back for each Collector has a different signature, then you need each bespoke Data Flow task.

Sending Email. I don't have an SMTP connection handy so I put a best guess at what the Send Mail would look like and then commented it out  You'll need to add a Connection for your SMTP server in the brains package and then configure the SendMail task to use it. And then remove my "SQL Pretend I send mail" task.

Finally, you'll notice the names are repeated in the worker Biml. That tells the engine how things should be wired up. If you don't like what I called something, you'll need to change it in two places. Search and Replace will be handy in this ;)

The question asked about custom workflow tasks - answer it

Fine. It sucks. The DataFlow stuff gets into COM objects and they aren't pleasant to work with. When you supply a query or source table, you need to check the metadata, add/remove columns and lots of stuff that's poorly documented and is a lot of scut work. And that's just building a "regular" package through the interfaces. Once you get that solved, then you are looking at encapsulating that logic into a custom componentry which used to be documented with fair enough samples on Codeplex but that's dead now and I don't know if it's been migrated to github. Oh and custom tasks and components especially are version dependent so you get to build against the various binaries to get a dll for each. And then you'll likely need to build out UI components to help folks configure your SSIS task/component. And then you'll need to worry about delivering and installing it on each developer's computer. And the server installation.

Or, I can define it once via Biml and be done.