How to Import Online Gifts Using CCB’s API

Welcome back to another week and another value-add tutorial using CCB’s API Service.

This week, we’re changing gears to focus a bit on the financial operations of the church.

Often times, financial and operational management aspects tend to be separate due to system and technical requirements.

Today’s tutorial aims to help understand how to import online gifts directly into the Church Community Builder system.

We will not cover nor does the import online gifts CCB API service cover processing any payments. Again, this is NOT to process payments, but is to create a record for online giving in CCB system.

Defining Service, Required, and Optional Parameter Variables

Open the text editor of your choice, naming and saving the following file: import-online-gifts.php.

As with previous tutorials, be sure to start your file out with the appropriate comments and the inclusion of the config.php file.

It’s important to include the config.php, as it contains reusable globals and functions need to make important CCB API calls.

Once comments and includes are successfully completed, now define the apiService variable, setting it equal to the CCB API service for importing online gifts: import_online_gifts.

For the sake of time, I’ll forego listing the extensive list of required and optional parameters. View CCB API documentation for a full description of both required and optional parameters as it pertains to the import_online_gifts API service.

In the code below, I’ve provided values for only the required parameters and no values for the optional parameters. But do feel free to use the optional parameters as the need arises.

NOTE: If you don’t provide an individual’s id, the ‘0’ is provided and the service attempts to match the individual gift to an individual using the contact information provided (i.e., first name, last name, address and email address).

Binding Labels and Variables to Make API Call and Parse Response

Once service, required and optional parameter variable are defined, it’s time to bind defined variables to their respective CCB API service label.

Defined variables (i.e., apiService, required and optional parameter variables) MUST be bound to their respective label for CCB API call to be successfully executed.

To bind variables and labels, create a urlData variable, setting it equal to an encapsulated key-value pair array using PHP’s built in array_filter method.

Once labels and variables are bound accordingly, instantiate the CCB API call using the ccbDetails function.

Be sure to set the ccbDetails functions equal to the value of the rss variable, ensuring to pass get as the first argument and the urlData variable a the second argument.

Parsing and Displaying CCB API’s XML Response Data

The CCB API can has been successfully executed. Now, it’s time to parse the XML response and prep the data for display via the web browser.

To parse data in the XML response, use PHP’s built-in XPATH query method and following expression: //online_gifts/online_gift.

Define a nodes variable and have it’s value be the rss variable pointing to the aforementioned path query expression.

Once the response data has been appropriately transformed, the nodes variable can be printed to the web browser using PHP’s built-in print_r method.

This method allows arrays to be printed and displayed to the screen.  Check previous tutorials for how to access each data point.

Testing Your CCB API Prowess via Web Browser

You’ve made it to the finally step of this tutorial. Your code in its entirety should look like the following:

Be sure to save the import-online-gifts.php file, and then open it via a web browser. You should be able to see a multi-dimensional array of data for the newly imported online gift.

If you don’t see array data displayed or you’ve encountered an error, then please don’t hesitate to drop me a question or comment. I would love to help remove the technical blocker and bridge the gap for you.

That’s all for now! See you back here for another tutorial next week.

Please comment if this tutorial has helped you.