How to Retrieve Giving Transactions Per Family

Tis’ the season churches are nearing the end of the year and getting set to send giving year end statements.

The native functionality for Church Community Builder (CCB) offers the opportunity to execute and export giving statements for individuals and families.

In fact, we’ve previously shared a few API tutorials as it pertains giving and using the CCB API:

• How to use API Online Giving Service to Track Single Gifts
• How to Import Online Gifts Using CCB’s API
• How to Insert Online Gifts

Today’s tutorial will not detail native functionality, yet will focus on how to retrieve giving transaction information for families.

Whether your church plans on creating it’s on giving statement tool or application, or you simply seek to understand the last date or amount of a given family id, this tutorial will help you do that and more.

Now let’s get started!

Open a text editor of your choice, naming and saving the following php file: transactions_by_family.php.

Include the config.php file and appropriate comments in the first few lines of the file as shown below.

To retrieve giving transaction information for families, we’ll use the transactions_by_family CCB API service. In addition, you’ll need a family id handy too.

While you could easily create a dynamic script to provide family ids, this tutorial will hardcode the family id for the sake of simplicity.

While the API service and family id are required parameters, there are optional parameters to consider when retrieving giving transaction information for families using the CCB API.

The following optional parameters are included in the code although commented out:

• startDate
• endDate
• lastModified

For more information and details about required and optional parameters for the transactions_by_family CCB API service, please refer to CCB Documentation.

<?PHP

/**
 * transactions_by_family
 */

// contains resusable globals and functions
include("includes/config.php");

$apiService = 'transactions_by_family'; // CCB api service
$familyID = '22'; // Family Id

//$startDate = '2018-01-01'; // YYYY-MM-DD
//$endDate = '2018-01-01'; // YYYY-MM-DD
//$lastModified = '2018-01-01'; // YYYY-MM-DD

?>

Binding CCB API Parameter Labels to Respective Variables

With the necessary variables defined, it’s time to bind aforementioned variables with their respective CCB API labels defining a urlData variable.

To bind labels, define a urlData variable, setting its value equal to an encapsulated key-value part array, using PHP’s built-in array_filter method (as shown below).

Although I’ve included optional parameters commented out within the code, they will not be used. Uncomment the optional parameters and set their values accordingly to use each.

Once data labels and variables are bound together, the CCB API call can be instantiated.

<?PHP

$urlData = array_filter( array(
	'srv' => "$apiService",
    'family_id' => "$familyID"
    //,'date_start' => "$startDate"
    //,'date_end' => "$endDate"
    //,'modified_since' => "$lastModified"
	) );

?>

Instantiating CCP API Request

To make a CCB API call or to instantiate a CCB API request, I’ll enlist the help of a function used in previous tutorials: ccbDetails.

The ccbDetails function does the heavy lifting to authenticate, authorize, access, and retrieve data from the CCB system.

The ccbDetails function can be instantiated by passing get as the first argument and the urlData as the second argument.

Once the API response is successfully returned as defined by the rss variable, create a nodes variable and set it equal to the rss variable.

The rss variable uses a reference or pointer to parse the response data using the following expression in conjunction to PHP’s XPATH query method: //transactions/transaction.

Now that the response data has been accessed and parse for each transaction, it’s time to access each data point for display to the web browser.

<?PHP

$rss = ccbDetails('get',$urlData); // transform to XML

$nodes = $rss->xpath('//transactions/transaction');  // xpath for groups

?>

Parsing API Response and Displaying Data

To parse and display the response data, I’ve created an empty response_object variable.

Next, I use a foreach statement to iterate the nodes variable which contains an array of available transactions for the respective family id.

Within the foreach statement, I access transaction information as outlined in CCB API documentation for the transactions_by_family API service.

Take notice of the additional foreach statement within the original foreach statement. This second foreach statement allows for accessing transaction details (i.e., giving amount, type of giving, tax deductible, etc.).

Also, make note of the “.=“ operator when redefining or reusing the response_object variable. This expression is used to concatenate data and html into a single line of information when viewing via the web browser.

Once closing both foreach statements, the last step is echoing the response_object variable so that response data can be viewed via the web browser.

<?PHP

$response_object = '';

foreach ($nodes as $node)
{
    $response_object .= $node->individual.' - '.$node->payment_type.' - '.$node->date;

    $trans_details = $node->transaction_details->transaction_detail;

    foreach($trans_details as $trans_detail){

    	$response_object .= ' - '.$trans_detail->coa.' - '.$trans_detail->amount;
    }

    $response_object .= '<br>';
}

echo $response_object;

?>

Time to test your technical chops

It’s time to save your work and open the same file via a web browser. But before executing the script, be sure your code looks exactly like the following in its entirety:

<?PHP

/**
 * transactions_by_family
 */

// contains resusable globals and functions
include("includes/config.php");

$apiService = 'transactions_by_family'; // CCB api service
$familyID = '22'; // Family Id

//$startDate = '2018-01-01'; // YYYY-MM-DD
//$endDate = '2018-01-01'; // YYYY-MM-DD
//$lastModified = '2018-01-01'; // YYYY-MM-DD

$urlData = array_filter( array(
	'srv' => "$apiService",
    'family_id' => "$familyID"
    //,'date_start' => "$startDate"
    //,'date_end' => "$endDate"
    //,'modified_since' => "$lastModified"
	) );

$rss = ccbDetails('get',$urlData); // transform to XML

$nodes = $rss->xpath('//transactions/transaction');  // xpath for groups

$response_object = '';

foreach ($nodes as $node)
{
    $response_object .= $node->individual.' - '.$node->payment_type.' - '.$node->date;

    $trans_details = $node->transaction_details->transaction_detail;

    foreach($trans_details as $trans_detail){

    	$response_object .= ' - '.$trans_detail->coa.' - '.$trans_detail->amount;
    }

    $response_object .= '<br>';
}

echo $response_object;

?>

Of course, you may choose or not choose to add optional parameters. That’s your call though.

As I stated in the beginning, this tutorial hardcodes the family id. With a bit of elbow grease and automation, you could make this script dynamic in nature to retrieve all family id’s.

But that’s a different tutorial altogether for a different day. Well, that’s it for this tutorial.

Let me know if you have comments or questions. Until next week’s tutorial, I wish you a Merry Christmas and Happy New Year!