blog banner

Data Forms: Use Value List Fields on Add Data Forms with Blackbaud CRM SDK

THE BLACKBAUD CRM SDK video series. In this video, we’ll explore how to use a value list
field with a stored procedure-based add data
form. We’ll demonstrate how to create an add data
form spec in Visual Studio that uses a value list
descriptor. After that, we can implement the feature in
Blackbaud CRM and observe its behavior. To get started with value list fields, let’s go to
Visual Studio to create an add data form spec in
our custom catalog project for the video series. In the Solution Explorer, we right-click the Demo
folder, select Add, and then select New Item. On the left side of the Add New Item screen, we
select the Blackbaud AppFx Catalog category. Then in the center of the screen, we select the
Add Data Form Template Spec (SP) template. Next, we update the default name in the Name
field. For this demonstration, we’ll use
“Demo.ValueListField.Sp.Add.xml.” By default, the spec includes the XML elements
and attributes that we need for a basic add data
form. It also includes stubbed-out stored procedures
to load default values when the form opens and
to save data from the form to the database. For the Name attribute, we add “(custom)” to
the default value to avoid any possible future
naming conflicts with Blackbaud features. We also add “(custom)” to the default values for
the Description, RecordType, and
SecurityUIFolder attributes. Then we add the NameUIOverride attribute to
provide a display name for the form in Blackbaud
CRM that does not include “(custom).” We also add “(with value list field)” to the Name
and NameUIOverride attributes to indicate that
this form demonstrates value list fields. The spec’s SPDataForm element includes
LoadImplementation and SaveImplementation
elements with stubbed-out stored procedures. The system uses the Transact-SQL code within
these elements to create or alter stored
procedures in the database. Since our sample form does not load default
values, we do not need the LoadImplementation
element. Since this video’s focus is value list fields, we
can reuse a stored procedure from an existing
add form in the SaveImplementation element. We open Demo.Sp.Add.xml and copy the
Transact SQL stored procedure within its
SaveImplementation element. Then we return to our new add data form spec. We delete the LoadImplementation element, and
then we overwrite the SaveImplementation
element’s stubbed-out stored procedure. After the SPDataForm element, the spec
includes the Context element. Since our form
does not require context, we delete this element Next, the spec includes a FormMetaData
element that describes presentation information
such as the fields to display on the form. The FormField elements within the
FormMetaData element describe how to
represent individual fields on the data form. For our new add data form, we want to use the
same form fields as the existing add data form
that we copied the save procedure from, so we return to that add data form spec and
copy its FormMetaData element. Then we return to the new add data form spec
and overwrite its FormMetaData element. With the FormField elements in place, we want
to update the RATING field so the form presents
a dropdown list of possible values to end users. To provide metadata about the form field so that
we can constrain to a specific set of values, we
add the ValueList element. Then to create the list of values, we add the
Items element. Within the Items element, we add an Item
element to declare a valid value for the form field. Finally, we add the Value element within the
Item element to specify that value. We specify the value as a string, but it must be
in a format that is convertible to the form field’s
data type. For our example, we enter “2.” To flesh out the value list, we then copy the Item
element and its child Value element and paste
four copies within the Items element. And we update the values to “4,” “6,” “8,”and
“10.” If we load the spec into Blackbaud CRM at this
point, the LoadSpec utility returns an error
because the procedure name is not unique. The name in the SPName attribute must be the
same as in the first line of the Transact-SQL’s
CREATE PROCEDURE statement. To ensure that the name is unique, we append
“_VALUELISTFIELD” to indicate the procedure is
for a form that demonstrates value list fields. After these changes to the add data form spec,
we are ready to save it and load it into
Blackbaud CRM. After we load the spec, it is available in
Blackbaud CRM, but we still need to create a
task to access the form. We right-click the Demo folder in the Solution
Explorer, select Add, and then select New Item. On the Add New Item screen, we select the
Blackbaud AppFx Catalog category and the
Task Spec template. Then we update the name to
“Demo.ValueListField.Sp.Add.Task.xml” and
click Add. By default, the spec includes an XML element
and attributes for a basic task, and we can
update them as necessary. First, we update the Name and Description
attributes. We open the task spec for the add data form
spec that we copied the save procedure from,
and we copy the name and description values. After we paste the values in our new task spec,
we add “(with VL field)” to indicate this task
opens a form that demonstrates a value list field. Next, we need the GUID from our Demo
functional area spec in the FunctionalAreaID
attribute. We open the functional area spec to copy the
GUID from its ID attribute. Then we return to the task spec and paste the
GUID into the FunctionalAreaID attribute. We also update the Sequence attribute to 30
and remove the ImageKey attribute. Since we want the task to display an add data
form instead of a page, we can remove the
ShowPage element. We replace it with the ShowAddDataForm
element and add the DataFormID attribute,
which requires the GUID for the data form. We open the spec for our add data form and
copy the GUID in the DataFormInstanceID
attribute. Then we return to the task spec and paste the
GUID into the DataFormID attribute. After we close the ShowAddDataForm element,
we can save the spec and load it into Blackbaud
CRM with the LoadSpec utility. With the spec in place, we can go to Blackbaud
CRM to view our new features in the custom
Demo functional area. In the Demo functional area, we click our new
Add a demo (SP with VL field) task to access
the new add data form. We can click the dropdown icon in the Rating
field to access the value list we specified for the
field. Then we can enter additional test data for a new
record and click Save to add it to the database.

Leave a Reply

Your email address will not be published. Required fields are marked *