Display a Search List from a Third-party Application

This article demonstrates how to call a search list from a custom .NET WinForm client application, and then use the ID returned from the search list to call upon a View Data Form. This example demonstrates the use of the DataFormWebHostDialog class within the Blackbaud.AppFx.UIModeling.DataFormWebHost namespace that comes with the Infinity SDK. The Blackbaud.AppFx.UIModeling.DataFormWebHost.dll assembly is located within the SDK\DLLReferences folder.

The source code for this example can be found at the bottom this article.

One of the cool things about the Blackbaud SDK is all of the Visual Studio templates to create projects and Infinity features/specs. One such template is the "Web API Client Template."

This template helps you to jump start a project by automatically creating a reference to Blackbaud.AppFx.WebApi, Blackbaud.AppFx.XMLTypes, Blackbaud.AppFx.dll, among others. Here is a newly created project based on this template and the resulting assembly references.

The template stubs out some code within Module1.vb to display a search list outside of the Infinity shell through ShowSearchExample().

Private Sub ShowSearchExample()

        'to show a data form, use the DataFormWebHostDialog component
        Dim form = New SearchFormWebHostDialog
        form.ServiceUrlBasePath = serviceUrlBasePath
        form.DatabaseName = databaseName
        form.ApplicationTitle = applicationTitle

        'supply credentials to authenticate
        'form.Credentials = New System.Net.NetworkCredential("<username>", "<password>", "<domain>")
        ' or
        form.Credentials = System.Net.CredentialCache.DefaultCredentials

        'indicate the Id of the search form to show (in this example, 
        'the "Constituent Search" feature is used)
        form.SearchListId = New Guid("23C5C603-D7D8-4106-AECC-65392B563887")

        'show the search
        If form.ShowDialog() = Windows.Forms.DialogResult.OK Then
            MsgBox(String.Format("You selected a record with id = {0} and translation of {1}", _
                                 form.SelectedRecordId, form.SelectedRecordTranslation))
        End If

End Sub

Instead of the API code being in Module1.vb, I rearranged the code into a VB class file called BlackbaudInfinityUIHelper.vb. I rewired the module1.vb to open a WinForm at startup. Here is the new, modified Module1.vb:

Module Module1

    'update the values for your system settings
    Public Const serviceUrlBasePath As String = "http://localhost/BBInfinityPROD2.7.1633.0/"
    Public Const serviceUrl As String = "http://localhost/BBInfinityPROD2.7.1633.0/AppFxWebService.asmx"
    Public Const databaseName As String = "BBInfinityPROD2.7.1633.0"
    Public Const applicationTitle As String = "Custom Application"

    Sub Main()
        Dim Form As New Form1
        Form1.ShowDialog()
    End Sub

End Module

When the app starts, Form1.vb appears. The user clicks the Search and Display Constituent as Infinity Form button and btnSearchConstituent_Click is called….

Private Sub btnSearchConstituent_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnSearchConstituent.Click
        Try
            Dim SearchResult As BlackbaudInfinityUIHelper.SearchListResult

            'the "Individual Search" feature is used
            SearchResult = BBUIHelper.ShowSearchList("4685952f-6964-486c-9acd-5560a8a30862")

            If Not SearchResult Is Nothing Then
                'Individual Summary View Form
                Me.txtConstituentID.Text = SearchResult.SelectedRecordId
                Me.txtConstitName.Text = SearchResult.SelectedRecordTranslation.ToString
                BBUIHelper.ShowViewDataForm("ce461c96-9a71-4279-a842-6f596956d470", SearchResult.SelectedRecordId)
            End If

        Catch ex As Exception
            MsgBox(ex.Message, MsgBoxStyle.Exclamation, "error")
        End Try
    End Sub

…and a call is made to the BlackbaudInfinityUIHelper.ShowSearchList().

