SmartCALLHANDLER: API and customisation

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:
  1. hook_new() => New person selected, fired just before the form is displayed
  2. 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.:
    1. {
      'id': constituent_record_id,
      'name': constituent_name,
      'address': constituent_address_string,
      'lookup_id': constituent_lookup_id'
      }
  3. results = hook_search_rendered(results) => as hook_search but after results have been rendered on screen
  4. 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 
  5. NXT version ONLY: 
    1. 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.
    2. hook_ready() => fired when the callhandler form has been loaded and is ready for use.
  6. Online Express based version ONLY:
    1. 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) 
  1. _url: the API endpoint path after https://api.sky.blackbaud.com/
  2. _success: the function to call with the result _success(data, _datapassthru)
  3. _fail: the function to call if the API call fails _fail(msg, response_code, _datapassthru)
  4. _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.
  1. <script>
  2. /* global ST_API, jQuery, bb$ */
  3. function hook_constituent(constituent) {
  4. var $ = jQuery || bb$;
  5. ST_API('constituent/v1/constituents/' + constituent.id + '/constituentcodes',
  6. function (data) {
  7. if (!data.hasOwnProperty('value')) {
  8. console.log('API Error cons codes: ' + JSON.stringify(data));
  9. } else {
  10. var conscodes = data.value;
  11. console.log(conscodes);
  12. $.each(conscodes, function (i, code) {
  13. // in this example select the designation that matches the conscode (the radio station in our use case)
  14. var desig = $('#bboxdonation_designation_ddDesignations');
  15. if (desig.length > 0) {
  16. var station = code.description.split("-")[0].trim();
  17. var opt = desig.find('option').filter(function () {
  18. return $(this).text().indexOf(station) != -1;
  19. });
  20. if (opt.length > 0) {
  21. desig.val(opt.val()).change();
  22. return false;
  23. }
  24. }
  25. });
  26. }
  27. },
  28. function (msg) {
  29. // error
  30. console.log('API Error cons codes (2): ' + msg);
  31. }
  32. );
  33. }
  34. </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.
  1. <script>

  3. /* global ST_API, jQuery, bb$ */
  4. function hook_search_rendered(results) {
  5. var $ = jQuery || bb$;
  6. // Build the search URL
  7. if (results.length > 0) {
  8. var url = 'constituent/v1/constituents?';
  9. $(results).each(function (i, one) {
  10. url += 'constituent_id=' + one.id + '&';
  11. });
  12. url += 'fields=id,spouse';
  13. }

  15. console.log('Searching for spouses');
  16. ST_API(url, function (data) {
  17. if (!data.hasOwnProperty('value')) {
  18. console.log('API Error Spouse: ' + JSON.stringify(data));
  19. } else {
  20. var cons = data.value;
  21. $.each(cons, function (j, cons) {
  22. if (cons.spouse.hasOwnProperty("last")) {
  23. console.log('Spouse found');
  24. console.log(cons.spouse);
  25. var name = (cons.spouse.hasOwnProperty("first") ? cons.spouse.first + " " : "");
  26. name += (cons.spouse.hasOwnProperty("last") ? cons.spouse.last : "");
  27. $('#constituent_' + cons.id + ' .constituent_name').append(
  28. '<br>(Spouse: ' + name.trim() + ')');
  29. }
  30. });
  31. }
  32. },
  33. function (msg) {
  34. // error
  35. console.log('API Error Spouse (2): ' + msg);
  36. });

  38. return results;
  39. }
  40. </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.
  1. <script>
  2. /* global ST_API, jQuery, bb$ */
  3. function hook_constituent(constituent) {
  4. var $ = jQuery || bb$;
  5. $('#giftList').remove();
  6. ST_API('gift/v1/gifts?constituent_id=' + constituent.id +
  7. '&gift_type=RecurringGift&gift_type=Pledge&gift_type=Cash',
  8. function (data) {
  9. if (!data.hasOwnProperty('value')) {
  10. console.log('API Error Gifts: ' + JSON.stringify(data));
  11. } else {
  12. var gifts = data.value;
  13. var profile_form = $('#smartportal-profile_form,#mongo-form');
  14. console.log(gifts);

  16. gifts.sort(function(a,b) {
  17. var dta = new Date(a.date);
  18. var dtb = new Date(b.date);
  19. if (dta.getTime() < dtb.getTime()) { return 1; }
  20. if (dta.getTime() > dtb.getTime()) { return -1; }
  21. return 0;
  22. });
    23. if (gifts.length > 0 && profile_form.length > 0) {
  23. // Build table of results
  24. var html = '<div id="giftList"><h2>Recent gifts</h2><table class="resultsList"><tbody>';
  25. html +=
  26. '<tr><th width="20%">Date</th><th width="40%">Type</th><th width="20%">Amount</th><th>Status</th></tr>';
  27. $.each(gifts, function (i, gift) {
  28. var dt = new Date(gift.date);
  29. var amt = gift.amount.value.toFixed(2);
  30. html +=
  31. '<tr>' +
  32. '<td>' + dt.toLocaleDateString() + '</td>' +
  33. '<td>' + gift.type.replace(/([A-Z])/g, " $1").trim() + '</td>' +
  34. '<td>' + amt + '</td>' +
  35. '<td>' + gift.gift_status + '</td>' +
  36. '</tr>';
  37. });
  38. html += '</tbody></table></div>';

  40. profile_form.prepend(html);
  41. }
  42. }
  43. },
  44. function (msg) {
  45. // error
  46. console.log('API Error Gifts: ' + msg);
  47. }
  48. );
  49. }

  51. function hook_new() {
  52. $('#giftList').remove();
  53. }
  54. </script>

    • Related Articles

    • SmartCALLHANDLER OLX FAQs

      A few frequently asked questions about our call handler software for Online Express Trial To trial the product you will need: Online Express - this is free from Blackbaud Raiser's Edge NXT - even if you have NXT but are not fully utilising it ...

    • SmartPORTAL: User login API features

      SmartPORTAL allows users to log in to your website using their Raiser's Edge NXT record. This means they can use the various SmartPORTAL forms such as login, profile updates, add action and the callhandler function. On top of this it also provides a ...

    • SmartZIP: Get your Google Places API key

      You have the choice with our SmartZIP products of using Loqate or Google Places APIs. Google's having a distinct price benefit if you fall within their free $200 per month allowance limit (which most clients will). Get an API KEY You will need an API ...

    • SmartSYNC: Real-time API security and requests

      SmartSYNC provides an API interface to run data flows in real-time and return the results to an external system. Using the API Enabling the API To enable the API you need to go to the Admin > Account page within your SmartSYNC account. Toggle the API ...

    • SmartPORTAL: API and example populating the form using URL parameters

      SmartPORTAL has an API which allows you to hook into events.  This allows you to do a lot of different things as you can alter the form or form fields prior to the display of the form to the end user.  The JavaScript ...