Welcome back to CCB Tutorials! Today’s tutorial is one that many folks have likely pondered but may or may not have desired or been too intimidated by to dive into the details.
From weekend services to special events to classes to seminars to workshops and the list continues, managing events in CCB is likely one of the top three actions used by most churches.
While CCB serves small to medium-sized congregations well in regards to event management, larger congregations often require self-managed event functionality, especially multi-site or multi-campus church organizations.
I’ve recently fielded inquiries from churches pertaining to the integration of 3rd-party event management software with CCB.
While most of the event management will occur in the 3rd-party system, there is also a need to create and track event and registration data upon close of event.
While an event with 100-150 registrants/attendees is roughly easy to manually manage, reconciling event and registration data for hundreds or thousands of persons is simply not possibly without a team of volunteers or staff.
Nevertheless, I’ll share how to create events in CCB using PHP and CCB’s API in today’s tutorial. Of course, your respective 3rd-party event management software will need to have an available API.
In addition, I’ve also written a few tutorials pertaining to accessing event attendance data that you’ll likely want to combine with today’s tutorial. But without further ado, let’s get started!
Pre-requisites for Group Creation
To create a CCB event using PHP and CCB’s API, the create_event API service will be used. Refer to CCB’s API documentation for a definition of the service, required parameters, and optional parameters.
While I’ve listed the create_event API service’s optional parameters below commented out, the following are required parameters that MUST be identified before continuing the tutorial:
- group_id
- start_date
- end_date
- name
Of the listed parameters above, the group_id parameter is one that can be programmatically searched for using group_profiles API service.
Although I won’t cover it in this tutorial, you could easily setup a web page that would display groups in a drop-down menu for selection along with datetime pickers and an input for the event name. That would spruce up the user interface and experience quite a bit. 😉
With the aforementioned required parameters, now it’s time to open a text editor of your choice, including the config.php, comments, api service, and required/optional parameters needed for the API call.
The apiService variable’s value will be equal to the create_event API service. Using the aforementioned required parameters above, then identify and define their respective values:
- group_id variable equal to an integer
- start_date variable equal to datetime
- end_date variable equal to datetime
- event_name variable equal to string
<?PHP
// contains resusable globals and functions
include("includes/config.php");
$apiService = 'create_event';
$servData = array_filter( array(
'srv' => "$apiService"
) );
$group_id = 5;
$start_date = '2018-10-10';
$end_date = '2018-10-10';
$event_name = 'Test CCB Event';
?>Binding CCB API Parameter Labels to Respective Variables
Now that apiService, required parameter, and optional parameter variables are defined with their respective values, servData and urlData variables can now be created and binded to their respective CCB label.
To bind labels, define a urlData variable, setting its value equal to an encapsulated key-value part array, using PHP’s built-in array_filter method (as shown below).
For the sake of this tutorial, I’m not including optional parameters. I do list operation parameters in the urlData variable, but commented out. Feel free to uncomment desired parameters.
Once data labels and variable are binded, the CCB API call be be made to create event.
<?PHP $urlData = array_filter( array( // required parameters 'group_id' => "$group_id", // integer 'start_date' => "$start_date", // datetime 'end_date' => "$end_date", // datetime 'name' => "$event_name" // string /* // optional parameters ,'description' => "$event_description", // string 'leader_notes' => "$leader_notes", // string 'setup_minutes' => "$setup_minutes", // integer 'clean_minutes' => "$clean_minutes", // integer 'setup_notes' => "$setup_notes", // string 'organizer_id' => "$organizer_id", // integer 'contact_phone' => "$contact_phone", // string 'event_type_id' => "$event_type_id", // integer 'registration_form_id' => "$registration_form_id", // integer 'event_grouping_id' => "$event_grouping_id", // integer 'registration_limit' => "$registration_limit", // integer 'recurrence_type' => "$recurrence_type", // string => daily, weekly, monthy 'recurrence_frequency' => "$recurrence_frequency", // integer => greater than 0 'recurrence_week_number' => "$recurrence_week_number", // string => first, second, third, fourth, last 'recurrence_day_of_week' => "$recurrence_day_of_week", // string => mon, tue, wed, thu, fri, sat, sun 'recurrence_day_of_month' => "$recurrence_day_of_month", // integer => between 0 and 31 'recurrence_end_date' => "$recurrence_end_date", // datetime 'number_of_occurrences' => "$number_of_occurrences", // integer 'location_name' => "$location_name", // integer 'location_street_address' => "$location_street_address", // integer 'location_city' => "$location_city", // integer 'location_state' => "$location_state", // string 'location_zip' => "$location_zip", // integer 'notification' => "$notification", // boolean 'attendance_reminder' => "$attendance_reminder", // boolean 'uses_resources' => "$uses_resources", // boolean 'use_campus_address' => "$use_campus_address", // boolean 'listed' => "$listed", // boolean 'creator_id' => "$creator_id" // integer */ ) ); ?>
Making CCB API Call to Create an Event and Display Response
To make a CCB API call to create an event, use the ccbDetails function. Most of the previously written tutorials are using GET rather than POST as the first argument of the ccbDetails function.
Because POST is needed to make the CCB API call, the CCB API service (i.e., create_event) will need to be separated from the urlData variable data and into their distinct variables as shown in previous sections.
Pass the urlData variable as the second argument and the servData variable as the third argument of ccbDetails function. The ccbDetails function does the heavy lifting to authenticate, authorize, access, and retrieve data from the CCB system.
Once the response is successfully returned as defined by the rss variable, create a nodes variable, setting it equal to the rss variable.
The rss variable uses a reference or pointer to parse the response data using the following expression in conjunction to PHP’s XPATH query method: //response/event.
<?PHP
$rss = ccbDetails('post',$urlData,$servData); // transform to XML
$nodes = $rss->xpath('//response/event'); // xpath for response->event
?>We’re ready now to parse and display the CCB API response. Using the nodes variable, define a variable named theCount and set it equal to PHP’s built-in count method, passing to it the nodes variable.
theCount variable is used to determined whether or not an event was created and returned when making the CCB API call to create an event. Next, definite and set an empty response_object variable.
Now it’s time for a bit of logic to determine whether or not an event was successfully created. We’ll use theCount variable to do so.
In short, if theCount variable is greater than zero, then an event was created, as shown by setting the response_object variable equal to the following text: “Event created.”.
In addition, you could also access event data if needed using a foreach statement and passing to it the nodes variable.
Within the foreach statement, access each event element or attribute accordingly. In this tutorial, I’ve chosen return the event id and name as verification event was successfully created in CCB system.
See CCB documentation for specific element and attributes for the create_event API service.
If an event is not created, then the response_object variable within the else statement is set equal to the following text: “Event not created.”.
Last but not least, echo the response_object and that’s all for this tutorial!
<?PHP
$theCount = count($nodes);
$response_object = '';
if( $theCount > 0){
$response_object = 'Event created.';
foreach ($nodes as $node){
$response_object .= ' '.$node['id'].' - '.$node->name;
}
} else {
$response_object = 'Event not created.';
}
echo $response_object;
?>Time to Put it All Together and Test
Now it’s time to put each block of code together and test your technical prowess. Only execute the code once from a web browser, or you will have multiple events named the same in your CCB System.
Save and execute the code (see below), and then check your CCB to see if the event was successfully added and its attributes set according to the required and optional parameter settings within your code.
Although this tutorial is simple in nature, it can certainly be expounded upon and used to integrate your CCB system with 3rd-party event management systems.
In closing, please leave comments and questions below. Thanks and see you back here next week for another CCB Tutorial. 😉
<?PHP
// contains resusable globals and functions
include("includes/config.php");
$apiService = 'create_event';
$servData = array_filter( array(
'srv' => "$apiService"
) );
$group_id = 5;
$start_date = '2018-10-10';
$end_date = '2018-10-10';
$event_name = 'Test CCB Event';
$urlData = array_filter( array(
// required parameters
'group_id' => "$group_id", // integer
'start_date' => "$start_date", // datetime
'end_date' => "$end_date", // datetime
'name' => "$event_name" // string
/*
// optional parameters
,'description' => "$event_description", // string
'leader_notes' => "$leader_notes", // string
'setup_minutes' => "$setup_minutes", // integer
'clean_minutes' => "$clean_minutes", // integer
'setup_notes' => "$setup_notes", // string
'organizer_id' => "$organizer_id", // integer
'contact_phone' => "$contact_phone", // string
'event_type_id' => "$event_type_id", // integer
'registration_form_id' => "$registration_form_id", // integer
'event_grouping_id' => "$event_grouping_id", // integer
'registration_limit' => "$registration_limit", // integer
'recurrence_type' => "$recurrence_type", // string => daily, weekly, monthy
'recurrence_frequency' => "$recurrence_frequency", // integer => greater than 0
'recurrence_week_number' => "$recurrence_week_number", // string => first, second, third, fourth, last
'recurrence_day_of_week' => "$recurrence_day_of_week", // string => mon, tue, wed, thu, fri, sat, sun
'recurrence_day_of_month' => "$recurrence_day_of_month", // integer => between 0 and 31
'recurrence_end_date' => "$recurrence_end_date", // datetime
'number_of_occurrences' => "$number_of_occurrences", // integer
'location_name' => "$location_name", // integer
'location_street_address' => "$location_street_address", // integer
'location_city' => "$location_city", // integer
'location_state' => "$location_state", // string
'location_zip' => "$location_zip", // integer
'notification' => "$notification", // boolean
'attendance_reminder' => "$attendance_reminder", // boolean
'uses_resources' => "$uses_resources", // boolean
'use_campus_address' => "$use_campus_address", // boolean
'listed' => "$listed", // boolean
'creator_id' => "$creator_id" // integer
*/
) );
$rss = ccbDetails('post',$urlData,$servData); // transform to XML
/*
echo '<pre>';
print_r($rss);
echo '</pre>';
die();
*/
$nodes = $rss->xpath('//response/event'); // xpath for response->event
$theCount = count($nodes);
$response_object = '';
if( $theCount > 0){
$response_object = 'Event created.';
foreach ($nodes as $node){
$response_object .= ' '.$node['id'].' - '.$node->name;
}
} else {
$response_object = 'Event not created.';
}
echo $response_object;
?>