Guides (SDK /API) | Technical Reference | BBDN | How-to Documentation

Code the Add the Pledge Logic (Revenue Records)

Code sample project: Custom Pledge Form

1. Open CustomPledgeFormDisplay.ascx for editing in Designer.

   

2. Double-click the Pledge button. CustomPledgeFormDisplay.ascx.vb appears in the editor with the handler for clicking the button. The Sub procedure should look like this:

       Protected Sub ButtonPledge_Click(ByVal sender As Object, ByVal e As EventArgs) Handles ButtonPledge.Click
           Try
               If MyContent.OnlyWriteToCustomPledgeRecord Then
                   AddCustomPledgeRecord()
               ElseIf API.Users.CurrentUser.IsAnonymous Then
                   AddCustomPledgeRecord()
               Else
                   AddCustomPledgeRecord()
               End If
           Catch ex As Exception
           End Try
       End Sub

   There should also be a Sub procedure called AddCustomPledgeRecord.

3. Add a new Sub procedure after AddCustomPledgeRecord called AddRevenuePledgeRecord.

       Private Sub AddRevenuePledgeRecord()
   
       End Sub

4. Adjust the button click handling Sub procedure to call AddRevenuePledgeRecord when the user is logged in and is connected to a Blackbaud CRM constituent. Otherwise write to the custom pledge record.

               If MyContent.OnlyWriteToCustomPledgeRecord Then
                   AddCustomPledgeRecord()
               ElseIf API.Users.CurrentUser.IsAnonymous Then
                   AddCustomPledgeRecord()
               Else
                   If API.Users.CurrentUser.BackOfficeGuid = System.Guid.Empty Then
                       AddCustomPledgeRecord()
                   Else
                       AddRevenuePledgeRecord()
                   End If
               End If

   For troubleshooting purposes, you can surround this with a Try - Catch block that catches Blackbaud-specific exceptions. For example:

           Try If MyContent.OnlyWriteToCustomPledgeRecord Then
                   AddCustomPledgeRecord()
               ElseIf API.Users.CurrentUser.IsAnonymous Then
                   AddCustomPledgeRecord()
               Else
                   If API.Users.CurrentUser.BackOfficeGuid = System.Guid.Empty Then
                       AddCustomPledgeRecord()
                   Else
                       AddRevenuePledgeRecord()
                   End If
               End If
           Catch ex As Blackbaud.AppFx.WebAPI.AppFxWebServiceException When ex.DataFormErrorInfo IsNot Nothing AndAlso ex.DataFormErrorInfo.ErrorCode = Blackbaud.AppFx.WebAPI.ServiceProxy.DataFormErrorCode.RecordNotFound
           End Try 

5. Using classes provided by Blackbaud.AppFx.Fundraising.Catalog.WebApiClient.dll, create an object to hold the form data.

           Dim RevenuePledgeData As New Blackbaud.AppFx.Fundraising.Catalog.WebApiClient.AddForms.Revenue.PledgeAddFormData()

6. Load default values into the form data.

           RevenuePledgeData = Blackbaud.AppFx.Fundraising.Catalog.WebApiClient.AddForms.Revenue.PledgeAddForm.LoadData(Me.API.AppFxWebServiceProvider)

7. Populate the CONSTITUENTID field with the GUID for the currently logged in user. This is accessible through the Blackbaud Internet Solutions API.

           RevenuePledgeData.CONSTITUENTID = Me.API.Users.CurrentUser.BackOfficeGuid

8. Use today's date for the DATE field.

           RevenuePledgeData.DATE = DateTime.Today

9. Set AMOUNT to the user-entered value.

           RevenuePledgeData.AMOUNT = TextBoxAmount.Text

10. Set POSTSTATUSCODE to the code for Do Not Post.

            RevenuePledgeData.POSTSTATUSCODE = Blackbaud.AppFx.Fundraising.Catalog.WebApiClient.AddForms.Revenue.PledgeAddFormData.POSTSTATUSCODEVALUES.Do_Not_Post

11. Set STARTDATE in the same way as DATE.

            RevenuePledgeData.STARTDATE = DateTime.Today

12. These pledges will only be handled as US dollars, so create a GUID instance for that ID. The ID was determined by observing another pledge transaction in SQL Server Management Studio.

            Dim USDollarCurrencyID = New System.Guid("ba9803bc-f104-4150-bd34-d40d0f5b1f27")

13. Pledges require designations and designations are organized as splits. Create a SPLITS_DATAITEM for the designation.

            Dim sdi As New Blackbaud.AppFx.Fundraising.Catalog.WebApiClient.AddForms.Revenue.PledgeAddFormData.SPLITS_DATAITEM

14. Populate the data item. A designation ID is required. For this to work, there must be a designation configured in the application. Each designation has an ID. You will have to configure a designation an find its ID. The ID in this example will not work for your implementation.

    Gift Aid is applicable to UK implementations.

            sdi.AMOUNT = TextBoxAmount.Text
            sdi.APPLICATIONCODE = 0
            Dim DesignationExampleID = New System.Guid("c622f540-b9d5-40dc-aff8-70f68f24e8fb")
            sdi.DESIGNATIONID = DesignationExampleID
            sdi.TRANSACTIONCURRENCYID = USDollarCurrencyID
            sdi.DECLINESGIFTAID = False

15. Create an array of SPLITS_DATAITEM, add the item to the array, and assign the array to SPLITS.

            Dim spl() As Blackbaud.AppFx.Fundraising.Catalog.WebApiClient.AddForms.Revenue.PledgeAddFormData.SPLITS_DATAITEM
            spl = {sdi}
            RevenuePledgeData.SPLITS = spl

