Subscribe to this blog to receive periodic product release announcements for developers and tips and tricks for using API.

Developer Blog Series: Synchronize Data To A Custom Data Source With SKY API

Synchronizing data across multiple data sources is often an integral part of any strategy that uses multiple third-party providers. If you have a Workato subscription, then our Raiser’s Edge NXT recipe that uses the easy-to-use Workato UI might suit your needs.

However, if you don’t have a subscription to Workato or have a complex synchronization scenario, then you may need to create your own data synchronization process. The initial step of any SKY API integration is to create an application that can get a JSON Web Token (JWT) to authenticate in SKY API. The next step is to use your JWT and Subscription Key to make calls to the SKY API to retrieve changed entities.

A full sample is available here. This sample uses the NuGet packages RestSharp and Newtonsoft.Json.

To synchronize entities from Raiser’s Edge NXT, you need to make calls to the GET list endpoints with the last_modified parameter set to a value that indicates how far back to get changes. For example, a GET to https://api.sky.blackbaud.com/constituent/v1/constituents?last_modified=2017-04-03T08%3A30%3A00.0000-4%3A00%u200B gets all constituents added or modified since 8:30am (EDT) on April 3, 2017.

Within the resulting collection entity, the results are returned as an array within the value property. The collection entity also includes a count property and a next_link property. To fetch additional changes, make a new GET request to the URL in the next_link property. When the results return an empty values array, no new changes are available. At this point, you can store the next_link property and wait to retrieve more results when more changes are reflected in the API. Reuse the supplied next_link and sort_token to ensure that no records are missed in future requests.


Best Practices and Additional Notes

A common question that we are asked is “How long should you wait between calls?” In short, it depends on your use case and what stage you’re at with your data synchronization.

If values are returned and the number of returned entries matches your requested page size, then more pending values are likely to be returned and an additional call using the next_link is required. While paging through responses in this way, wait a short time (1 second for example) to prevent hitting API rate limits.

If no values are returned, then your application should wait for entities to be added or updated before attempting to synchronize with the API. Depending on the needs of your application, an average wait time of about 30 minutes, an hour, or even a day is appropriate for the subsequent update request. A wait time less than the 30 minute average will not produce new results due to internal sync times in Raiser’s Edge NXT for many of the available list endpoints. In addition, shorter wait times between update requests lead to fewer results on each update and higher chances of reaching your API request quota.

Additional notes:
  • For data synchronization, the last_modified parameter is required. To initialize your data from scratch, set last_modified to 0001-01-01. If you do not set the last_modified property, the next_link does not contain a sort_token parameter. In some circumstances, this could omit entries from the results.
  • List endpoints do not return results for deleted entities or indicate that records were deleted. Therefore, we suggest using PATCH inactive=true when synchronizing with an external system instead of DELETE whenever possible.
 
Posted by Jason Tremper on Apr 5, 2017 10:07 AM America/New_York

Leave a Comment

Log in to post a comment.

Why was my comment deleted on this blog? I just mentioned that together with Blackbaud we are working on an easy to use integration system between Blackbaud products and other systems. Currently supported : Nxt, Dynamics, CSV and SQL server.
  • Posted Wed 12 Apr 2017 04:43 AM EDT