I’m back with a doozy of a tutorial today based upon using Church Community Builder’s (CCB) API to create an overdue persons report.
In short, CCB innately provides notifications when individuals are placed in a queue and their due date expires without the queue manager taking action.
For example, our church has a number of ministry service teams:
- Greeters
- Ushers
- Coffee Bar
- mKids (Children’s Ministry)
- mYouth (Youth Ministry)
- Elevate (High School)
- Chi Street (Homeless Ministry)
- Worship Team
- Production
- Hospitality
- Events/Admin
These various ministry areas rely on our Connection Card, Member Class, and Foundation Class processes to supply their ministry with volunteers to serve.
One of the things that can happen often is that queue managers, often volunteer ministry leads, forget to check their queues even with reminders auto emailed by CCB natively.
After all, it’s not a volunteer’s full time job or responsibility.
However, this type of inactivity causes communication challenges and breakdowns when ministry leads are not communicating in a timely manner to volunteers who have a desire to serve.
So today, I’ll show you how to create a report for a specific queue to determine how many days an individual is passed their due date.
IMAGE
This doesn’t necessarily mean that the person in question in the respective queue has not been contacted by the ministry lead.
Sometimes it’s that the ministry lead has not updated CCB even though they’ve contacted the volunteer and, in some cases, the volunteer is actively serving.
Nevertheless, the goal should be to keep CCB data pristine and updated at all times.
Getting started with today’s tutorial
To begin this tutorial, open the text editor of your choice, and name and save the file queue-overdue-persons.php.
As we’ve performed in previous tutorials, include the necessary comments and file inclusions in this file.
Using the Church Community Builder’s API documentation, find the following api services:
- queue_individuals
- individual_queues
Using both services, we’ll create functions to retrieve a list of individuals in a queue, and an individuals queue status and details.
I won’t dive into all the details. Review the initial tutorials for further explanation.
For the sake of this tutorial, I’ll use a single queue. You could modify this code, once you’ve completed this tutorial, to create reports for multiple queues at once.
To start, define the queueID variable with the queue’s id that you would like to review. I’m using queue id 107 in this tutorial.
Again review previous tutorials to figure out how to find your respective queue’s id using the Church Community Builder Web Interface.
Next, define the response_object variable and set it’s value to use the getQueueIndividuals function, passing it the queueID variable. I’ll cover functions at the of this tutorial.
In short, just know that the getQueueIndividuals function retrieves a list of individuals in a respective queue and returns them via an array.
Next, sort the array (i.e. response_object variable) using the built-in PHP method asort.
<?PHP
/**
* overdue persons in a queue
*/
// contains resusable globals and functions
include("includes/config.php");
$queueID = '107';
$response_object = getQueueIndividuals($queueID);
// sort
asort($response_object);
?>Now, we’re ready to determine the number of days overdue individuals with a not started status are the desired queue.
Define the response_catch variable as an empty array.
Next, we’ll use a foreach statement to iterate through the array (i.e. response_object variable array) containing a list of individuals.
Within the foreach statement, define a response_catch[] array variable and set it’s value to use the getIndividualQueueStatus function, passing to it the value variable array as the first argument and the queueID as the second argument.
Next, we use the built-in PHP method usort and a custom function (i.e., sortByDays – see at end of tutorial) to sort the final list of data in descending order by the number of days overdue.
Essentially, pass usort the response_catch variable array as the first argument and text string sortByDays as the second argument.
<?PHP
$response_catch = array();
foreach($response_object as $value){
$response_catch[] = getIndividualQueueStatus($value,$queueID);
}
usort($response_catch, 'sortByDays');
?>Preparing the table to list individuals that are overdue
Now, we’re ready to work on creating the table that will be displayed when you execute the code in a web browser.
I won’t cover it in this tutorial, but keep in mind that you can also save data to a Excel/CSV file.
If you’re not familiar with HTML, then I invite you to use the following resources for HMTL guidance:
In short, you’re going to build a 3 column table that has the following:
- Total Individual Count Header that spans 4 columns
- Header row containing column headers:
- Name
- Days Overdue
- Process Queue
To list each person’s name, days overdue and the respective process queue, we’ll use a foreach statement to iterate through the array (i.e. response_catch variable array) containing respective data.
You may noticed I set i as a variable and set it’s value to 1. I did this so that you can verify and the Total number of individuals count.
Within the foreach statement, you’ll find the i variable with double plus signs following it, indicating that the value will increment itself by one each iteration.
With the same foreach statement, we’ll access the value variable array as follows to obtain data points:
- name: $value[1]
- days overdue: $value[2]
- process queue: $value[3]
Then, close the table and we’re ready to wrap this tutorial up with a test.
<?PHP
// table for displaying data, including styles and html
echo '<style> .header{ background: #000; color: #fff;} </style>';
echo '<table cellpadding="8" cellspacing="0" border="1" width="50%" align="center">';
echo '<tr><td colspan="3">Total number of Individuals: '.sizeof($response_object).'</td></tr>';
echo '<tr><td class="header">Name</td><td class="header">Days Overdue</td><td class="header">Process Queue</td></tr>';
$i = 1;
foreach($response_catch as $value){
echo '<tr><td>'.$i.') '.$value[1].'</td><td>'.$value[2].'</td><td>'.$value[3].'</td></tr>';
$i++;
}
echo '</table>';
?>I love it when a plan comes together…
That’s it for today’s tutorial. The code is below in it’s entirety. Save your file and execute it via a web browser.
<?PHP
/**
* overdue persons in a queue
*/
// contains resusable globals and functions
include("includes/config.php");
$queueID = '107';
$response_object = getQueueIndividuals($queueID);
// sort
asort($response_object);
$response_catch = array();
foreach($response_object as $value){
$response_catch[] = getIndividualQueueStatus($value,$queueID);
}
usort($response_catch, 'sortByDays');
// table for displaying data, including styles and html
echo '<style> .header{ background: #000; color: #fff;} </style>';
echo '<table cellpadding="8" cellspacing="0" border="1" width="50%" align="center">';
echo '<tr><td colspan="3">Total number of Individuals: '.sizeof($response_object).'</td></tr>';
echo '<tr><td class="header">Name</td><td class="header">Days Overdue</td><td class="header">Process Queue</td></tr>';
$i = 1;
foreach($response_catch as $value){
echo '<tr><td>'.$i.') '.$value[1].'</td><td>'.$value[2].'</td><td>'.$value[3].'</td></tr>';
$i++;
}
echo '</table>';
//**********************************************************************************
// FUNCTIONS -
//**********************************************************************************//
// sorts multi-dimensional array
function sortByDays($a, $b) {
// if you want asecending, then set to following: $a[2] - $b[2];
return $b[2] - $a[2];
}
// function to get individuals in a specific queue with a specific status, returns a multi-dimensional array
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[] = array ((string) $node['id'],(string) $node->name);
} else {
$response_object[] = array ((string) $node['id'],(string) $node->name);
}
}
return $response_object;
}
// function determines how many days individual has been in queue and returns a array
function getIndividualQueueStatus($pinfo,$qid){
$apiService = 'individual_queues'; // CCB api service
$queueID = $qid; // Queue ID
$personID = $pinfo[0]; // Person ID
$personName = $pinfo[1]; // Person ID
$urlData = array_filter( array(
'srv' => "$apiService",
'id' => "$personID",
) );
$rss = ccbDetails('get',$urlData); // transform to XML
$nodes = $rss->xpath('//queues/queue'); // xpath for attendance
$response_object = array();
foreach ($nodes as $node)
{
if($node['id'] == $queueID){
$dueDate = (string)$node->due;
$dateToSeconds = dateToSeconds($dueDate);
$daysOverDue = daysOverDue($dateToSeconds);
if(isOverDue($dateToSeconds)){
$response_object = array($personID,$personName, $daysOverDue,(string) $node->name);
//echo $personID.'-'.$personName.'-'.$dueDate.'-'.$dateToSeconds.'<br>';
}
}
}
return $response_object;
}
// changes date (e.g., YYYY-MM-DD or Y-m-d) to seconds
function dateToSeconds($date){
$dateToSeconds = strtotime($date);
return $dateToSeconds;
}
// input date as seconds and figures out how many days person is over due
function daysOverDue($date){
$time = time();
$diff = $time - $date;
$days = floor($diff/86400);
return $days;
}
// input date as seconds and figures out if time as seconds as passed based on current time
function isOverDue($dateSeconds){
$time = time();
if($dateSeconds < $time)
return true;
return false;
}
?>Remember, this is only a report for a single Process Queue. With a little ingenuity placing Queue ids in an array and using a foreach statement to iterate each, you turn this into a broader report.
This just might be next week’s tutorial! Then again, I may show you how to email it to persons not inside CCB. 😉
Nevertheless, enjoy this tutorial and I hope it helps to get persons moving in an efficient and expeditious manner across all Process Queues.
The following functions can be placed in your general.php using the following tutorial: Creating a reusable function for CCB API calls.
sortByDays function
This user-defined function simply sorts a multi-dimensional array.
<?PHP
// sorts multi-dimensional array
function sortByDays($a, $b) {
// if you want asecending, then set to following: $a[2] - $b[2];
return $b[2] - $a[2];
}
?>getQueueIndividuals function
This function retrieves a list of individuals in a specific queue with a specific status, returning a multi-dimensional array.
<?PHP
// function to get individuals in a specific queue with a specific status, returns a multi-dimensional array
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[] = array ((string) $node['id'],(string) $node->name);
} else {
$response_object[] = array ((string) $node['id'],(string) $node->name);
}
}
return $response_object;
}
?>getIndividualQueueStatus function
This function determines how many days an individual has been in queue and returns an array.
<?PHP
// function determines how many days individual has been in queue and returns a array
function getIndividualQueueStatus($pinfo,$qid){
$apiService = 'individual_queues'; // CCB api service
$queueID = $qid; // Queue ID
$personID = $pinfo[0]; // Person ID
$personName = $pinfo[1]; // Person ID
$urlData = array_filter( array(
'srv' => "$apiService",
'id' => "$personID",
) );
$rss = ccbDetails('get',$urlData); // transform to XML
$nodes = $rss->xpath('//queues/queue'); // xpath for attendance
$response_object = array();
foreach ($nodes as $node)
{
if($node['id'] == $queueID){
$dueDate = (string)$node->due;
$dateToSeconds = dateToSeconds($dueDate);
$daysOverDue = daysOverDue($dateToSeconds);
if(isOverDue($dateToSeconds)){
$response_object = array($personID,$personName, $daysOverDue,(string) $node->name);
//echo $personID.'-'.$personName.'-'.$dueDate.'-'.$dateToSeconds.'<br>';
}
}
}
return $response_object;
}
?>dateToSeconds function
This function transforms date (e.g., YYYY-MM-DD or Y-m-d) to seconds.
<?PHP
// changes date (e.g., YYYY-MM-DD or Y-m-d) to seconds
function dateToSeconds($date){
$dateToSeconds = strtotime($date);
return $dateToSeconds;
}
?>daysOverDue function
This function takes input date as seconds and figures out how many days person is over due.
<?PHP
// input date as seconds and figures out how many days person is over due
function daysOverDue($date){
$time = time();
$diff = $time - $date;
$days = floor($diff/86400);
return $days;
}
?>isOverDue function
This function takes input date as seconds and figures out if time as seconds as passed based on current time.
<?PHP
// input date as seconds and figures out if time as seconds as passed based on current time
function isOverDue($dateSeconds){
$time = time();
if($dateSeconds < $time)
return true;
return false;
}
?>