Geez, just re-reading the title makes me (and probably you too!) cringe at the thought of using the Church Community Builder API to automate processes, queues and attendance reporting into a repeatable dynamic action.

That’s a thought and mouthful to repeat.

Well, it’s been a fast moving week for me, and I’ve been a bit slow delivering today’s tutorial.

In fact, I wish I had finished and posted it earlier than now, and let me explain why.

As most of you know, I’m a member of and volunteer at Mosaic Church in Austin, Texas.  My primary responsibility outside of discipling, ministering and leading is being the point of contact for our Foundation and Membership Classes, and the Membership Process in its entirety.

We recently had our latest Foundations Class end this past Sunday. As I was attempting to MANUALLY figure out who attended 4 or more classes and completed Membership Class, I was reminded how much I needed today’s tutorial.

It is possible to manually create reports using the CCB front-end interface and achieve the task.

However, I rarely have time to lose, and I like being able to setup the use of repeatable and dynamic automation using cron jobs. 

And that’s exactly what I’m going to show you in today’s tutorial:

  • How to use a specific process and queue
  • How to return the individuals for a specific queue
  • How to check the attendance for multiple events
  • How to add individuals to another queue (optional)
  • How to create an excel report

If you’re ready, then I’m ready to begin. Let’s get started.

Do not pass Go without reading this…

To start, we’re going to use quite a few tutorials we recently completed. Those tutorials are as follows:

You’ll really need to review each tutorial before starting this tutorial.

I won’t give much detail as I’ve already covered most in previous tutorials.

If you get lost, then take the time to read and study up a bit using the previous tutorials.

What am I trying to solve and achieve?

As I stated, I manually manage our church’s Foundation and Membership Classes, and the Membership Process.

It can be quite time consuming to manually manage this process every 6 weeks, especially when your church is rapidly growing (which we thank God for!).

Although we use the check in feature for our classes to capture attendee attendance, I have to manually cross check each person’s attendance and involvement across the following three processes:

  • Foundations Class
  • Membership Class
  • Membership

For each person that attends a class, I have to manually validate their captured attendance history and record.  Why?

When a person has completed the Membership class and 4 out of 6 Foundation Classes, then the person is eligible for continuation in the Membership Process by way of Pastoral Interview.

What does this tutorial have to do with your church?

This tutorial in terms of the processes I chose may not have to do a thing with your church.  But you may have a reporting need that shares in the same likeness and spirit.

You too could find yourself having to validate and compare individuals’ actions and behaviors across multiple processes and queues, and then adding a certain type of person to another process and queue based on defined actions and behaviors.

Can this be accomplished using CCB’s interface? The short answer is Yes.

However, it’s quite a bit of work to create custom searches that are not dynamic in nature as is the case when using the Church Community Builder API.

Now that you know what were attempting to solve, let’s solve it together.

It’s time to start coding…

To begin this tutorial, open the text editor of your choice, and name and save the file whatever you would like. For this example, I’m naming my file membership-ready.php.

As we’ve performed in previous tutorials, include the necessary comments and file inclusions in this file.

Next, define the apiService variable to the value of queue_list. This use of queue_list allows to retrieve the queues for a specific process.

In addition, there is not a need to start with a process id, because you can find the specific queue id by hovering over the queue’s name via the CCB front-end web interface.

For the sake of this example, I’m sharing how to find a process first and then define a specific queue id to work with.

The next variables to identify are the processID and queueID variables. As I alluded to in previous sentences, you can use the CCB front-end web interface to find out the processID and queueID (see tutorial).

For this example, the processID value is defined as 50 and the queueID value is defined at 197.

Next, I’ll define the addToQueueID variable’s value to be 91. The addToQueueID variable is the id of the queue that we’ll add people to when they have completed both Membership and Foundations classes, and are ready for Pastoral Interview.

Finally, we define the nameOfReport variable’s value to be ready-for-pi. This variable value is the name of the Excel/CSV file.

<?PHP

/**
 * retrieve list of individuals from process and queues
 */

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

// Use the queue_list service retrieve a list of queues
$apiService = 'queue_list'; // CCB api service

// For my example, I'm checking my Foundations Class process and Completed Foundations queue
$processID = '50'; // Process ID
$queueID = '197'; // Queue ID to check with individuals

// And we arrive at the queue where we end
$addToQueueID = '91'; // Queue ID to add individiuals to

