What's New for Blackbaud CRM SDK v2.94

This topic describes new features for the 2.94 release of the Blackbaud CRM SDK.

Kitchen Sink SDK Samples

Overview

The Kitchen Sink is a functional area containing a series of SDK samples used to highlight new feature functionality for the Web Shell user interface. Once you have compiled, deployed, and opted into the samples, you can review new feature functionality within Kitchen Sink functional area within Blackbaud CRM 2.94. Descriptions located next to the feature provide details on the newest features and feature enhancements. You can review the source code within the SDK Samples to review how these features were built.

Figure: The Kitchen Sink Chart Widgets Page is just one of the cool new features showcased by the Kitchen Sink SDK Samples

See Blackbaud Infinity What's New - Kitchen Sink Videos within the Developer Guides for more information on the Kitchen Sink.

Pages

Page Layout Control with New DisplayZones Element

The DisplayZones element allows page authors additional levels of control over page layout within the Web Shell user interface. Traditionally, a developer can organize a feature such as a Data List or UI Widget within a section that is placed within a tab on a page. Fortunately, using display zones developers can easily layout page sections in either two equal columns or use html to arrange a custom layout of zones on a page.

The DisplayZones element may optionally be added underneath the Tab's Sections element. Within the DisplayZones element, a series of 1 to many DisplayZone elements should exist. Each DisplayZone element indicates a single location in the layout of the page. A DisplayZone may represent one or several sections defined within page's tab, in this way, sections may be displayed together within a zone and a zone may be positioned on a page. more...

For a review on the various ways to layout features within a tab on a page see Tab Section Layout Options.

Displaying List Builders on a Page with New ListBuilder Element

An SDK developer can define a List Builder using a QueryViewSpec and then place the List Builder on a page. A new ListBuilder element within a PageDefinitionSpec describes a section that displays a List Builder. The ListBuilder element includes a QueryViewID attribute used to hold a guid representing the ID of the query view that will provide data for the List Builder section. more...

Figure: A List Builder is displayed within a page using the ListBuilder element within a section.

Query Views and List Builders

ListBuilder, Columns and Column Elements

Query Views help define and provide data to List Builders. Within a QueryViewSpec, the ListBuilder element describes information used to render the query output in a List Builder page section. The ListBuilder element holds a Columns element which is used to provide a list of query view columns to be shown when the list is created. Each Column element within the Columns element contains a Name attribute which is the name of the column in the query output. In the example below, I have added a new EMAIL column to the original list of 3 columns (NAME, AGE, BIRTHDATE) within the ListBuilder element. The modified spec was loaded and as a result a fourth column is now displayed within the List Builder by default..

Figure: Adding a new column to be displayed by default within the List Builder when opened.

A food bank list builder code sample can be found within the catalog project's Blackbaud.CustomFx.FoodBank.Catalog\ListBuilder\Final\FoodBankListBuilder.Query.xml spec file. Be sure to download and review the sample within the latest food bank source code download.

See List Builder Videos within the Developer Guides for more information on building a List Builder.

New Context Element within QueryViewSpec

The Context element contains the record type and associated parameter name that is required by the List Builder. A code sample of using context within a QueryViewSpec/List Builder may be found within the Kitchen Sink code samples within the \SDK\Samples\WebShellKitchenSink.Catalog\ListBuilder\KitchenSinkListBuilderWithContext.Query.xml file in the WebShellKitchenSink.Catalog Visual Studio project. Use the context element when you want to provide a list of records for a given parent record. The Kitchen Sink sample provides a list of friends for an individual. The task which opens the page containing the List Builder first uses a search list to retrieve the context value and then passes the context value (parent record id) to the page which displays the List Builder.

Figure: A List Builder with context

Use List Builder to Display Data Warehouse Info with MartKey Attribute, ViewSchema attribute, and FunctionSchema attribute

Query Views provide data to List Builders. A new optional MartKey attribute has been added to the QueryViewSpec element to support querying and displaying data from the data mart for List Builders. Query Views against a data mart are intended to be leveraged by List Builders and should not be exposed as a root view for display within Query at this time. The MartKey indicates where the SQL object defined within either the ViewImplementation or TVFImplementation is created. When no option is specified the SQL object are created in the application (transactional) database; otherwise, it is created in the OLAP data source referenced by the MartKey value. In short, the MartKey provides the ability for the view or function to be executed against the data warehouse.

Use the MartKey attribute in conjunction with the ViewImplementation element's ViewSchema attribute or the TVFImplementation element's FunctionSchema attribute which provides the ability for the stored procedure to be created in a different database schema. Most database objects within the data warehouse live within the "BBDW" schema. Your stored procedures will be placed into this schema by adding the value of ViewSchema="BBDW" to the ViewImplementation element or FunctionSchema="BBDW" to the TVFImplementation element.

