Of course, what a response received from last week’s tutorial in regards to displaying CCB groups on your website using CCB’s API.
I had a feeling there were quite a few of your churches wanting to implement such functionality. And if you hadn’t been currently pondering it, you had at some point wished for customization of the native CCB group search functionality.
In this week’s tutorial, I’ll share with you how to go about creating groups. Of course, most of everyone using CCB likely already has groups created.
If you’re new to CCB and migrating from another church management software solution, then you’re likely hoping and strongly desiring a way to avoid the manual labor of entering groups into CCB.
In fact, it’s quite easy to use the CCB API to create new groups. Ready to begin? Let’s get started.
Pre-requisites for Group Creation
The Create Group API service requires a few parameters each time a group is created. Refer to CCB’s API documentation for a complete list of parameters, but do note the following parameters are REQUIRED for each group:
- name
- campus_id
- main_leader_id
In addition, there are also considerations to remember and adhere too when executing the Create Group API Service (per CCB’s API documentation).
Keep in mind that a group can NOT have:
- interaction type of administrative and membership type of open to all
- interaction type of administrative and listed set to true
- interaction type of administrative and public search listed set to true
- membership type of open to all and listed set to false
So, if you encounter errors, then it’s likely one of the aforementioned considerations that may have been violated.
Setting up Service, Required, and Optional Parameters
It’s time to code! Open a text editor of your choice, and include the config.php file that contains reusable globals and functions.
Immediately following the includes and comments on the next open line, create and define the apiService variable to be equal to the CCB API Create Group service: create_group.
<?PHP
/**
* create group profile
*/
// contains reusable globals and functions
include("includes/config.php");
$apiService = 'create_group'; // CCB api service
?>Define the Required Parameter Variables and Values
Next, the Create Group API service has a set of required fields that MUST be defined when creating a group.
Before you create the group, it’s essential to identify and define the following variables:
- groupName variable is equal to the group’s name (string)
- campusId variable is equal to the campus id found in CCB (integer)
- groupLeaderId variable is equal to the person’s CCB profile id that leads the group (integer)
If you need assistance finding any of the values, especially campusId and groupLeaderId variable values, then please refer to CCB’s API documentation, specifically the required parameters for the create_group API service.
<?PHP // group fields per CCB required and optional parameters // REQUIRED PARAMETERS $groupName = 'Test Group'; $campusId = 1; $groupLeaderId = 5; ?>
Define the Optional Parameter Variables and Values
At this point, you could easily create a group based on the required parameters being defined and containing their respective and valid values.
Nevertheless, once the required variables have been defined, you’ll have the choice of defining optional parameters.
The are a number of optional parameters that can be defined when creating a group profile. Per CCB API documentation, the following optional parameters exist:
- description – group text description
- group_type_id – the integer value for what type of group it is
- department_id – if the group has a department id association, typically an integer
- area_id – integer id of the area where the group is located or held when meeting
- group_capacity – integer value for the number of persons a group serves
- meeting_location_street_address – exact street address of where group meets
- meeting_location_city – city in which group meets
- meeting_location_state – state in which group meets
- meeting_location_zip – zip code where group is located
- meeting_day_id – integer value for the day of the week the group meets
- meeting_time_id – integer value for the time of day a group meets
- childcare_provided – boolean value of whether or not the group offers childcare (true or false)
- interaction_type – the type of interaction group allows via CCB
- membership_type – the type of membership group desired when using CCB
- listed – default is boolean value of true (typically not set)
- public_search_listed – default is boolean value of false and must be set to true to allow public group search and group to be listed using search functionality.
There are 3 additional fields that expect integer values but are not used in this tutorial:
- udf_group_pulldown_1_id
- udf_group_pulldown_2_id
- udf_group_pulldown_3_id
<?PHP // OPTIONAL PARAMETERS $groupDescription = 'This is a test group using the CCB API Create Group service.'; $groupTypeId = 9; $departmentId = 10; $areaId = 5; $groupCapacity = 30; $meetingLocationStreetAddress = '123 Testing Avenue'; $meetingLocationCity = 'Testing'; $meetingLocationState = 'TX'; $meetingLocationZip = '78729'; $meetingDayId = 3; $meetingTimeId = 5; $childcareProvided = true; $interactionType = 'Members Interaction'; $membershipType = 'Open to All'; $listed = true; $publicSearchListed = true; ?>
Binding CCB API Paramater Labels to Respective Variables
Now that Required and Optional variables have both been defined, it’s time to bind both to their respective CCB labels.
To bind labels to their respective variables, define a urlData variable. Set this variable equal to an encapsulated key-value pair array, using PHP’s built-in array_filter method (as shown below).
Once data labels and variables are bound together, the CCB API call can be made to create group.
<?PHP
$urlData = array_filter( array(
'srv' => "$apiService",
'name' => "$groupName",
'campus_id' => "$campusId",
'main_leader_id' => "$groupLeaderId",
'description' => "$groupDescription",
'group_type_id' => "$groupTypeId",
'department_id' => "$departmentId",
'area_id' => "$areaId",
'group_capacity' => "$groupCapacity",
'meeting_location_street_address' => "$meetingLocationStreetAddress",
'meeting_location_city' => "$meetingLocationCity",
'meeting_location_state' => "$meetingLocationState",
'meeting_location_zip' => "$meetingLocationZip",
'meeting_day_id' => "$meetingDayId",
'meeting_time_id' => "$meetingTimeId",
'childcare_provided' => "$childcareProvided",
'interaction_type' => "$interactionType",
'membership_type' => "$membershipType",
'listed' => "$listed",
'public_search_listed' => "$publicSearchListed"
) );
?>Making CCB API Call to Create Group and Display Response
To make the CCP API call, use the ccbDetails function, which is set as the value of the rss variable, passing it get as the first argument and the newly created urlData variable as its second argument.
Next, create a nodes variable and define the value of it use the rss variable which references PHP’s built-in XPATH query method.
In short, the data retrieved from the CCB API when creating a group must be transformed to XML. The XPATH query allows for parsing of the transformed response data using the following query expression: //groups/group.
Once the response data has been appropriately transformed, the nodes variable can be printed to the web browser using PHP’s built-in print_r method. This method allows for arrays to be printed and displayed to the screen.
And that’s all there is to this tutorial
<?PHP
$rss = ccbDetails('get',$urlData); // transform to XML
$nodes = $rss->xpath('//groups/group'); // xpath for groups
print_r($nodes);
?>Time to test, display and check CCB for a new group entry
The time has come to save and execute your file via a web browser. Your code should look like the following:
<?PHP
/**
* create group profile
*/
// contains reusable globals and functions
include("includes/config.php");
$apiService = 'create_group'; // CCB api service
// group fields per CCB required and optional parameters
// REQUIRED PARAMETERS
$groupName = 'Test Group';
$campusId = 1;
$groupLeaderId = 5;
// OPTIONAL PARAMETERS
$groupDescription = 'This is a test group using the CCB API Create Group service.';
$groupTypeId = 9;
$departmentId = 10;
$areaId = 5;
$groupCapacity = 30;
$meetingLocationStreetAddress = '123 Testing Avenue';
$meetingLocationCity = 'Testing';
$meetingLocationState = 'TX';
$meetingLocationZip = '78729';
$meetingDayId = 3;
$meetingTimeId = 5;
$childcareProvided = true;
$interactionType = 'Members Interaction';
$membershipType = 'Open to All';
$listed = true;
$publicSearchListed = true;
$urlData = array_filter( array(
'srv' => "$apiService",
'name' => "$groupName",
'campus_id' => "$campusId",
'main_leader_id' => "$groupLeaderId",
'description' => "$groupDescription",
'group_type_id' => "$groupTypeId",
'department_id' => "$departmentId",
'area_id' => "$areaId",
'group_capacity' => "$groupCapacity",
'meeting_location_street_address' => "$meetingLocationStreetAddress",
'meeting_location_city' => "$meetingLocationCity",
'meeting_location_state' => "$meetingLocationState",
'meeting_location_zip' => "$meetingLocationZip",
'meeting_day_id' => "$meetingDayId",
'meeting_time_id' => "$meetingTimeId",
'childcare_provided' => "$childcareProvided",
'interaction_type' => "$interactionType",
'membership_type' => "$membershipType",
'listed' => "$listed",
'public_search_listed' => "$publicSearchListed"
) );
$rss = ccbDetails('get',$urlData); // transform to XML
$nodes = $rss->xpath('//groups/group'); // xpath for groups
print_r($nodes);
?>Once executed, the web browser should display a multi-dimensional array of group information you submitted for creation.
In addition, you can check CCB to ensure that the group did get created and with the proper information by going to the groups section within their native web application.
Do keep in mind that this is a single group entry that is created. It’s a very manual process.
If you have more than one group you would like to create using the CCB API, then I suggest you view the following tutorials for how to parse Excel/CSV files:
Both tutorials should give clues and insight as for how to harness the power of PHP to create a spreadsheet loaded with all groups and their respective data.
If you need help, or run into any issues, please don’t hesitate to contact us. Or give us a visit should you want to hire us.
See you back here next week. 😉