16. Pledges require installment information. Handle installments along the lines of splits. Create an item for the installment and an array of items. Then add the item to the array and assign the array to INSTALLMENTS.

            Dim idi As New Blackbaud.AppFx.Fundraising.Catalog.WebApiClient.AddForms.Revenue.PledgeAddFormData.INSTALLMENTS_DATAITEM
            idi.AMOUNT = TextBoxAmount.Text
            idi.DATE = DateTime.Today
            idi.TRANSACTIONCURRENCYID = USDollarCurrencyID
            idi.SEQUENCE = 1
            Dim ins() As Blackbaud.AppFx.Fundraising.Catalog.WebApiClient.AddForms.Revenue.PledgeAddFormData.INSTALLMENTS_DATAITEM
            ins = {idi}
            RevenuePledgeData.INSTALLMENTS = ins

17. Save the data.

            RevenuePledgeData.Save(Me.API.AppFxWebServiceProvider)

Here is the Sub procedure with some additional items commented out.

    Private Sub AddRevenuePledgeRecord()
        Dim RevenuePledgeData As New Blackbaud.AppFx.Fundraising.Catalog.WebApiClient.AddForms.Revenue.PledgeAddFormData()
        RevenuePledgeData = Blackbaud.AppFx.Fundraising.Catalog.WebApiClient.AddForms.Revenue.PledgeAddForm.LoadData(Me.API.AppFxWebServiceProvider)

        RevenuePledgeData.CONSTITUENTID = Me.API.Users.CurrentUser.BackOfficeGuid
        RevenuePledgeData.DATE = DateTime.Today
        RevenuePledgeData.AMOUNT = TextBoxAmount.Text
        RevenuePledgeData.POSTSTATUSCODE = Blackbaud.AppFx.Fundraising.Catalog.WebApiClient.AddForms.Revenue.PledgeAddFormData.POSTSTATUSCODEVALUES.Do_Not_Post
        'RevenuePledgeData.FREQUENCYCODE = Blackbaud.AppFx.Fundraising.Catalog.WebApiClient.AddForms.Revenue.PledgeAddFormData.FREQUENCYCODEVALUES.Single_Installment
        'RevenuePledgeData.NUMBEROFINSTALLMENTS = 1
        RevenuePledgeData.STARTDATE = DateTime.Today
        'RevenuePledgeData.PAYMENTMETHODCODE = Blackbaud.AppFx.Fundraising.Catalog.WebApiClient.AddForms.Revenue.PledgeAddFormData.PAYMENTMETHODCODEVALUES.Credit_Card
        Dim USDollarCurrencyID = New System.Guid("ba9803bc-f104-4150-bd34-d40d0f5b1f27")
        'RevenuePledgeData.TRANSACTIONCURRENCYID = USDollarCurrencyID
        'RevenuePledgeData.SENDPLEDGEREMINDER = False

        Dim sdi As New Blackbaud.AppFx.Fundraising.Catalog.WebApiClient.AddForms.Revenue.PledgeAddFormData.SPLITS_DATAITEM
        sdi.AMOUNT = TextBoxAmount.Text
        sdi.APPLICATIONCODE = 0
        Dim DesignationExampleID = New System.Guid("c622f540-b9d5-40dc-aff8-70f68f24e8fb")
        sdi.DESIGNATIONID = DesignationExampleID
        sdi.TRANSACTIONCURRENCYID = USDollarCurrencyID
        sdi.DECLINESGIFTAID = False
        Dim spl() As Blackbaud.AppFx.Fundraising.Catalog.WebApiClient.AddForms.Revenue.PledgeAddFormData.SPLITS_DATAITEM
        spl = {sdi}
        RevenuePledgeData.SPLITS = spl

        Dim idi As New Blackbaud.AppFx.Fundraising.Catalog.WebApiClient.AddForms.Revenue.PledgeAddFormData.INSTALLMENTS_DATAITEM
        idi.AMOUNT = TextBoxAmount.Text
        idi.DATE = DateTime.Today
        idi.TRANSACTIONCURRENCYID = USDollarCurrencyID
        idi.SEQUENCE = 1
        Dim ins() As Blackbaud.AppFx.Fundraising.Catalog.WebApiClient.AddForms.Revenue.PledgeAddFormData.INSTALLMENTS_DATAITEM
        ins = {idi}
        RevenuePledgeData.INSTALLMENTS = ins

        'RevenuePledgeData.AUTOPAY = False
        'Dim GUIDofZeros = New System.Guid("00000000-0000-0000-0000-000000000000")
        'RevenuePledgeData.CREDITCARDTOKEN = GUIDofZeros
        'RevenuePledgeData.REFERENCEDATE = "00000000"
        'RevenuePledgeData.BENEFITSWAIVED = False
        'RevenuePledgeData.GIVENANONYMOUSLY = False
        'RevenuePledgeData.DONOTACKNOWLEDGE = False
        'RevenuePledgeData.STANDINGORDERSETUP = False
        'RevenuePledgeData.EXCHANGERATE = 1.0
        'Dim AccountSystemGUID = New System.Guid("4b121c2c-cce6-440d-894c-ea0def80d50b")
        'RevenuePledgeData.PDACCOUNTSYSTEMID = AccountSystemGUID
        'RevenuePledgeData.GENERATEREFERENCENUMBER = False

        RevenuePledgeData.Save(Me.API.AppFxWebServiceProvider)
    End Sub