Tag Archives: SKY API

Audit Trail Cloud doubles the areas tracked

Not Code, , , ,

Today we released a new version of Audit Trail Cloud and what a release it is!

New Tracked Areas

We have doubled the number of areas tracked. As well as constituent, gift, address, email, phones, online presence, prospect and solicit codes, you can now also track actions, relationships (both individual and organisational), constituent codes and constituent custom fields.

We said that as soon as Blackbaud released new webhooks we would release new areas to track additions, changes and deletions and that is exactly what we have done.

To complement the new areas, we have also added two new tiles. When looking at a specific action page or a specific gift page in the Raiser’s Edge web view, we now include a tile that shows the history of changes for that action or gift respectively. (You only see this if it has been turned on for your login in Tile Security under the Configuration area of the Audit Trail Viewer)

And More Too!…

A while back Blackbaud added the functionality to see who made a change to the record. This was a much sought after addition but it was not available for all records. The changed by id only comes through for constituents, gifts and addresses. This meant that for all the other areas, we were forced to simply write “Not Available”.

As part of this release, if a user has made a change to, say, a constituent and then to an email address, we will infer the changed by user from the constituent change by data. This is not an exact science as, in theory there are several possibilities. It could be that one person is changing the constituent and, unlikely as though it may seem, another goes and changes their email address. Alternatively the same person changes the email address before the constituent record. (Or the change is made so close together that the webhook for the email is fired before the webhook for the constituent even though the constituent is changed first). In this case we will still write “Not Available”

To make it clear, for inferred changes, the changed by user is given in italics and hovering over it will show the tooltip that the value is inferred.

Upgrade (or Purchase) Now!

If you are an existing user, you will be prompted to upgrade the next time you go into the Viewer. Just go into ZeidZone to download the latest configuration version.

If you are not an existing user then what are you waiting for?! Get in touch now

Adding a primary constituent code

Intermediate,

A SKY API task that is common but not obvious is adding a primary constituent code to a constituent record.

I say that it is not obvious because adding a first constituent code automatically makes it the primary. However adding a second does not change the first.

One way of doing it to remove the existing constituent code and add the second one followed by what was the first one. This is a highly unsatisfactory workaround.

The solution lies with the ‘sequence’ field. When creating your constituent code, set this value to 1 and this code becomes the primary.

Here is a sample payload :

{
  "constituent_id": "11278",
  "description": "Volunteer",
  "end": { "d": 13, "m": 11, "y": 2023 },
  "start": { "d": 12, "m": 01, "y": 2022 },
  "sequence": 1
}

This will put this constituent code at the top of the list and it will become the primary.

As an aside, working with constituent codes, it would seem possible to PATCH a constituent code description. After all you supply the id for the code, it seems reasonable then that you could simply change the code description. However, this is not possible. You do not get any kind of error message. Indeed the response is that everything has worked as expected. (but no change of code value)

SKY API and Postman

Beginner, ,

The SKY API documentation is very good compared to many APIs that I work with. One area that is particularly useful is the “Try It” area where you can test an endpoint with your own data. One small annoyance is that if you want to try a number of different endpoints, you need to go through the whole oAuth2 process each time.

Using Postman allows you to avoid this and also take advantage of a number of other features of that application. One nice feature is the ability to generate access tokens with ease so that they do not need to be refreshed each time you run an endpoint. (You will still need to refresh them after the allotted 60 minute life but that should give you plenty of time to run a number of endpoints)

This post shows you how to set up Postman for oAuth2 in the simplest way possible. I am not an expert in Postman and there may well be things that I have missed that could make the process even easier. Let me know in the comments if you do something differently!

Setup your application

It is probably wise to have a separate Blackbaud application for Postman rather than using an application that you use in production.

This is my very basic app. For Postman you do not need a live redirect URI but you do need one as the SKY OAuth2 process requires that the value you send in matches a value on your app.

Setup Postman

In my postman I have a collection of Sky API endpoint calls. You are able to add authorisation details to the main folder and have each endpoint inherit the credentials from that rather than having to enter them each time.

When I click on the Sky API link I can enter my credentials for the whole folder.

Hopefully most of the values are self-explanatory. You should start with the section “Configure New Token”.

Token Name: Just give your token a name so that you recognise it.

Grant Type: Authorization Code

Callback URL: This is one of the values that you have in your SKY app

Auth URL: https://oauth2.sky.blackbaud.com/authorization

Access Token URL: https://oauth2.sky.blackbaud.com/token

Client ID: This is the Application Id from your SKY app

Client Secret: From your SKY app

Scope: This is not currently used by the SKY API

State: You could put a value here but it has no real use in the context of Postman

Client Authentication: Send as Basic Auth Header

Press the “Get New Access Token” button. This will prompt you to log into Blackbaud and go through the OAuth2 process. It will then save a token in the Current Token area. This is then used by your calls.

Setup an individual endpoint call

