I happened to check my email folder containing The Village’s emails, and found an email where someone was in need of a mass addition to process queues using the CCB API.
Of course, you know this made me perk up a bit. I opened the email to find the need addressed as follows:
In our organization we want to be able to track people who have completed a certain curriculum.
We have about 10 inactive groups of people who have this curriculum in the last two years.
Is there a way to add all of these people to a process queue?
I know I could reactivate all the groups and then search by group name to do a mass add via an Advanced Search.
However, I already have a spreadsheet of these people with their individual IDs from CCB.
It would be much easier to add the people by their individual IDs.
Is achieving such a feat possible via the front-end web interface of CCB?
The short answer to this question is yes.
In fact, the individual in need could use the advanced people search feature, without having to change the status of the group, to mass add curriculum candidates in a new group or to a process queue.
But the one thing that is missing is that the search report doesn’t include the person’s id. Next.
Is achieving such a feat possible via the CBB API?
The short answer to this question is yes.
In fact, I’m going to show you how to solve this problem based on how the use case is written.
One of the first things to understand to begin today’s tutorial is knowing or learning how to parse Excel files.
We’ll use PHP to parse Excel or CSV files in this tutorial, and then add persons to a specific process queue using CCB’s API service add_individual_to_queue.
If the add_individual_to_queue API services sounds familiar, then that’s because we used this function in our last tutorial.
The difference in today’s tutorial versus last week’s tutorial is that today’s tutorial modifies the addIndividualToQueue function to include a note argument.
Are you ready to start? Then, let’s get started.
It’s time to start coding…
I’m not going to perform a deep dive into the details, but I will provide an overview. For more information, you can review previous tutorials.
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 parse-add-ids.php.
As we’ve performed in previous tutorials, include the necessary comments and file inclusions in this file.
To start, define the following variables and enter their respective values:
- queueID – The respective id of the process queue individuals are being added too.
- queueNote – Add a note when a person is added to a specific process queue. This is optional, but I always suggest adding a note and including a snippet of text about the person being added by an automated script.
- err_upTmpName – The file name that contains person ids. I used a .csv file for this tutorial and I recommend you do the same. Open the file and save it as a .csv from Excel or Numbers.
Use the code from the tutorial How to parse Excel and CSV files using PHP.
Look for the commented out lines that contain the text “// $data[0] = first name…”. We’ll need to change the following line of code from:
<?PHP
// $data[0] = first name; $data[1] = last name; $data[2] = email; $data[3] = phone
/*********************************************************************************************************************/
if(!empty($data[0]) && !empty($data[1]))
echo $data[0].' - '.$data[1].' - '.$data[2].' - '.$data[3].'<br/>';
?>to the following line of code:
<?PHP
// $data[0] = first name; $data[1] = last name; $data[2] = email; $data[3] = phone
/*********************************************************************************************************************/
if(!empty($data[0])){
addIndividualToQueue($queueID,$data[0],$queueNote);
echo 'Id '.$data[0].' has been added.<br/>';
}
?>The simple explanation is that we search to make sure there is a person’s id and the id is not empty.
If the respective person id is not empty, then the queueID, person’s id (i.e., $data[0]), and queueNote are passed as arguments to the addIndividualToQueue function.
Then, in the next line, text is printed to the screen to let you know a person has been added (see below).
READ THIS NEXT SECTION CAREFULLY
By the way, be sure to NOT EXECUTE, also meaning not to view in browser more than once, this report multiple times. Executing the script multiple times adds the same people into the respective process queue. Yes, you’ll have duplicates, leaving you with a manual nightmare to clean up by hand. SO BE CAREFUL TO ONLY EXECUTE SCRIPT ONE TIME.
Another thing to make note of about this script is that I DID NOT include error checking in the addIndividualToQueue function.
This means you’ll have to be logged into CCB, and manually monitor whether or not a person is actually entered into your respective queue.
Yes, I know I’m being lazy, but I am getting you 90% of the way to your objective, right? That’s what I thought. Extend me a bit of grace, please and thank you. 🙂
If you wanted to, you could parse the addIndividualToQueue function’s XML response for the entered or created date. If no date is returned, then it’s safe to assume the person was not added to the respective queue.
If you need assistance parsing the XML response, then, you guessed it, I have a tutorial for it as well.
Bonus Tip: More than Process Queues…
Yes, you can add people to more than just Process Queues.
In fact, you can use the same addIndividualToQueue function (seen below), although you need to change the name of it, with slight modifications to perform the following:
- Use add_individual_to_event service to add individuals to a specific event
- Use add_individual_to_group service to add individuals to a specific group
- Use add_individual_to_position service to add individuals to a specific position
- Use add_individual_to_significant_event to create a significant event record for individuals
Don’t forget that you’ll have to check the CCB API Documentation to be sure you identify and verify the mandatory and optional fields for each service.
<?PHP
// adds a person to a specific queue based on queue id and individual id
function addIndividualToQueue($qid,$pid,$noteMsg){
$apiService = 'add_individual_to_queue'; // CCB api service
$personID = $pid;
//$noteMsg = 'Person added to Queue by Automated Report';
$urlData = array_filter( array(
'srv' => "$apiService"
,'individual_id' => "$personID"
,'queue_id' => "$qid"
,'note' => "$noteMsg"
) );
$rss = ccbDetails('get',$urlData);
}
?>Bringing it all together as the final solution
Okay, so you are now ready to save and test your code, opening the file using a web browser.
Remember what I said about only successfully executing the code once. 😉
Well, that’s it for today’s tutorial. I’ll be back with another tutorial next week. See you then.
<?PHP
/**
* parse-add-ids.php
*/
// contains resusable globals and functions
include("includes/config.php");
$queueID = '56'; // Specific queue id that person should be added too.
$queueNote = 'This person was added to the queue by automated script.'; // You can attach a note to a person when they are placed in a queue.
$err_upTmpName = 'personids.csv'; // name of file to parse
$row = 0;
if (($handle = fopen($err_upTmpName, "r")) !== FALSE) {
while (($data = fgetcsv($handle, 0, ",")) !== FALSE) {
if($row == 0){
$row++;
} else {
// $data[0] = first name; $data[1] = last name; $data[2] = email; $data[3] = phone
/*********************************************************************************************************************/
if(!empty($data[0])){
addIndividualToQueue($queueID,$data[0],$queueNote);
echo 'Id '.$data[0].' has been added.<br/>';
}
}
}
} else {
echo 'File could not be opened.';
}
fclose($handle);
// adds a person to a specific queue based on queue id and individual id
function addIndividualToQueue($qid,$pid,$noteMsg){
$apiService = 'add_individual_to_queue'; // CCB api service
$personID = $pid;
//$noteMsg = 'Person added to Queue by Automated Report';
$urlData = array_filter( array(
'srv' => "$apiService"
,'individual_id' => "$personID"
,'queue_id' => "$qid"
,'note' => "$noteMsg"
) );
$rss = ccbDetails('get',$urlData);
}
?>