One common complaint about the API is that it is poorly documented. I found that out myself when I went to use the gift filter object. This is a powerful object that allows you to filter a collection of gifts by its properties. The filter object has very many properties but very few of them are documented. There is one knowledgebase article and one FAQ entry showing how to use it.

Before we start looking at the gift filter object however there are other filters built into the initialization of the gift collection. They include:

tvf_Gift_All
tvf_Gift_AnonymousOnly
tvf_Gift_ConstituentGifts
tvf_Gift_CustomWhereClause
tvf_Gift_ExcludeAnonymous
tvf_Gift_ExcludeDeceasedConstits
tvf_Gift_ExcludeInactiveConstits
tvf_Gift_ExcludeNoValidAddressConstits
tvf_Gift_ExcludeTaxClaimEligible
tvf_Gift_GLReversals
tvf_Gift_TaxClaimEligibleOnly
tvf_Gift_TributeGifts
tvf_Gift_UnPostedGifts
tvf_Gift_UseFilterObject

They can ORed in order to give several options combined e.g.

Code:

oGifts.init SessionContext, tvf_Gift_UseFilterObject OR tvf_Gift_ExcludeAnonymous

This will allow you to use the filter object as well as excluding anonymous. This leads to the possibility of using the filter object together with the custom where clause to create a really powerful gift filter

What is more there is a secondary gift filter object called IGiftsFilter2 which the main CGiftsFilter implements. We may look at this in another article.

To start using the gift filter object we have to initialize our gift collection:

Code:

Dim oGifts As New CGifts
Dim oFilter As CGiftsFilter  

oGifts.Init REApplication.SessionContext, tvf_Gift_UseFilterObject
Set oFilter = oGifts.FilterObject

We are now ready to start using the filter.

The properties can be split into groups

The first group is a collection. Here you add ids to the collection. Note that these are system ids, not the values you see on screen on the record but those that are viewable on the properties page.
AppealIDs
CampaignIDs
ConstitRecordID
FundIDs
GiftIDs
GiftTypes

So for example if my appeal has a system id of 2 I would add it as follows:

Code:

oFilter.AppealIDs.Add 2, CStr(2)

A word on the GiftTypes filter. Here you can filter on cash, pay-cash, pledge, etc. However this is not simply the text but rather an id that the type refers to. This too is not well documented. There is a link in the knowledgebase (http://www.blackbaud.com/esupport/es…r=0&id=BB17413) that gives this information or it can be derived by looking at the SQL or a query.

Update: This list can now be found here.
For example:

Code:

oFilter.GiftTypes.Add 1, "Cash"
oFilter.GiftTypes.Add 2, "Pay-Cash"

The next group are composite properties. They are (or can be in some cases) added together. For example

DateRange
DateToUse
StartDate
EndDate

StartAmount
EndAmount

For example I would enter a date range, a type of date to use and the actual date

Code:

oFilter.DateToUse = dtu_GiftDate
oFilter.DateRange = bbDATE_SPECIFICDATE
oFilter.StartDate = 01/01/2007

We only use the start date here has the end date is ignored for a specific date.

The remainder are miscellaneous properties of varying importance.

SoftCredit - How has the gift been soft credited; donor, recipient or both
SoftCreditAmountMethod - How has the soft credit been distributed, full amount to all, split evenly, use amount in grid

ExcludeZeroAmount - excludes zero amounts

GiftConstituentCode - filters by the constituency code on the gift

MatchCredit - how matching gifts are credited; constituent, matching gift organization or both

SubtrackBrokerFee - whether the broker fee is subracted (true or false)
UsePledgeBalance - use the pledge balance (true or false)
UseSaleAmountForSoldStock - use the sale amount for sold stock (true or false)
UseSaleDateForSoldStock -use sale date for sold stock (true or false)

And then these two… (Let me know if you can enlighten me)

UseCFAFiltersForAmount
ConstitIDPrepSQLName

If you have anything to add then please do so this is by now means all encompassing

Related posts:

1. Filtering and Sorting Participants - Just not Together This is being written in response to two hours of...
2. Gift Type IDs - A Reference A while ago I wrote an article about filtering on...
3. Filtering Individual Relationships In my endeavour of documenting the undocumented I would like...
4. Close down or crash One of the basic principles that you need to learn...