Friend Function ShowSearchList(ByVal SearchListID As String) As SearchListResult
       'to show a data form, use the DataFormWebHostDialog component
       Dim form = New SearchFormWebHostDialog
       form.ServiceUrlBasePath = _serviceUrlBasePath
       form.DatabaseName = _databaseName
       form.ApplicationTitle = _applicationTitle

       'supply credentials to authenticate
       form.Credentials = _credentials

       'indicate the Id of the search form to show (in this example, 
       'the "Constituent Search" feature is used)
       form.SearchListId = New Guid(SearchListID)

       'show the search
       If form.ShowDialog() = Windows.Forms.DialogResult.OK Then

           Return New SearchListResult(form.SelectedRecordId, form.SelectedRecordTranslation)
       Else
           Return Nothing
       End If
   End Function

The search list feature is called and displayed from this third-party/non-Infinity shell application.

After the user selects a constituent, we capture the returned constituent ID and translation (yellow highlight below):

'show the search
        If form.ShowDialog() = Windows.Forms.DialogResult.OK Then

            Return New SearchListResult(form.SelectedRecordId, form.SelectedRecordTranslation)
        Else
            Return Nothing
        End If

The record ID and translation are then displayed on Form1.vb at the top of the form.

Private Sub btnSearchConstituent_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnSearchConstituent.Click
        Try
            Dim SearchResult As BlackbaudInfinityUIHelper.SearchListResult

            'the "Individual Search" feature is used
            SearchResult = BBUIHelper.ShowSearchList("4685952f-6964-486c-9acd-5560a8a30862")

            If Not SearchResult Is Nothing Then
                'Individual Summary View Form
                Me.txtConstituentID.Text = SearchResult.SelectedRecordId
                Me.txtConstitName.Text = SearchResult.SelectedRecordTranslation.ToString
                BBUIHelper.ShowViewDataForm("ce461c96-9a71-4279-a842-6f596956d470", SearchResult.SelectedRecordId)
            End If

        Catch ex As Exception
            MsgBox(ex.Message, MsgBoxStyle.Exclamation, "error")
        End Try
    End Sub

Next a View Data Form is opened….

Private Sub btnSearchConstituent_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnSearchConstituent.Click
        Try
            Dim SearchResult As BlackbaudInfinityUIHelper.SearchListResult

            'the "Individual Search" feature is used
            SearchResult = BBUIHelper.ShowSearchList("4685952f-6964-486c-9acd-5560a8a30862")

            If Not SearchResult Is Nothing Then
                'Individual Summary View Form
                Me.txtConstituentID.Text = SearchResult.SelectedRecordId
                Me.txtConstitName.Text = SearchResult.SelectedRecordTranslation.ToString
                BBUIHelper.ShowViewDataForm("ce461c96-9a71-4279-a842-6f596956d470", SearchResult.SelectedRecordId)
            End If

        Catch ex As Exception
            MsgBox(ex.Message, MsgBoxStyle.Exclamation, "error")
        End Try
    End Sub

… and BlackbaudInfinityUIHelper.ShowViewDataForm() displays Individual Summary View Form for the selected constituent:

Friend Sub ShowViewDataForm(ByVal DataFormInstanceID As String, ByVal RecordID As String, Optional ByVal ContextRecordID As String = "")
        'to show a data form, use the DataFormWebHostDialog component

        Dim form = New DataFormWebHostDialog
        form.ServiceUrlBasePath = _serviceUrlBasePath
        form.DatabaseName = _databaseName
        form.ApplicationTitle = _applicationTitle

        'supply credentials to authenticate
        'form.Credentials = New System.Net.NetworkCredential("<username>", "<password>", "<domain>")
        ' or
        form.Credentials = _credentials

       'indicate the data form instance Id of the form to show         form.DataFormInstanceId = New Guid(DataFormInstanceID)

        'specify the context record id for "add" forms that required it
        If ContextRecordID Is Nothing Then
        Else
            form.ContextRecordId = ContextRecordID
        End If

        'specify the record id for "edit" or "view" forms that require it
        form.RecordId = RecordID

        form.ShowDialog()

    End Sub

Attachment: DisplayingaSearchList.zip.