//Example: ready-for-pi === pi = pastoral interview 
$nameOfReport = 'ready-for-pi';  //No spaces or if you need spaces then use dash (-) only; No other special characters can be used

?>

I’m providing the Excel/CSV report option, so that you can cross check to ensure that individuals were successfully added to the queue.

In addition, you can use this excel report to go back and mark the same individuals as done in the respective processes and queues.

Then, of course we set the urlData variable as we have in previous tutorials. With the queue_list service, we simply pass it the srv and id variables with apiService and processID values respectively.

Then, we execute the ccbDetails function, passing it the get and urlData variable respectively as arguments.

The data response is then transformed into XML, and we use XPATH query to parse the data using the following expression: //queues/queue.

The we define empty variables for the following:

  • response_object: this variable allows for data to be printed to web browser for display
  • response_object_arr: this variable allows for an array of person id’s to be returned
  • response_object_xls: this variable allows for the names of people to be placed within excel report
<?PHP

$urlData = array_filter( array(
	'srv' => "$apiService",
    'id' => "$processID",
	) );

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

$nodes = $rss->xpath('//queues/queue');  // xpath for process queues

$response_object = $response_object_arr = $response_object_xls = '';

?>

Next, we move onto the foreach statement. Within this statement that traverses an array of process queues, an if statement is created to match the queue’s id to that of the queueID variable value.

This allows for a specific queue to be captured. Inside this if statement, we then set the response_object_arr equal to the getQueueIndividuals, passing it the queue’s id (i.e., $node[‘id’]) and returning an array of individuals within the specified queue.

<?PHP

foreach ($nodes as $node)
{
	if($node['id'] == $queueID){
		//$response_object .= '<h2>'.$node->name.'</h2>';
		$response_object_arr = getQueueIndividuals($node['id']);
	}
}


?>

So far, we are now able to identify a queue and individuals in that queue.

Or put another way, I can now identify persons that have completed either Membership or Foundations process.

Who’s ready for Pastoral Interview?

The next thing to figure out is who’s ready for a Pastoral Interview.

To determine this, we’ll need to be able to check each person’s attendance based on their event check in history.

Once we determine a person has completed Membership Class and 4 out of 6 Foundation classes, then we’re able to add the person to a Ready for Pastoral Interview queue in a different process.

But not too fast. You’ll need and want to also create an Excel/CSV file of persons ready fro Pastoral Interview. Do this so that you have a point of reference to cross check and validate that the right persons were added to the right process queues.

A downside to CCB’s Process and Queues is that you’re not able to automatically mark person’s done using the API.

I can’t wait for this feature to make it’s debut, yet I’m not holding my breath either.

Nevertheless, you’ll have to manually go back and mark persons done in the old queue that were moved to new queue. So, having a Excel/CSV to cross reference is handy for such a task.

To get started, define the Excel/CSV header using the response_obj_xls variable, setting it accordingly. Then set the xls_count variable to 0.

<?PHP

// Time to prepare the Excel/CSV header and set the count of people ready for Pastoral Interview
$response_object_xls = '"Name"' . "\n";
$xls_count = 0;

?>

Why set the xls_count variable to 0 you ask? Well, not everyone in this queue will be ready for a Pastoral Interview.

Some may have only completed Foundations or Membership, and not both.

Now it’s time to iterate through the response_object_arr we arrived at in the last section using a foreach statement. This variable contains a list of individuals’ ids.

Next, define a person_ready variable within the foreach statement, and assign it the getIndividualAttendance function, passing it the foreach value variable (person’s id).

Next, define a if statement using the person_ready variable.

If a person is ready for Pastoral Interview, meaning that getIndividualAttendance returned true, then we add the person to a new queue (Pastoral Interview queue) using their id via the addIndividualToQueue function.

The addToQueueID variable will also need to be passed to the addIndividualToQueue function as it’s first argument, passing the person’s id as the second argument.

Next, define the personFullName variable and assign it the getIndividualProfileFullName, passing it the person’s id. The getIndividualProfileFullName function returns a person’s full name based on the person’s id.

Then, increment the xls_count, and set the response_object and response_object_xls variables accordingly, closing the if and foreach statements with their respective curly ( ) brackets.

<?PHP

