SmartCALLHANDLER: API and customisation

You can customise SmartCALLHANDLER using our 'hooks' and the 'ST_API' function. Details of this are below. You require knowledge of JavaScript programming and the ability to add your code to the page where you have placed the SmartCALLHANDLER snippet.

Hooks

If you define functions in JavaScript as per the below they will be called by SmartCALLHANDLER at the indicated times and with the data specified below:

hook_new() => New person selected, fired just before the form is displayed
results = hook_search(results) => Results from the search, fired just before the results are displayed. You MUST return the results array from this function. This allows you to alter the results if you so wish i.e. append data or filter further. The value 'results' is an array containing objects per constituent that features in the results i.e.:

{
'id': constituent_record_id,
'name': constituent_name,
'address': constituent_address_string,
'lookup_id': constituent_lookup_id'
}

results = hook_search_rendered(results) => as hook_search but after results have been rendered on screen
hook_constituent(constituent) => Person selected, fired just before the form is displayed. The value 'constituent' is the data provided by the SKY API call https://api.sky.blackbaud.com/constituent/v1/constituents/[constituent_id] with docs here: https://developer.sky.blackbaud.com/docs/services/56b76470069a0509c8f1c5b3/operations/GetConstituent
NXT version ONLY:

hook_profile_form_ready(constituent) => fired just before the profile form is displayed. Where constituent is either null (blank form) or the constituent record data from SmartPORTAL. This allows you to alter the profile form before the user sees it. If not null, the constituent data is already populated in the form at this point.
hook_ready() => fired when the callhandler form has been loaded and is ready for use.

Online Express based version ONLY:

gifts = hook_gifts(gifts) => Person selected and gifts retrieved (after form is displayed and gifts rendered). You MUST return the gifts array from this function. This allows you to alter the results if you so wish i.e. append data or filter further. The value 'gifts' is the data provided by the SKY API call https://api.sky.blackbaud.com/gift/v1/gifts with docs here: https://developer.sky.blackbaud.com/docs/services/58bdd5edd7dcde06046081d6/operations/ListGifts
Note: Other versions of SmartCALLHANDLER use the ST_API function as detailed below to allow clients to retrieve gifts and other information in more flexible ways (See Example 3).

ST_API

This function allows you to access ALL the read only functions available via Blackbaud's SKY API as documented here https://developer.sky.blackbaud.com/. You do not need to set up your own connection to the SKY APIs or deal with OAUTH tokens as the ST_API function does this for you. NOTE: Read only API calls are those that use the GET method and not the POST, PATCH or DELETE methods, this is detailed in the Blackbaud documentation.

function ST_API(_url, _success, _fail, _datapassthru)

_url: the API endpoint path after https://api.sky.blackbaud.com/
_success: the function to call with the result _success(data, _datapassthru)
_fail: the function to call if the API call fails _fail(msg, response_code, _datapassthru)
_datapassthru: data to pass on as arguments to the _success and _fail functions

An example of use of this API along with the hooks is below.

Example script 1 - Online Express SmartCALLHANDLER - Fetch constituent codes

Example script to fetch constituent codes of the selected record.

<script>
/* global ST_API, jQuery, bb$ */
function hook_constituent(constituent) {
var $ = jQuery || bb$;
ST_API('constituent/v1/constituents/' + constituent.id + '/constituentcodes',
function (data) {
if (!data.hasOwnProperty('value')) {
console.log('API Error cons codes: ' + JSON.stringify(data));
} else {
var conscodes = data.value;
console.log(conscodes);
$.each(conscodes, function (i, code) {
// in this example select the designation that matches the conscode (the radio station in our use case)
var desig = $('#bboxdonation_designation_ddDesignations');
if (desig.length > 0) {
var station = code.description.split("-")[0].trim();
var opt = desig.find('option').filter(function () {
return $(this).text().indexOf(station) != -1;
});
if (opt.length > 0) {
desig.val(opt.val()).change();
return false;
}
}
});
}
},
function (msg) {
// error
console.log('API Error cons codes (2): ' + msg);
}
);
}
</script>

Example script 2 - All versions of SmartCALLHANDLER - Fetch spouse and append to search results

Example script to fetch spouse information for each result. We do this on delayed load so the results can be displayed immediately and then we go through each and append spouse information.

<script>
/* global ST_API, jQuery, bb$ */
function hook_search_rendered(results) {
var $ = jQuery || bb$;
// Build the search URL
if (results.length > 0) {
var url = 'constituent/v1/constituents?';
$(results).each(function (i, one) {
url += 'constituent_id=' + one.id + '&';
});
url += 'fields=id,spouse';
}
console.log('Searching for spouses');
ST_API(url, function (data) {
if (!data.hasOwnProperty('value')) {
console.log('API Error Spouse: ' + JSON.stringify(data));
} else {
var cons = data.value;
$.each(cons, function (j, cons) {
if (cons.spouse.hasOwnProperty("last")) {
console.log('Spouse found');
console.log(cons.spouse);
var name = (cons.spouse.hasOwnProperty("first") ? cons.spouse.first + " " : "");
name += (cons.spouse.hasOwnProperty("last") ? cons.spouse.last : "");
$('#constituent_' + cons.id + ' .constituent_name').append(
'<br>(Spouse: ' + name.trim() + ')');
}
});
}
},
function (msg) {
// error
console.log('API Error Spouse (2): ' + msg);
});
return results;
}
</script>

Example script 3 - All versions of SmartCALLHANDLER - Fetch filtered gift details

Example script to fetch spouse information for each result. We do this on delayed load so the results can be displayed immediately and then we go through each and append spouse information.

<script>
/* global ST_API, jQuery, bb$ */
function hook_constituent(constituent) {
var $ = jQuery || bb$;
$('#giftList').remove();
ST_API('gift/v1/gifts?constituent_id=' + constituent.id +
'&gift_type=RecurringGift&gift_type=Pledge&gift_type=Cash',
function (data) {
if (!data.hasOwnProperty('value')) {
console.log('API Error Gifts: ' + JSON.stringify(data));
} else {
var gifts = data.value;
var profile_form = $('#smartportal-profile_form,#mongo-form');
console.log(gifts);
gifts.sort(function(a,b) {
var dta = new Date(a.date);
var dtb = new Date(b.date);
if (dta.getTime() < dtb.getTime()) { return 1; }
if (dta.getTime() > dtb.getTime()) { return -1; }
return 0;
});

// Build table of results
var html = '<div id="giftList"><h2>Recent gifts</h2><table class="resultsList"><tbody>';
html +=
'<tr><th width="20%">Date</th><th width="40%">Type</th><th width="20%">Amount</th><th>Status</th></tr>';
$.each(gifts, function (i, gift) {
var dt = new Date(gift.date);
var amt = gift.amount.value.toFixed(2);
html +=
'<tr>' +
'<td>' + dt.toLocaleDateString() + '</td>' +
'<td>' + gift.type.replace(/([A-Z])/g, " $1").trim() + '</td>' +
'<td>' + amt + '</td>' +
'<td>' + gift.gift_status + '</td>' +
'</tr>';
});
html += '</tbody></table></div>';
profile_form.prepend(html);
}
}
},
function (msg) {
// error
console.log('API Error Gifts: ' + msg);
}
);
}
function hook_new() {
$('#giftList').remove();
}
</script>