Barkbaud

Blackbaud SKY API / SKY UX sample application.

About
Run Barkbaud on your server

About

This sample application showcases Blackbaud SKY API and Blackbaud SKY UX. Both technologies function completely independent of one another. Blackbaud SKY API supports Authorization Code Flow, which requires us to have a back-end server component where we're able to securely store the client secret. We've implemented the server component using NodeJS. Our front end, a SKY UX SPA, is stored in the skyux-spa-ui folder.

Features

The Barkbaud application starts by requesting authorization to your Blackbaud Raiser's Edge NXT data.
A dashboard provides a listing of dogs that are looking for a good home. Selecting a dog will take you to a page which lists the animal's owner and medical history. Biographies, owner, and medical history for each animal are stored in a MongoDB.
Blackbaud SKY API provides access to the constituent data. The application then uses the API to search for a constituent and retrieve the constituent ID, which is used to pair the constituent record to a dog within MongoDB.
Medical history is stored as a subdocument for each dog in MongoDB. Upon adding medical history, the user has the option of storing the information as a note on the current owner's Raiser's Edge NXT constituent record.

Questions or comments?

Leave feedback or ask a question by filing an issue.

Run Barkbaud on your server

To run this application in your environment, you need a server (such as your local machine) capable of running NodeJS. We're also expecting you to have some familiarity with server-side JavaScript, environment variables, cloning a repository with Git, and using a command line interface (CLI), such as Command Prompt within Windows or Terminal within Mac.

Server requirements

The latest, stable version of NodeJS
The latest, stable version of Git
(Optional) The latest, stable version of Bower

SKY API requirements

A Blackbaud Developer subscription key
- If you have not already done so, complete the Getting started guide. This will walk you through the process of registering for a Blackbaud developer account and requesting a subscription to an API product.
- Once approved, your subscription will contain a primary key and secondary key. When making API calls, you can use either key as the subscription key value for the bb-api-subscription-key request header.
- You can view your subscription keys on your Blackbaud Developer profile.
A Blackbaud Developer application ID and application secret
- Register your application in order to obtain the application ID (client ID) and application secret (client secret).
- When you call the Blackbaud Authorization Service from your application, you pass the redirect_uri as part of the call. The Blackbaud Authorization Service redirects to this URI after the user grants or denies permission. Therefore, you must whitelist the web address(es) or the authorization will fail.
- URIs must exactly match the value your application uses in calls to the Blackbaud Authorization Service. If you plan on running Barkbaud on your local machine, supply a Redirect URI of "http://localhost:5000/auth/callback".
Add the note type, "Barkbaud", to the Constituent API Note Types table.

Steps to install and run the application

1) Clone or fork the Barkbaud repository

$  git clone https://github.com/blackbaud/barkbaud.git
$  cd barkbaud

2) Register for a free MongoDB account

Create a free MongoDB account.
With this account, create a new cluster named "barkbaud" (the "Sandbox" tier is free).
Add your connection IP address to IP Acccess list.
Create a new database user (the username and password is your preference).

3) Prepare your environment

On your server (or local machine), open the barkbaud/ working directory and copy the configuration file barkbaud.env-sample, saving it as barkbaud.env.
Open barkbaud.env in a text editor (such as Notepad or TextEdit).
You should see a list of variables which will serve to configure Barkbaud's NodeJS environment.
Update the file with the following values:

Key	Description
`AUTH_CLIENT_ID`	Your registered application's application ID. (See Managing your apps)
`AUTH_CLIENT_SECRET`	Your registered application's application secret. (See Managing your apps)
`AUTH_REDIRECT_URI`	One of your registered application's redirect URIs. For local development, use `http://localhost:5000/auth/callback`. (See Managing your apps)
`AUTH_SUBSCRIPTION_KEY`	Your Blackbaud Developer subscription key. Use either the primary key or secondary key, visible on your Blackbaud Developer Profile.
`DATABASE_URI`	A MongoDB connection string, which points to your MongoDB database. The string must follow this format: `mongodb+srv://<dbuser>:<dbpassword>@<dbname>?retryWrites=true&w=majority` More details about how to find your connection string can be found on MongoDB's Documentation.

Save the barkbaud.env file.
Review the .gitignore file. The purpose of this file is to specify which directories and files Git should ignore when performing a commit. Note that the barkbaud.env file is ignored. This prevents the file from being synced to your repository and protects your registered application's keys and other sensitive data from being exposed.

4) Install dependencies and run the application

Using Terminal/Command Prompt, change to the working directory (cd barkbaud) and type:

barkbaud $  npm install
barkbaud $  npm run setup

The first command installs all of Barkbaud's dependencies. It may take a few minutes to complete.
The second command builds and configures the database, so it should be executed only once.

Now run the prebuild step:

barkbaud $  npm run prebuild

This command installs all of the UI dependencies for the SKY UX SPA. It may take a few minutes to complete.

Build the UI application by running:

barkbaud $  npm run build

This builds the UI to the barkbaud\skyux-spa-ui\dist\skyux-spa-ui location on disk.
Node.js will reference this build location to use as the UI when running the app. It is not necessary to serve the Angular SPA application separately.

Now that all the dependencies have been installed, the database created, and the UI SPA has been built, we can now run the application with:

barkbaud $  npm start

Open a Web browser to http://localhost:5000.

Notes for deploying

To simplify the demo for local development, this tutorial is written to run the application over HTTP. When deploying to production, the application should be configured to run over HTTPS with the appropriate SSL (Secure Sockets Layer) certificate.

blackbaud/barkbaud