// Time to check to see who's ready for Pastorial Interview
foreach($response_object_arr as $value){

	  // Is the person ready for Pastoral Interview? Return true or false
	  $person_ready = getIndividualAttendance($value);

	  // Person is ready for Pastoral Interview
	  if($person_ready){
	  	// Add Person To New Queue
	  	addIndividualToQueue($addToQueueID,$value);

	  	// Retrieve Person's Name
		$personFullName = getIndividualProfileFullName($value);
		// increment the total person count of those ready for Pastoral Interview
		$xls_count++;

	  	$response_object .= $personFullName.'<br>';
		$response_object_xls .= '"'.$personFullName.'"'."\n";  // now prep row data for csv file (See CCB API documentation for more $apiService fields)
	}

}

?>

Writing the Excel/CSV report

There’s a whole tutorial on how I create the excel report, so I won’t do a deep dive here other than to say we use an if statement to check to see if the xls_count variable is greater than 0.

Run this check to verify that there are people being reported and data written to Excel/CSV file.

Otherwise, there is no need to create the Excel/CSV report if no one is ready for a Pastoral Interview, or whatever your process may be.

<?PHP

// If count is > 0 then create an excel/csv file with list of persons ready for Pastoral Interview

if($xls_count > 0){ 

	$f = fopen($nameOfReport.'.csv' , 'wb');
	fwrite($f , $response_object_xls );
	fclose($f);

}

?>

The last thing we do is print the response_object to the web browser display, so that you can view the list of individuals added to your new process.

<?PHP

echo $response_object;

?>

Again, you’ll have an excel report in the same directory as your codebase, so do make sure that the file is created.

By the way, be sure to NOT EXECUTE this report multiple times without manually marking people done in the previous queue.

If you forget to mark people done, then you will add the same people into the new process queue and you’ll have duplicates, leaving you with a manual nightmare to clean up by hand.

Feel free to also include the functions listed at the very end of this tutorial in the general.php file.

If you don’t have a clue as to what I’m talking about in terms of including functions inside general.php, then read this.

I only included the functions you see below as a part of this tutorial to help you understand how it all works together.

And by all means, please refactor or make the functions more efficient and reusable for future purposes.

Time to test out this code magic…

So, let’s put it all together and execute the code in a web browser… Or take it a step further and automate using a cron job to run every six weeks based on event dates.

<?PHP

/**
 * retrieve list of individuals from process and queues
 */

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

// Use the queue_list service retrieve a list of queues
$apiService = 'queue_list'; // CCB api service

// For my example, I'm checking my Foundations Class process and Completed Foundations queue
$processID = '50'; // Process ID
$queueID = '197'; // Queue ID to check with individuals

// And we arrive at the queue where we end
$addToQueueID = '91'; // Queue ID to add individiuals to

//Example: ready-for-pi === pi = pastoral interview 
$nameOfReport = 'ready-for-pi';  //No spaces or if you need spaces then use dash (-) only; No other special characters can be used

$urlData = array_filter( array(
	'srv' => "$apiService",
    'id' => "$processID",
	) );

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

$nodes = $rss->xpath('//queues/queue');  // xpath for process queues

$response_object = $response_object_arr = $response_object_xls = '';

foreach ($nodes as $node)
{
	if($node['id'] == $queueID){
		//$response_object .= '<h2>'.$node->name.'</h2>';
		$response_object_arr = getQueueIndividuals($node['id']);
	}
}

// Time to prepare the Excel/CSV header and set the count of people ready for Pastoral Interview
$response_object_xls = '"Name"' . "\n";
$xls_count = 0;

// Time to check to see who's ready for Pastorial Interview
foreach($response_object_arr as $value){

	  // Is the person ready for Pastoral Interview? Return true or false
	  $person_ready = getIndividualAttendance($value);

	  // Person is ready for Pastoral Interview
	  if($person_ready){
	  	// Add Person To New Queue
	  	addIndividualToQueue($addToQueueID,$value);

	  	// Retrieve Person's Name
		$personFullName = getIndividualProfileFullName($value);
		// increment the total person count of those ready for Pastoral Interview
		$xls_count++;

	  	$response_object .= $personFullName.'<br>';
		$response_object_xls .= '"'.$personFullName.'"'."\n";  // now prep row data for csv file (See CCB API documentation for more $apiService fields)
	}

}

// If count is > 0 then create an excel/csv file with list of persons ready for Pastoral Interview

if($xls_count > 0){ 

	$f = fopen($nameOfReport.'.csv' , 'wb');
	fwrite($f , $response_object_xls );
	fclose($f);

}	

//print_r($response_object_arr);

echo $response_object;


//**********************************************************************************
//  FUNCTIONS - 
//**********************************************************************************//

