Overview

Version: This material pertains to version 2.94 of Blackbaud CRM SDK.

Import handlers allow the SDK developer to validate, alter, scrub, and enhance each row of data just before it is added (imported) into a batch staging table.

Import Handlers Supplement Data Validation

Since Import bypasses the batch grid user interface as a means to get data into a batch, it therefore bypasses any Batch Event Handlers associated with the batch user interface data entry grid. Import handlers can be used as an additional tool to help check data along with Batch Event Handlers.

ImportHandlers Tag within the BatchTypeSpec

You can create your own custom batch types with a BatchTypeSpec in the SDK. The BatchTypeSpec contains a new ImportHandlers element. This optional element allows custom import handlers when you import files for a batch type. Import handlers are used by the import process to handle file- and row-level operations when importing data.

The ImportHandlers element contains one-to-many child ImportHandler elements. Each ImportHandler element identifies the custom component used to import a file. The ImportHandler's AssemblyName attribute provides the name of the assembly that contains the component while the ClassName attribute provides the name of the class within the assembly that implements the import handler.

Each ImportHandler element can contain static parameters. The StaticParameters element can contain a ParameterList child element which in turn contains a series of Param elements. Use StaticParameters to indicate fixed-value parameters to pass to the CLR object referenced by the ImportHandlers element.

Figure: Sample ImportHandlers element for the constituent batch

Create an Import Handler

Creating an import handler requires authoring a .NET CLR class that inherits from Blackbaud.AppFx.Platform.Catalog.ImportProcessHandler. ImportProcessHandler is declared as MustInherit and is a member of the Blackbaud.AppFx.Platform.Catalog namespace. The ImportProcessHandler is located within the Blackbaud.AppFx.Platform.Catalog.dll assembly that you can locate in your <Your local SDK Install Location>\SDK\DLLReferences folder. Your import handler class file should reside within an existing or new UI Model assembly project. If you need to create a UI Model project, first create a new Blackbaud AppFx server-side UI model assembly project using the UI Model Project template within Visual Studio.

Note: For information about how to install the SDK and set up your local development environment, see Blackbaud CRM SDK Developer Environment Setup.

Within the UI Model assembly project, you need to set a reference to the Blackbaud.AppFx.Platform.Catalog.dll. Within your import handler class, the developer can override procedures within the base class such as BeforeFileImport, AfterFileImport, BeforeRowImport,and HandleImportRowException. These procedures help to verify the import file and check each row of data for problems. BeforeRowImport is called by the application for each row to check the data within the row. BeforeRowImport returns an object of type Blackbaud.AppFx.Platform.Catalog.ImportProcessHandlerResult to represent the results of each row processed. Within ImportProcessHandlerResult, an error message can be provided if needed along with the result enum value of either CriticalError, NonCriticalError, or Successful. Import handlers may also be added to a BatchTypeExtensionSpec.

For more details, see Example: Creating an Import Handler.

Tip: You can find the Food Item Add Batch BatchTypeSpec sample within the Blackbaud.CustomFx.FoodBank.Catalog project's \Batch Types\Food Item\FoodItemAdd.Batch.xml spec file. You can find the import handler code within the Blackbaud.CustomFx.FoodBank.UIModel project within the \Batch\Food Item\FoodItemCapitalizeImportHandler.vb class file. Be sure to download and review the sample within the latest food bank source code download.

Order of Import Operations

Here is a list of the order of operations for processing an import file. First, the BeforeFileImport function is called. Next, for each row within the import file the BeforeRowImport function is called as each row is read from the input stream. Immediately following BeforeRowImport is the call to the Add Batch Row Data Form (Batch Add). The Batch Add performs the actual importing of data as a new row into the batch staging table. It is simply an Add Data Form Template Spec whose stored procedure inserts a row into the batch staging table. If errors during processing the Batch Add, then HandleImportRowException handles the problem. HandleImportRowException receives row number, batch row data form item, and a list of all errors that occurred when saving the row using the batch add data form. HandleImportRowException may be overridden if your requirements dictate any additional functionality beyond the default handling of importing a row exception. Finally, the AfterFileImport is called.

1. BeforeFileImport

   For loop on all import rows

2. BeforeRowImport

3. Save rows using Add Batch Row Data Form (Batch Add)

   If errors during processing add form then HandleImportRowException

   End for loop

4. AfterFileImport

Import Handlers Work in ClickOnce and Web Shell

Import handlers are not tied to either the ClickOnce Smart Client user interface or the Web Shell user interface. They are executed as part of the import process and complete prior to the batch data being viewed within either user interface.