In preparing for the panel session “APIs and the Art of the Possible” for the 2024 ATLIS Conference, I spent some time thinking about my process for developing solutions using APIs. I have recently been working on something to send gift acknowledgment letters via Google based on data in Blackbaud Raiser’s Edge and thought it might make a practical case study. So here it goes:

Overview

1. Meet with key stakeholders to understand what the problem/need is.
2. Identify the Minimum Viable Product (MVP) to use as a starting point from which to iterate. This serves as a proof of concept and provides a feedback loop to develop the solution.
3. Explore the API via documentation/tools to see what it can provide for our needs. Manually run the API calls I plan to verify that they provide the needed data.
4. Deconstruct the problem into pieces and start implementing and iterating.

Meeting with Key Stakeholders

Here are some questions I might ask the key stakeholders:

• Can you demonstrate to me how the current process works?
• What works well for you?
• What frustrates you?

I’ll want to drill down and understand the most common cases where there might be weird exceptions and figure out where (and if) technology can help. I also try to understand the goals they are trying to achieve. Perhaps an entirely different process could do a better job of meeting those goals.

For the gift acknowledgment letters, I met with the member of our team who generates them. She is also our Raiser’s Edge expert and understands the underlying data. Due to some security changes in the hosting environment, the previous method of generating letters didn’t work. The new process was more convoluted and frustrating. It was also more complicated than I thought since different gifts had different acknowledgment letters, which could be in different formats (e-mail vs print).

The Minimum Viable Product (MVP) & Deconstruction

It’s easier to build and test little pieces of a project rather than build everything all at once. For the gift acknowledgments, the MVP was code that grabbed all unacknowledged gifts and placed them into a spreadsheet.

Even this simple project is useful; I can use Google Add-ons like Yet Another Mail Merge or Autocrat to send the acknowledgment letters based off of this spreadsheet.

The MVP allows me to get user and recipient feedback and discover any surprises in the data/process. For example, what should I do with a gift that doesn’t have an acknowledgment letter assigned to it?

After getting feedback, the next step might be to write code to merge the letters into a Google Doc, which could be printed or emailed. After another feedback loop, I might automate the email generation and/or make the solution an add-on for Raiser’s Edge or Google Workspace.

Building incrementally and iterating allows me to learn and adapt before I spend a ton of time doing development work.

Exploring the API & Deconstructing the Problem

Before writing any code, I want to figure out what API calls I need to make, how I use the endpoints, and what results I should expect. I start by going to the API documentation, so for a Blackbaud product, I would start at https://developer.blackbaud.com and browse through to the Raiser’s Edge NXT endpoints. To start, I want a way of finding all unacknowledged gifts so I would look at endpoints involving gifts.

In the documentation, we see an endpoint GET Gift list that returns a paginated list of gifts that match various criteria. The Blackbaud documentation has a handy tool we can test API calls with, by clicking on the green “Try It” button to launch the Sky API console (which requires being activated prior to use).

Experimenting with the various parameters, I learned that it is probably helpful to use “date_added” to list only recent gifts. Between the documentation and some experimentation, I saw that “date_added” needed to be in RFC3339 format.

There is also a parameter for “acknowledgement_status” which I can use to filter for only unacknowledged gifts. Using the SKY API console, I can look at a gift I know isn’t acknowledged and see that the status of “NotAcknowledged” is used.

Now that I know what API call to use unacknowledged gifts I can review the information the API call returns about the gift. Looking at the gift letter templates, I noticed a lot of information I needed isn’t in the results, such as the “Acknowledgement Letter” (used to determine the template) and information about the constituent who gave the gift (like their name). Looking at RE NXT we see this data is associated with the gift:

More experimentation finds that GET Gift returns more detailed information about a single gift, including the gift_letter, which is the “Acknowledgement letter” and that GET Constituent provides information about constituent who gave the gift.

With these three API calls we can get all of the information we need to acknowledge the letter.

Next Steps

With an understanding of the problem, identifying an MVP as a starting point, and knowing the API calls and parameters that get me the data I need, I can start coding.

In reality, I didn’t have the time to develop the MVP, so I reached out to Kevin Harig at Trabant Technology Partners, who I’ve worked with in the past and who has done a lot of API work and had him build it.

It’s also worth noting that Blackbaud has an excellent tutorial on using Power Automate to create gift acknowledgment letters which provides a low-code way of solving the problem in a Microsoft environment.