Assuming the Blackbaud Data Warehouse is installed, the value of MartKey should be set to “BBDW” in the spec to indicate the Blackbaud Data Warehouse database. The OLAPDATASOURCE table within the application database is populated with a row when the Blackbaud Data Warehouse is installed. After installation the OLAPDATASOURCE table’s MARTKEY column is populated with a value of “BBDW”. These changes gives developers data retrieval capability against the data warehouse.

Batch/Import

ImportHandlers element

You can create your own custom batch types using a BatchTypeSpec via the SDK. TheBatchTypeSpec contains a new ImportHandlers element. This optional element allows custom import handlers when importing 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 handle importing a file. The ImportHandler's AssemblyName attribute is used to provide the name of the assembly which contains the component while the ClassName attribute is used to provide 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

Creating an Import handler requires authoring a .NET CLR class that inherits from Blackbaud.AppFx.Platform.Catalog.ImportProcessHandler. Within the 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.

A food bank ImportHandler sample can be found within the catalog project's \Batch Types\Food Item\FoodItemAdd.Batch.xml spec file. The UI Model code can be found 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.

Add Parameter Sets to a Batch with New Parameters Element

A new Parameters element within the BatchTypeSpec provides the ability to support parameter sets when adding or editing batch templates. Each parameter set appears as a tab within the Configure Options section when managing Batch Templates. The parameters values are fed to the batch's add, edit data forms which manage data within the batch staging table(s) as well as the commit data form which provides another data validation mechanisms and commits the data from the staging table(s) to the production table(s). The parameter sets are also managed when defining an import process more...

Figure: The Edit batch template screen contains two parameter sets named "Address validation" and "Name validation".

Data Lists

MartKey Attribute Supports Querying from the Data Mart

A new optional MartKey attribute has been added to the DataListSpec element to support querying and displaying data from the data mart. The new attribute indicates where the stored procedure for a stored procedure based data list is created. When no MartKey attribute is specified, the stored procedure defined within the spec is created within the application (transactional) database; otherwise the stored procedure is created in the OLAP data source. In short, the MartKey provides the ability for stored procedure based data lists to be executed against BBDW.

Use the MartKey attribute in conjunction with the SPDataList element's SPSchema attribute which provides the ability for the stored procedure to be created in a different database schema. Most database objects within the data warehouse live within the "BBDW" schema. Your stored procedures will be placed into this schema by adding SPSchema="BBDW" in the SPDataList section.

Assuming the Blackbaud Data Warehouse is installed, the value of MartKey should be set to “BBDW” in the DataListSpec to indicate the Blackbaud Data Warehouse database. The OLAPDATASOURCE table within the application database is populated with a row when the Blackbaud Data Warehouse is installed. After installation the OLAPDATASOURCE table’s MARTKEY column is populated with a value of “BBDW”. Data Lists are one of the types of features used to provide data to UI Widgets. These changes to the DataListSpec gives developers nice charting capability against the data warehouse.

Check out Ron Frum's post on BBDN describing How to build a data list against the Blackbaud Data Warehouse.

View Data Forms

MartKey Attribute Supports Querying from the Data Mart

Along with data lists and query view spec/list builders, a new optional MartKey attribute has been added to the ViewDataFormTemplateSpec element to support querying and displaying data from the data mart. The attribute is optional and Indicates where stored procedure in an SPDataForm is created. When no option is specified, the SQL stored procedure is created in the application database; otherwise, it is created in the OLAP data source provided.

UI Widgets

List Widgets

When rendering a widget as a list, the List element's ItemsPerPage attribute defines how may rows should be displayed per page within the widget, EnableHeaders attribute defines whether the headers will be used for sorting or resizing and EnableSelection attribute defines whether the row is selectable.

See KitchenSinkListUIWidget.UIWidget.xml within the Kitchen Sink code samples that ship with the SDK for an example. The code sample can be found within the catalog project within the \SDK\Samples\WebShellKitchenSink.Catalog\UIWidgets folder.

Chart Widgets

When rendering a widget as a chart, the Chart element's DisplayEmptySeries attribute indicates whether to show an empty series, GridDisplayStyle defined how to display grid lines on the chart (options include Show (default), Hide, HorizontalOnly, VerticalOnly), and HideChartBorder is a flag which indicates whether to hide the chart border.

See KitchenSinkChartWidget.Empty.UIWidget.xml within the Kitchen Sink code samples that ship with the SDK for an example. The code sample can be found within the catalog project within the \SDK\Samples\WebShellKitchenSink.Catalog\DataForms\Charts folder.

Chart Series Attributes

The color of a chart series can be defined within a Series element via the Color attribute. A chart can have several series of data points charted, each with their own color. The default color is orange. A PointSize attribute value can be defined on the Series element, provided points are displayed. PointSize valid options include ExtraSmall, Small, Medium (default), Large, and ExtraLarge. Points will not be displayed if the ShowPoints attribute is set to false (default). ShowPoints applies to line and area graphs.

For demonstrations, be sure to check out our Kitchen Sink Videos and UI Widget Videos.