Now that you have set up authorisation, you can proceed to try a call. You will still need to add your subscription id to the header as shown. (If anybody knows of a way to add that value on the folder level let me know!)

Put the URL in the address box and change the authorisation to inherit from parent as shown below

On the headers tab, add the bb-api-subscription-key

This can be found on your developer account here: https://developer.blackbaud.com/subscriptions/

Then you are ready to press the Send button to retrieve data from SKY API

Creating a Donation Form through SKY API into Raiser’s Edge NXT – Part 3 (Server back end)

Advanced, , , ,

This follows on from the second part of my guide to creating a donation from through SKY API…

The source code for this and the other parts of this series is available on Github.

In this part we are going to actually doing something with the donor details and their credit card.

We are using .NET on our server. You could use any language to do this but I am mostly familiar with working with .NET. I am going to assume here that you are either familiar with .NET or you are able to translate the concepts into your own language.

I created a new project in Visual Studio 2017. I chose an ASP.NET Web Application and selected the WebAPI option without authentication.  I added a new controller to my project – “Web API 2 Controller – Empty” called DonationController.

Continue reading Creating a Donation Form through SKY API into Raiser’s Edge NXT – Part 3 (Server back end) →

Creating a Donation Form through SKY API into Raiser’s Edge NXT – Part 2 (Web front end)

Advanced, , , ,

This follows on from the first part of my guide to creating a donation from through SKY API…

The source code for this and the other parts of this series is available on Github.

Now we are going to focus on the web page that captures the donation.

We are going to show the minimum here. You will want to include data validation to ensure that the incoming data is valid. You will also want some form of security to ensure that you don’t end up sending a lot of spam into your Raiser’s Edge.

On this page we are making use of some simple html, some javascript and the Stripe Checkout API which makes an easy and PCI compliant way of capturing a credit card.

OK, Let’s begin!

Continue reading Creating a Donation Form through SKY API into Raiser’s Edge NXT – Part 2 (Web front end) →

Creating a Donation Form through SKY API into Raiser’s Edge NXT – Part 1 (Overview)

Advanced, , , ,

This post is in response to a thread on the Raiser’s Edge User Group Support Forum on Facebook. If you are not already a member then I can highly recommend it. There are some very talented individuals there who have been using Raiser’s Edge for a long time and have a wealth of experience!

The question asked was whether anybody had created a donation form on a website which would capture information and send it through to RE NXT.

There are a number of different possibilities here. You could create a complex web application that captures donations like ones that are already commercially available e.g. Classy, Crowdrise, OneCause, FunRaise, 4AGoodCause, WeDidIt, MobileCause, FundRazr, etc to name a few to name the ones that Importacular currently integrates with. From an end user perspective these have a lot of functionality that makes donating an easier experience.

Continue reading Creating a Donation Form through SKY API into Raiser’s Edge NXT – Part 1 (Overview) →

Moving over to SKY API

Beginner, Not Code, Opinion, , ,

This blog has mainly consisted of the COM based RE7 API and my musings of all things Blackbaud related. I am sure that the latter will no doubt continue but I have realised for a while now that as time goes on the RE7 API is becoming less and less relevant (although not entirely so) and that there is a natural progression towards the SKY API.

In general there is probably less to be said about SKY API. Firstly Blackbaud have been doing a much better job at documenting it than they ever did with the RE7 API. They are also putting a lot more thought into it so that there are far fewer inconsistencies (so far at least) than there ever were with the RE7 API. Where there are difficult, new, areas they have written up good documentation or blog posts to explain. In short they have made my job here somewhat redundant… Well thanks a lot Blackbaud!

Actually, yes, thank you. I would much rather a clean usable API than one where I have to write up blog posts explaining how to do things. I am sure that there will be moments but there will quite possibly be fewer of them.

One topic that I think deserves some discussion though is the porting of existing functionality from RE7 to SKY. Those of us that have products written for RE7 are keen to see the functionality available on SKY in order that we can port the solutions over.

I have been very keen to transfer Chimpegration but one of the stumbling blocks has been the lack of bulk data processing on SKY. Specifically the ability to return filtered lists of constituents. On many platforms this means simply specifying a last data changed or a keyword search. On RE7 though it is possible to make use of a query to retrieve that information. The user would themselves set up the criteria in the query and the application would allow the user to select that query.

There is some discussion on the SKY API forums about how imperative it is that this be ported over to SKY and that we should be allowed to once again select an existing query.

Despite really needing this functionality for Chimpegration, I am not convinced that this is the best course of action for SKY. This new API should embrace a general approach to this problem. It cannot be based on RE7’s query module. There is definitely a need to generate lists based on complex filters and criteria and that should be exposed somehow to the developer community but to simply port the existing RE7 functionality to SKY would be short-sighted and not take into consideration the other applications what will one day make use of the same API. I want an API that will work with RE, BBCRM, ETap and others. To simply port queries to SKY would confuse the issue and make for an API that is not consistent.