// retrieves a list of individuals from a queue with trigger status of 'not-started' and returns an array of ids
function getQueueIndividuals($id){

$apiService = 'queue_individuals'; // CCB api service
$queueID = $id; // Queue ID

$urlData = array_filter( array(
	'srv' => "$apiService",
    'id' => "$queueID",
	) );

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

$nodes = $rss->xpath('//individuals/individual');  // xpath for attendance

$response_object = array();

foreach ($nodes as $node)
{
	// if you want to return a certain status, then make sure to set $triggerStatus = 1
	// Then, be sure to set filter status using one of the following:
	// waiting, in-process, done, not-started
	$triggerStatus = 1;
	$statusFilter = 'not-started';

	if ($triggerStatus){

		// or also filter using != operator: if($statusFilter != strtolower($node->status))
		if($statusFilter == strtolower($node->status))
			$response_object[] .= $node['id'];

	} else {
		$response_object[] .= $node['id'];
	}
}

return $response_object;

}

// Returns false, or true if a person has completed 1 Membership Class and 4 out of 6 Foundation Classes
function getIndividualAttendance($pid){

$apiService = 'individual_attendance'; // CCB api service
$personID = $pid; // Person's ID

$urlData = array_filter( array(
	'srv' => "$apiService",
    'individual_id' => "$personID"
	) );

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

$nodes = $rss->xpath('//attendances/attendance');  // xpath for attendance

$response_object = '';

$membershipLimit = 1; // number of Membership classes a person MUST to be ready for Pastoral Interview
$foundationsLimit = 4; // number of Foundation classes a person MUST to be ready for Pastoral Interview

$membershipAttendanceCount = $foundationsAttendanceCount = 0;

foreach ($nodes as $node)
{

	$pageString = $node->event;

	/*if ((strpos($pageString,'Membership Class') !== false) || (strpos($pageString,'Foundations Class') !== false) ) {
    	$response_object .= $node->event.' - '.$node->group.' - '.$node->occurrence.'<br/>';
	}*/

	if(strpos($pageString,'Membership Class') !== false)
		$membershipAttendanceCount++;

	if(strpos($pageString,'Foundations Class') !== false)
		$foundationsAttendanceCount++;
}

if($membershipAttendanceCount >= $membershipLimit && $foundationsAttendanceCount >= $foundationsLimit)
	return true;

return false;

//echo $response_object;

//echo '<br>mac: '.$membershipAttendanceCount;
//echo '<br>fac: '.$foundationsAttendanceCount;

}

// retrieves and returns a person's full name
function getIndividualProfileFullName($id){

$apiService = 'individual_profile_from_id'; // CCB api service

$personID = $id;  // sample field to search for (See CCB API documentation for more $apiService fields)

$urlData = array_filter( array(
	'srv' => "$apiService",
'individual_id' => "$personID"
	) );

$rss = ccbDetails('get',$urlData);

$nodes = $rss->xpath('//individuals/individual');  // xpath for individuals->individual

$fullname = '';

foreach ($nodes as $node)
{
    $fullname = $node->full_name;  // now print the person's full name and age (See CCB API documentation for more $apiService fields)
}

return $fullname;

}

// adds a person to a specific queue based on queue id and individual id
function addIndividualToQueue($qid,$pid){

$apiService = 'add_individual_to_queue'; // CCB api service
$personID = $pid; 
//$noteMsg = 'Person completed Membership & Foundation Classes.  Added By Automated Report';

$urlData = array_filter( array(
	'srv' => "$apiService",
	'individual_id' => "$personID",
	'queue_id' => "$qid"
	//,'note' => '$noteMsg'
	) );

$rss = ccbDetails('get',$urlData);

}

?>

It would take me hours a time to manage multiple processes, and now because of this code, I can manage everything in a matter of 30 minutes at most.

I can now get a list of people who completed both Foundations and Membership Class, and are ready for Pastoral Interview. And the same persons are added to the Pastoral Interview process.

Using CCB’s front-end web interface, the only manual work I have now is marking persons done in both Foundations and Membership Class processes, and cross check my work using the Excel/CSV report.

Talking about a way to be more accurate and get more time back in my day to go be for efficient and productive in other areas.

I hope this tutorial helps you to solve and achieve the same thing. If you need help, please don’t hesitate to drop me a comment below.

That’s it for this tutorial… I’ll see you back here next week.

getQueueIndividuals function

This function simply retrieves a list of individuals in a given queue.

<?PHP

