Select your user interface: Web Shell Smart Client

Blackbaud.AppFx.*.WebAPIClient.dlls

Note: For examples that use Blackbaud.AppFx.*.WebAPIClient.dlls, see Blackbaud.AppFx.*.WebAPIClient.dll API.

Note: Blackbaud.AppFx.*.WebAPIClient.dllsis a wrapper API for AppFxWebService targeted to .NET developers.

About two years after the introduction of the BizOps endpoints, the Blackbaud core platform team decided to create .NET client side assemblies that organize related features together. Blackbaud.AppFx.*.WebAPIClient.dlls contain strongly typed wrapper classes that make the web service calls automatically and make the platform's structure easy to navigate. These assemblies are included with the Infinity SDK and can be found by filtering your SDK\DLLReferences folder on Blackbaud.AppFx.*.WebAPIClient.dll. In my opinion, if you use the .NET platform to create an integration application that communicates with an Infinity application, this is the preferred API for its ease of use and minimal amount of code to get something accomplished. As a side note, the Blackbaud workflow activities that are used internally by Infinity Workflow use the WebAPIClient.dll classes. This reiterates the preference for the WebAPIClient.dlls as the preferred API for .NET code. Finally, as a matter of practicality, any feature that is not included within a WebApiClient.dll can be supplemented with a reference to the AppFxWebService.asmx or its cousin the Blackbaud.AppFx.WebAPI.dll.

These assemblies contain strongly typed wrapper classes that leverage the primary Infinity web service: AppFxWebService.asmx. These assemblies organize the following types of specs together:

• Code tables

• Data lists

• Record views (view data forms)

• Record creates (add data forms)

• Record updates (edit data forms)

• Delete record operations

• Record searches (search lists)

These Blackbaud.AppFx.*.WebAPIClient assemblies have a dependency on the .NET Blackbaud.AppFx.WebAPI.dll.

The main advantage to the Blackbaud.AppFx.*.WebAPIClient.dlls is the organization of features into a namespace hierarchy. Visual Studio's Intellisense makes navigating the namespace hierarchy very easy.

Add Data Forms

Calling an Add Data Form is pretty simple. Create new form data object, load data defaults into the data object, update the form fields on the data object with data from the UI, and the save the modified data.

View Data Forms

Calling a View Data Form is very simple. First grab the strongly typed form data object, such as ViewForms.Constituent.ConstituentFirstNameLastNameViewFormData in the code sample below. Next, LoadData is called to retrieve the form's data. After form field data is retrieved, you can view it using strongly typed properties of the form data, such as FIRSTNAME and KEYNAME below.

Search Lists

Using a search list is a matter of grabbing the appropriate filter data object from the WebAPIClient's SearchLists namespace. Below, you can see we use the IndividualSearchFilterData class from the Blackbaud.AppFx.Constituent.Catalog.WebApiClient.SearchLists.Constituent namespace. Next, we set values on the properties of the search filter. You can see we are providing a constituent lookup ID, and narrowing our results to only active individuals. The filter is passed to the GetIDs method. The results of the method call are placed into a string array. If the search was successful, then we extract the constituent ID from the results.

Record Operations

The API for record operations is very simple – each record operation maps to a single procedure call. The following code sample deletes an address from a datagridview.

Simple Data Lists

Simple data lists are typically used to load drop-down combo boxes in the application. You can access simple data lists from the following namespace:

Blackbaud.AppFx.WebAPI.SimpleDataLists

Data Lists

Each data list returns an enumerable list of strongly-typed objects, which makes for a very natural API. Use an array of data list rows to contain the rows returned from the call to the data list. Optionally, a filter object defines how to narrow down the rows. This example requires context with a record type of Constituent, so GetRows is called and the ConstituentID is passed for the context. The columns returned in the data list are strongly typed … nice.

Note that "top-level" data lists and "simple" data lists are also located within the DataLists namespace. Top-level data lists are data lists that have no context type, and thus are not associated with a specific record type.

Code Tables

The code tables API is organized within the CodeTables namespace by code table name. Each code table exposes commonly used methods to work with entries for the code table.

Security

When you create your connection to the Infinity web service, you can use any set of Windows credentials you would like. By doing so, the security applied to that login is applied to this connection. This is the same security model as that applied by the Blackbaud smart client.

Dim ServiceProvider As AppFxWebServiceProvider 
ServiceProvider = New AppFxWebServiceProvider("http://localhost/BBInfinityPROD2.7.1633.0/appfxwebservice.asmx", _ 
                                                     "BBInfinityPROD2.7.1633.0", _ 
                                                     "AddAddressWinFormWebAPIClient") 
ServiceProvider.Credentials = System.Net.CredentialCache.DefaultCredentials
 
Me.btnSearch.Enabled = EvalSearchCriteriaDisplay() 

        ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 
        'Initialize States 
        'Using the GUID that identifies the State Abbreviation List (Simple Data List_ 
        'Retrieve a listing of states and populate the combo box with a key, value pair. 
        ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 
        Dim States() As SimpleDataListsData 
        States = SimpleDataLists.LoadSimpleDataList(ServiceProvider, New System.Guid("7fa91401-596c-4f7c-936d-6e41683121d7"))

Each feature type (data lists, data forms, record operations, etc.) can be secured through configuration within the application. Application-defined security on a feature is respected by all of the APIs listed above. If someone does not have rights to access a feature, they can not access the feature through the APIs listed above. Each feature type has a feature page that you can use to manage security for the feature. A typical step in real world use of the API is to first secure the feature. By navigating to a feature page, you can simply add the feature to a security role.

For more information about how to secure Infinity features, see Add Features to Infinity System Role.

Create a Client .NET Project That Utilizes Blackbaud.AppFx.*.WebAPIClient.dlls

Let's create a simple Win Form .NET project that adds addresses for a constituent record.

First, we need to find the feature that adds an address. Looking at the Constituent page in Design Mode, we can navigate to the page's metadata and find the feature that is utilized by the Add action within the Contacts tab on the page: Address Add Form 2. Clicking on the Go to data form instance definition button takes us to the metadata for the Address Add Form 2.

Below, you can see the assembly name that contains the class: Blackbaud.AppFx.Constituent.Catalog.WebApiClient.dll.

So, the new .NET Win Form project should have the following Blackbaud .NET assemblies referenced. Note, the path to the Blackbaud .NET assemblies depend on where you installed the Infinity SDK on your development machine.

Pros of the Blackbaud.AppFx.*.WebAPIClient.dlls

• Strong support for .NET development

• Organization of features into a namespace

• Easy to use with minimal code

Cons of the Blackbaud.AppFx.*.WebAPIClient.dlls

• Does not support non-Windows development because of dependency on .NET assemblies.

• Not every Infinity feature type is represented

AddAddressWinFormWebAPIClient.dll_.zip

Use a WebAPIClient DLL to Retrieve a Data List