Creating a Queue overdue list of persons report

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.

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.

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.

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.

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.

getQueueIndividuals function

This function retrieves a list of individuals in a specific queue with a specific status, returning a multi-dimensional array.

getIndividualQueueStatus function

This function determines how many days an individual has been in queue and returns an array.

dateToSeconds function

This function transforms date (e.g., YYYY-MM-DD or Y-m-d) to seconds.

daysOverDue function

This function takes input date as seconds and figures out how many days person is over due.

isOverDue function

This function takes input date as seconds and figures out if time as seconds as passed based on current time.

 


Please comment if this tutorial has helped you.