// retrieves a list of individuals from a queue with trigger status of 'not-started' and returns an array of ids
function getQueueIndividuals($id){

$apiService = 'queue_individuals'; // CCB api service
$queueID = $id; // Queue ID

$urlData = array_filter( array(
	'srv' => "$apiService",
    'id' => "$queueID",
	) );

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

$nodes = $rss->xpath('//individuals/individual');  // xpath for attendance

$response_object = array();

foreach ($nodes as $node)
{
	// if you want to return a certain status, then make sure to set $triggerStatus = 1
	// Then, be sure to set filter status using one of the following:
	// waiting, in-process, done, not-started
	$triggerStatus = 1;
	$statusFilter = 'not-started';

	if ($triggerStatus){

		// or also filter using != operator: if($statusFilter != strtolower($node->status))
		if($statusFilter == strtolower($node->status))
			$response_object[] .= $node['id'];

	} else {
		$response_object[] .= $node['id'];
	}
}

return $response_object;

}

?>

getIndividualAttendance function

This function retrieves a person’s attendance and returns true if the person complete 1 Membership Class and 4 out of 6 Foundation Classes.  It uses much of the same logic as previous tutorials.  This does the heavy lifting that I once manually did by hand and multiple reports.

<?PHP

// Returns false, or true if a person has completed 1 Membership Class and 4 out of 6 Foundation Classes
function getIndividualAttendance($pid){

$apiService = 'individual_attendance'; // CCB api service
$personID = $pid; // Person's ID

$urlData = array_filter( array(
	'srv' => "$apiService",
    'individual_id' => "$personID"
	) );

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

$nodes = $rss->xpath('//attendances/attendance');  // xpath for attendance

$response_object = '';

$membershipLimit = 1; // number of Membership classes a person MUST to be ready for Pastoral Interview
$foundationsLimit = 4; // number of Foundation classes a person MUST to be ready for Pastoral Interview

$membershipAttendanceCount = $foundationsAttendanceCount = 0;

foreach ($nodes as $node)
{

	$pageString = $node->event;

	/*if ((strpos($pageString,'Membership Class') !== false) || (strpos($pageString,'Foundations Class') !== false) ) {
    	$response_object .= $node->event.' - '.$node->group.' - '.$node->occurrence.'<br/>';
	}*/

	if(strpos($pageString,'Membership Class') !== false)
		$membershipAttendanceCount++;

	if(strpos($pageString,'Foundations Class') !== false)
		$foundationsAttendanceCount++;
}

if($membershipAttendanceCount >= $membershipLimit && $foundationsAttendanceCount >= $foundationsLimit)
	return true;

return false;

//echo $response_object;

//echo '<br>mac: '.$membershipAttendanceCount;
//echo '<br>fac: '.$foundationsAttendanceCount;

}

?>

getIndividualProfileFullName function

This function accepts a person’s id and returns their full name.  Pretty simple, aye?

<?PHP

// retrieves and returns a person's full name
function getIndividualProfileFullName($id){

$apiService = 'individual_profile_from_id'; // CCB api service

$personID = $id;  // sample field to search for (See CCB API documentation for more $apiService fields)

$urlData = array_filter( array(
	'srv' => "$apiService",
'individual_id' => "$personID"
	) );

$rss = ccbDetails('get',$urlData);

$nodes = $rss->xpath('//individuals/individual');  // xpath for individuals->individual

$fullname = '';

foreach ($nodes as $node)
{
    $fullname = $node->full_name;  // now print the person's full name and age (See CCB API documentation for more $apiService fields)
}

return $fullname;

}

?>

addIndividualToQueue function

This function adds a person to a specific queue.  There’s not much error checking in the function.  It could use a little error checking love, verifying that the person was indeed entered into the correct queue.

<?PHP

// adds a person to a specific queue based on queue id and individual id
function addIndividualToQueue($qid,$pid){

$apiService = 'add_individual_to_queue'; // CCB api service
$personID = $pid; 
//$noteMsg = 'Person completed Membership & Foundation Classes.  Added By Automated Report';

$urlData = array_filter( array(
	'srv' => "$apiService",
	'individual_id' => "$personID",
	'queue_id' => "$qid"
	//,'note' => '$noteMsg'
	) );

$rss = ccbDetails('get',$urlData);

}

?>

 

Related Posts

Subscribe and receive the following...

  • Inside CCB tips and tricks
  • Instant CCB tutorial alerts and updates
  • CCB How To's, Videos, Webinars and more...