Hi there, and welcome to today’s CCB Tutorial.
Today we’ll explore a service that you’ll likely want to become familiar with, and one that likely goes unnoticed.
However, if you’ve used the Church Community Builder system, then it’s likely you’ve encountered a situation where you have duplicate profiles.
Duplicate CCB profiles are created and often happen because of one the following reasons:
- Person’s name and contact info is fat fingered, or entered incorrectly
- Person uses multiple aliases
- Person uses multiple emails
- Person gets married or divorce
- Person stops coming for a time period, then re-engages
But have you ever wondered exactly how many duplicate merges have been processed via your CCB account?
Well, today’s tutorial will cover that and more. Let’s get started.
Setting up variables, comments, and inclusion files
Open the text editor of your choice, and create and save a php file, naming it merged-persons.php.
As usual, include the necessary comments and file inclusions. Once you complete that step, then you’re ready to define the following variables with their respective values:
- apiService – Set the value to be the merged_individuals CCB API Service
- modifiedDate – this is an optional datetime (e.g., YYYY-MM-DD) field to limit the number of records return after a certain datetime.
The variables are now defined and set accordingly. Time to create the urlData variable that is passed as the second argument of the ccbDetails function (soon to be discussed).
Nevertheless, define the urlData variable using the built-in PHP array_filter method, setting and bidding the following fields:
- srv => apiService variable
- modified_since => modifiedDate variable (optional)
<?PHP
<?PHP
// contains resusable globals and functions
include("includes/config.php");
$apiService = 'merged_individuals'; // CCB api service
$modifiedDate = date('Y-m-d'); // sample field to search for (See CCB API documentation for more $apiService fields)
$modifiedDate = '2016-07-01';
$urlData = array_filter( array(
'srv' => "$apiService",
'modified_since' => "$modifiedDate"
) );
?>Making API Call and Parsing XML Response
In the previous section, I mentioned the ccbDetails function. This is a critical piece of the puzzle to successfully making a CCB API call.
If you’re not familiar with the ccbDetails function, then you’ll want to review and read this tutorial.
Nevertheless, define the rss variable and set it equal to the ccbDetails function.
Next, set a nodes variable equal to $rss->xpath function. The XPATH function allows for parsing the XML response from your CCB API call. Set the XPATH expression to use the following: //merged_individuals/merged_individual.
Now set an empty response_object variable that we’ll use to capture and concatenate the merged individual data for each person.
<?PHP
$rss = ccbDetails('get',$urlData); // transform to XML
$nodes = $rss->xpath('//merged_individuals/merged_individual'); // xpath for individuals->individual
$response_object = '';
?>The nodes variable now holds all the information for each merged individual. To parse each individual’s respective data, we’ll create a foreach statement, integrating over the nodes variable until complete.
Before we continue, you must know that the merged_individuals API service DOES NOT provide the first and last name, or full name of individuals.
This API service simply provides the individual id’s for the winning and losing profiles.
To obtain the winning profile name, I’ve created a function to accept a person’s CCB id and returns the full name using the individual_profile_from_id: getIndividualProfileFullName.
Note: Losing person’s full name cannot be returned because profile was merged and no longer exists. 😉
Don’t forget to be sure to include the function in your general.php file too, or your function won’t worky. 😉
Once within the foreach statement, simply define and set the winningPersonName variable equal to the getIndividualProfileFullName function, having passed the respective ids.
Next, set the response_object variable to concatenate each iteration using the .= operator, and set the following fields:
- winningPersonName variable
- $node->winner_id
- $node->loser_id
- $node->date_merged
Finally, close the foreach statement and echo the response_object variable.
<?PHP
foreach ($nodes as $node)
{
$winningPersonName = getIndividualProfileFullName($node->winner_id);
$response_object .= $winningPersonName.' - Winner Id: '.$node->winner_id.' | Loser Id: '.$node->loser_id.' | Date Merged: '.$node->date_merged."<br/>"; // now print the person's full name and age (See CCB API documentation for more $apiService fields)
}
echo $response_object;
?>Time to test your coding skills
It’s time to put it together and save your file. Now you’re ready to test your code in a web browser.
<?PHP
// contains resusable globals and functions
include("includes/config.php");
$apiService = 'merged_individuals'; // CCB api service
$modifiedDate = date('Y-m-d'); // sample field to search for (See CCB API documentation for more $apiService fields)
$modifiedDate = '2016-07-01';
$urlData = array_filter( array(
'srv' => "$apiService",
'modified_since' => "$modifiedDate"
) );
$rss = ccbDetails('get',$urlData); // transform to XML
$nodes = $rss->xpath('//merged_individuals/merged_individual'); // xpath for individuals->individual
$response_object = '';
foreach ($nodes as $node)
{
$winningPersonName = getIndividualProfileFullName($node->winner_id);
$losingPersonName = getIndividualProfileFullName($node->loser_id);
$response_object .= $winningPersonName.' - Winner Id: '.$node->winner_id.' | Loser Id: '.$node->loser_id.' | Date Merged: '.$node->date_merged."<br/>"; // now print the person's full name and age (See CCB API documentation for more $apiService fields)
}
echo $response_object;
?>You should see something along the following lines:
This is a quick way to understand how many duplicates have occurred, and a good way to obtain the previous id of a person should an accidental merge occur (trust me, it happens from time to time).
I encourage you build on this tutorial, saving the data to a Excel/CSV file. I wish you coding success and hope this tutorial has been beneficial to and for you.
See you back next week for another tutorial.
getIndividualProfileFullName function
<?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;
}
?>