How to insert online gifts

This tutorial is definitely one of my favorites and will save a tremendous amount of time for any church looking to migrate to Church Community Builder.

Most churches have two main concerns about moving from one Church Management Software system to another: How hard is it to migrate personal profiles and giving information?

We’ve covered the first part of the question in our tutorial on How to Create a CCB Profile.  It was a simple tutorial, but with a little elbow grease, you can transform the codebase into automatically creating CCB profiles.

If you’re still in the dark on how to programmatically go about creating or inserting multiple CCB profiles, then no worries, I’ll soon provide a paid written or video tutorial walking you through how to automate the process.  Sit tight for now.

However, today’s tutorial will cover in detail how to go about inserting online gifts into CCB.  Let me be clear that this tutorial IS NOT about processing payments for online giving.  This tutorial is primarily for churches migrating to CCB, and needing a sound method for transferring their online giving history into CCB. So lets’ get started with today’s tutorial.

For the sake of time in this tutorial, I’ll assume you’ve read and produced the same codebase as our tutorial covering reusable CCB API functions.  If not, it’s in your best interest to go read up and complete that tutorial before attempting this one.

Setting up the basics for inserting online gifts

If you’re ready to move forward, then open your text editor, and create and save a php file named insert-online-gifts.php.  Be sure to add the header comment, including the page name, and then include the config.php file found in your includes directory.

If you’ve been tracking along with me from the beginning, you should now see the benefits in completing the previous tutorials.  It only took us seconds and way fewer keystrokes to setup the insert-online-gifts.php file.  But I digress and we must continue.

We are ready now to set the apiService variable and assign it the online_giving_insert_gift API service.  Next we set the required parameters as variables for the online_giving_insert_gift API service: givingcategoryid, giverid, and giveramount.  There are additional parameters that can be included (e.g., first name, last name, address, email, phone, etc.), but you’ll need to read up using the latest CCB API Documentation.

Let me also take a moment to state the obvious should it not be so clear.  Before attempting to insert an online gift, the person that you are inserting the gift must have a CBB profile created.   This is the only method to obtain the individual’s CCB individual id.


Binding and prepping the URL data for CCB API call

Moving forward, we’re now ready for binding the variables and their respective giving values to their respective service API labels. For this we’ll create a urlData variable and assign it an array of binded service API labels and variables.  We’ll wrap the array using the array_filter to remove any empty arrays (as a precaution or just in case step). 😉

Now were ready to pass the urlData variable as an argument to the ccbDetails function we created in previous tutorials.  Create a rss variable and assign it the ccbDetails function, making the first argument get in single quotes.  I won’t cover all of the nitty gritty details of the ccbDetails function, but I encourage you to read previous tutorials.

Nevertheless, the ccbDetails function, when successfully executed, will return properly structured and formatted XML response.

Now we’re ready for our last step which is parsing the XML and displaying whether or not giving information was successfully entered.

Parsing online giving XML response

You’ll want to read the CCB API documentation as it pertains to the online_giving_gift_insert API service call.  The documentation provides API call and XML response examples that can guide you in terms of parsing the XML response.

Just as we’ve performed in previous tutorials, use XPATH query to parse the XML Response.  Be careful and do take notice that our XPATH query expression has changed to search and find //items/item.  Once assigning the XPATH query to the rss variable, then we’re ready for a good ole’ foreach statement to prepare the response_object variable results to be echoed to the web browser.  And that’s it!

Time to put it all together and test the codebase

You know what time it is!?  It’s time to assemble the code and test it!

Based on the previous steps, you should have the following code as shown below.  Keep in mind when testing the codebase, that online gifts are being inserted into CCB and you’ll need to obtain the appropriate Administrator access privileges to view financial information.

Remember too that this tutorial is only for insert online giving information and NOT processing.

Well, that’s it for this tutorial.  Stay tuned for upcoming tutorials where we will in detail email marketing and integrating to 3rd party applications.

Please comment if this tutorial has helped you.