Select your user interface: Web Shell Smart Client

Use a WebAPIClient DLL to Retrieve a Data List

When the times comes to integrate your custom application with an Infinity application, the need will arise where you need to retrieve and iterate through a list of data from the Infinity database. This article shows you how to locate the assemblies that contain the Infinity features to automate. This article touches on concepts central to data lists such as context, security, and data list filters. If you are new to the Infinity, check out the following articles:

• Use WebAPI to Retrieve a Data List

• Using a WebAPIClient DLL to Retrieve a Data List

• Overview of Infinity Data Lists

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 SDK and can be found by filtering your SDK\DLLReferences folder on Blackbaud.AppFx.*.WebAPIClient.dll. These assemblies contain strongly typed wrapper classes that leverage the primary Infinity web service: AppFxWebService.asmx.

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.

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.

To get my WebAPIClient project going, I created a WinForm project (does not have to be a WinForm project) with Visual Studio 2008 and added the following Blackbaud references to the project. Your custom .NET project needs to take a dependency on one or several of the Blackbaud.AppFx.*.WebAPIClient.dll assemblies. Below, I added a reference to the Blackbaud.AppFx.Constituent.Catalog.WebApiClient.dll, which in turn depends on Blackbaud.AppFx.WebApi.dll, Blackbaud.AppFx.dll, and Blackbaud.AppFx.XMLTypes.dll.

Keep in mind that you can browse the application features to find the appropriate feature. In reviewing a feature's metadata page, you can use the API tab to locate the appropriate WebApiClient.dll assembly within the Client-side Web API group.

So, onto the code. Enter a constituent Lookup ID and click the Search button.

The code uses a search list and a View Data Form to retrieve the constituent's name and addresses.

The code utilizes the Contact Information List's GetRows method to retrieve the addresses via RetrieveAddress().

   Private Sub RetrieveAddress()
        If ConstituentID = Nothing Then
            DataGridViewAddress.DataSource = Nothing
            DataGridViewAddress.Refresh()
        Else
            Dim AddressItems() As DataLists.Constituent.ContactInformationListRow
            Dim Filter As New DataLists.Constituent.ContactInformationListFilterData

            Filter.INCLUDEADDRESSES = True
            Filter.INCLUDEFORMER = True
            Filter.INCLUDEEMAIL = False
           Filter.INCLUDEPHONES = False

            AddressItems = DataLists.Constituent.ContactInformationList.GetRows(ServiceProvider, ConstituentID, Filter)

            ' Fill in the data grid with a List
            Dim list = New List(Of Address)
            For Each AddressItem As DataLists.Constituent.ContactInformationListRow In AddressItems
                list.Add(New Address(AddressItem.ID.ToString, AddressItem.CONTACTINFO, AddressItem.TYPE))
            Next

            DataGridViewAddress.DataSource = list
            DataGridViewAddress.Columns(0).Visible = False
            DataGridViewAddress.Columns(1).Width = 210
            DataGridViewAddress.Columns(2).Width = 115
            DataGridViewAddress.Refresh()
        End If
    End Sub

Take a closer look at the GetRows method call above by reviewing its arguments list.

Blackbaud.AppFx.WebAPI.AppFxWebServiceProvider

For the first argument, we provide a variable named ServiceProvider, which is of type Blackbaud.AppFx.WebAPI.AppFxWebServiceProvider. As part of the initialization of ServiceProvider, we provide a URL to the AppFxWebService.asmx web service, the name of the database key, and the name of our custom application client.

ServiceProvider = New AppFxWebServiceProvider("http://localhost/BBInfinityPROD2.7.1633.0/appfxwebservice.asmx", _
                                                     "BBInfinityPROD2.7.1633.0", _
                                                     "AddAddressWinFormWebAPIClient")

Next, we must provide credentials for the service provider. In this code sample, we provide the default credentials that represent the system credentials of the application. The DefaultCredentials property applies only to NTLM, negotiate, and Kerberos-based authentication. DefaultCredentials represents the system credentials for the current security context in which the application is running. For a client-side application like this sample application, it is the Windows credentials (user name, password, and domain) of the user running the application. For ASP.NET applications, the default credentials are the user credentials of the logged-in user, or the user being impersonated. Another option is to select DefaultNetworkCredentials, which gets the network credentials of the current user or application.

ServiceProvider.Credentials = System.Net.CredentialCache.DefaultCredentials

Context

Since the data list returns contact information for a constituent, we must provide context in the form of a constituent ID to the data list as an argument within the call to GetRows.

Filter

Normally this data list returns addresses, emails, and phone numbers. However, we can manipulate the data list''s filter to narrow the list of data returned. The addresses are returned to an array of ContactInformationListRow.

After the data list is retrieved into the array, we iterate or loop through the list building up a generic list of type address. After the list is populated, we provide the list as the DataGridView's data source.

AddressItems = DataLists.Constituent.ContactInformationList.GetRows(ServiceProvider, ConstituentID, Filter)

' Fill in the data grid with a List
Dim list = New List(Of Address)
For Each AddressItem As DataLists.Constituent.ContactInformationListRow In AddressItems
    list.Add(New Address(AddressItem.ID.ToString, AddressItem.CONTACTINFO, AddressItem.TYPE))
Next

DataGridViewAddress.DataSource = list

Source Code

The source code for this sample can be found here: AddAddressWinFormWebAPIClient.dll_.zip.