Modify the Spec Header and Add Parameters

Previous: Add the Project and Global Change Spec

Step 1 - Review the Global Change Spec XML and remove the error within generated CLR class file.

Review the boilerplate GlobalChangeSpec XML file and vb.net CLR class file.

Warning: You may notice an error within the generated class file within the ProcessGlobalChange() function on the return type Server.AppCatalog.AppGlobalChangeResult.

Modify the namespace within the ProcessGlobalChange function's return type by removing "Server" from the beginning of the namespace of the return type. After adjusting the CLR class should look something like this:

Imports Blackbaud.AppFx.Server

Public NotInheritable Class AddressCoordinateTimeZoneGlobalChange
    Inherits AppCatalog.AppGlobalChangeProcess

    Public Overrides Function ProcessGlobalChange() As AppCatalog.AppGlobalChangeResult

    End Function

End Class

Step 2 - Modify the spec header

Let's switch over to the AddressCoordinateTimeZone.GlobalChange.xml spec file and modify the GlobalChangeSpec element. We will modify the Name, Description, Author, DisplayName, and GlobalChangeFolder attributes to look something like this. Your ID attribute value will vary since the catalog item template defaults each new spec with a unique GUID value.

Tip: Note the use of (Custom) to help future-proof the display name of our spec against potential upgrade conflicts. After it is loaded into the catalog system (database), the GlobalChangeSpec will be stored within the GlobalChangeCatalog table that contains a unique index on the DisplayName column. For spec naming and coding standards, see Best Practices.

Step 3 - Add UI Parameters by modifying the ParametersFormMetaData element

With the AddressCoordinateTimeZone.GlobalChange.xml spec file open, add some parameters for the user interface. We are going to modify the ParametersFormMetaData element 's FormMetaData child element by adding three form fields. Each form field represents a user interface parameter. When the end user configures a new global change instance from a definition, the user will supply the values for each parameter using these form fields.

Note: For more information on parameters within a global change, see the ParametersFormMetaData element within Exploring a GlobalChangeSpec.

We are going to have three parameters for our global change. One parameter will represent a selection of constituents to process. A second parameter will represent whether we wish to process only Geocodes for a constituent's primary address. A third parameter determines whether to process Geocodes for addresses that are unchanged since last being assigned a Geocode.

Leverage a Selection as a Parameter

A common situation a developer will run into is the necessity to restrict the row set to a specified set of records. A parameter value within a global change instance can point to a selection which specifies the set of records. A selection is a set of record IDs for a particular record type, like the Constituent record type. A selection can be a static (unchanging) list of record IDs or it can be a dynamic list of record IDs which are derived when called upon by a global change.

Tip: Much like Global Change, selections are commonly used as an input parameters for business processes.

Selections can be created in a variety of ways. Selections can be created using Blackbaud’s query tool by first creating either an ad-hoc query or smart query and then saving the query results as a selection. If you are unfamiliar with creating selections via query, check out the Query and Export Guide. Selections can be created as the result of a business process run to represent the rows processed or created. Using the SDK, selections can be added by creating a SQLFunctionSpec that contains a CreateSelection element.

Add the Form Field for the Selection

Within the global change spec, add the following FormField tag to your FormMetaData element. This will add a user interface control on the parameter's section of the global change instance screens used to manage global change instance. This user interface control will allow the end user to search for and choose a selection with a record type of Constituent. This form field leverages a the Selection Search by record type search list that ships with Blackbaud CRM. The FormField is required. Note the use of the FormFieldOverrides tag whereby we default the RECORDTYPE field to a value of "Constituent" and mark the field as read only. Thus ensuring the user searches for only "Constituent" related selections.

<common:FormField Caption="Selection" DataType="Guid" 
	Description="Constituent selection containing the geocoded addresses which should be timezoned" 
	FieldID="IDSETREGISTERID" 
	Required="true">
	<common:SearchList SearchListID="1F0E603C-1C55-4E1E-8218-BDB877B2CBE8" EnableQuickFind="true">
		<common:FormFieldOverrides>
			<common:FormFieldOverride FieldID="RECORDTYPE" DefaultValueText="Constituent" ReadOnly="true" />
		</common:FormFieldOverrides>
	</common:SearchList>
</common:FormField>

Add the "Only process primary address geocodes" Form Field

Within the global change spec, add the following FormField tag below the selection form field within to the FormMetaData element. This will provide a checkbox for indicating whether the global change processing logic should only focus on a constituent's primary address records that contain geocodes or all of a constituent's address records that contain Geocodes.

<common:FormField Caption="Only process primary address geocodes" DataType="Boolean" 
	Description="Determines whether to process all Geocodes for a constituent's address or only the Geocodes for a constituent's primary address." 
	FieldID="ONLYPRIMARY" />

Add the "Only process new and changed address geocodes" Form Field

Next, add the following FormField tag below the previous form field within to the FormMetaData element. This will provide another checkbox to indicate whether to process Geocodes for addresses that are unchanged since last being assigned a Geocode. This will help increase the performance of the global change by only focusing on records that have been modified since the last time the global change instance was run.

Tip: The GlobalChange table's LastRunOn column is used to hold a datetime value of the last time the instance was run.

Step 4 - Remove or comment out the FormUIComponent tag

Within the GlobalChangeSpec, remove or comment out the FormUIComponent tag from ParametersFormMetaData. With the tag removed, the system will render a simple user interface containing our three form fields.

Note: The FormUIComponent tag is a relic from the ClickOnce Smart Client user interface days. The existence of FormUIComponent signifies that a conversion to a UI Model is necessary to view the feature in the Web Shell user interface. You don't want to use FormUIComponent since the ClickOnce Smart Clientultimately will be retired and replaced by the Web Shell user interface. For more information, see Frequently Asked Questions in the User Interface section of the User Guides.

Below is look at the bottom half of our spec. At this point your GlobalChangeSpec's ParametersFormMetaData element should include the three form fields and look something like this. Note that I have replaced the three template FormFIeld elements that are provided when you created the spec from the catalog item template via the SDK. And I have commented out the FormUIComponent tag.

Our new form fields provide user input parameters for our global change.

Next: Add a Custom Table