Blackbaud CRM™ has a rich library of specs which allow your organization to easily extend the software to add and modify functionality. At the heart of most CRM customizations is the XML spec architecture, which provide a neat, human-readable definition allowing great power with very traditional coding.
Despite this power, organizations will often need to modify CRM functionality at a deeper level, and the UI Model provides architecture for developers to “get under the hood” and work with real CLR code, often to extend business logic and handle UI events.
Prerequisite
Blackbaud Infinity SDK™ basic training, knowledge of Microsoft Visual Studio™ with some VB.NET of C# experience.
When working in VB/C# in the UI Model, it’s frequently the case that a developer will want to call a custom data form, view, etc. from code. As these specs, when loaded, become available as web service endpoints, a developer with web service experience could access them through regular service references.
However, when creating a custom data form, view, etc, that will be called from code, it’s helpful to run a utility called BBMetalWeb™, which may be unfamiliar to your organization if your developers have only had basic SDK training. BBMetalWeb™ will parse an XML spec, and create a .NET class which can be used as a first class object in code. This means when you’re calling the View form that was just created, you have the nice early-bound .NET “dot” notation for properties, and intelligence, so coding and step-through debugging are a lot easier.
Create CodeGen Class Library Project
Although you could just create code-generated classes and bring them into your UI Model project, we feel it’s better practice to create a new project (that would sit alongside the existing catalog and UI Model projects) – a class library called “YOURPROJECTNAME.CodeGen”
For our purposes here, let’s say we have a hypothetical View Data Form which works with the Attribute Category table. (We will have a separate blog post for this later today, so stay tuned!)
To do this, first go to your catalog project and make sure your View Data Form is loaded (use Load Spec in VS “Tools”), then select BBMetalWeb™ from Tools. You’ll probably be prompted for the location to the web service, as well as the DB name.
Select View Data Forms and then in the Record Type tab, select “Attribute Category”.
BBMetalWeb™ will create a new class in your catalog project. (You may need to toggle “view all files” to see it). Our hypothetical file “AttributeCategoryGetDefaultViewDataForm.codegen.vb” is the one you’re interested in, although a couple others may come along for the ride.
We won’t be able to use AttributeCategoryGetDefaultViewDataForm.codegen.vb in the catalog project. The best practice here will be to create a new project called MyProject.CodeGen, and the type should be “class library”. You can simply drag the code gen file into your new project, then delete the entire “ViewForms” folder that got created in the catalog. One thing to note is that you’ll need some references added to the Code Gen project.
Back to the UI Model Project
From the UI Model project, add a reference to your Code Gen project.
From here, you’ll want code to create a provider, which will provide the plumbing to our custom View Form:
Private Const serviceUrlBasePath As String = "http://localhost/crm40/"
Private Const databaseName As String = "BBInfinity_BB_3.0"
Private Shared _provider As AppFxWebServiceProvider
Friend Shared Function GetProvider() As AppFxWebServiceProvider
If _provider Is Nothing Then
_provider = New Blackbaud.AppFx.WebAPI.AppFxWebServiceProvider
_provider.Url = String.Concat(serviceUrlBasePath, "appfxwebservice.asmx")
_provider.Database = databaseName
_provider.Credentials = System.Net.CredentialCache.DefaultCredentials
'_provider.Credentials = New System.Net.NetworkCredential("USERNAME", "PASSWORD", "DOMAIN")
End If
Return _provider
End Function
Your call to the View Form becomes very simple:
Dim provider = GetProvider()
Dim data As BrightVine.CustomFx.AttributeDefaults.CodeGen.ViewForms.AttributeCategory.AttributeCategoryGetDefaultViewDataFormData = BrightVine.CustomFx.AttributeDefaults.CodeGen.ViewForms.AttributeCategory.AttributeCategoryGetDefaultViewDataForm.LoadData(provider, ATTRIBUTECATEGORYID.Value.ToString)
From here, you’ll have an object named “data” where you can use regular dot-notation to pull out all the custom fields from the View Form, as first class properties.
We hope this tutorial helps you get going with code generation using BBMetalWeb. If you have any questions you can contact me at christopher.keene@brightvinesolutions.com and I’ll be glad to help.