Skip to content

Home

Jump to bottom
Sekers edited this page Mar 7, 2023 · 96 revisions

Introduction

PowerShell Module for the Blackbaud SKY API.

API Endpoints

This module started out with a focus on working with the Blackbaud SKY API Education Management School API but SKY API endpoints for Raiser's Edge NXT, Financial Edge NXT, Church Management, etc. are being added in. It is designed so that additional endpoints can be added in quickly & easily.

Currently Supported SKY API Endpoints

See the sidebar for a list of supported Blackbaud SKY API endpoints. Examples are included in the Sample Usage Scripts folder as well as in the comment-based help for each function/cmdlet (e.g., Get-Help Connect-SKYAPI).

Getting Started

Create Blackbaud Application

Creating a Blackbaud application produces a unique set of credentials that is used during your authorization process. You should create a separate application for each application or script you write that uses the SKYAPI PowerShell module. You can also create an app specifically for use in your personal command-line shell.

  1. Sign up for a Blackbaud developer account at https://developer.blackbaud.com/signup/.
    • We highly recommend that you create a Blackbaud account specifically for Blackbaud SKY API development and not use an account tied to a specific person. Ex. [email protected].
    • SKY API requires at least one admin user to be authenticated with Blackbaud ID to authorize apps for your organization/environment. Your developer account does not need to be an admin, but should also be able to authenticate using Blackbaud ID.
  2. Find and securely document your subscription key by going to https://developer.blackbaud.com/subscriptions/. Just use the primary subscription key unless you plan to implement a key rotation schedule.
  3. Create a new application for your project by going to https://developer.blackbaud.com/apps/.
    • Application name: Name for your application (or script).
    • Application details: Description of the application.
    • Organization name: The name of your organization.
    • Application logo: Optional logo when you or others authenticate the application.
    • Application website URL: Your organization's website or another URL specific to your application.
  4. From the new application, document your application ID (OAuth client_id). This is the unique identifier for the application and connects the application to your environment. The value is not sensitive.
  5. From the new application, document your application secret (OAuth client_secret). This is a sensitive value that is used when requesting an access token to call SKY API endpoints during the authorization process. Just like subscription keys, the application secret should be kept secure and treated like a password.
  6. From the new application, add the following redirect URI: http://localhost:5000/auth/callback

Authorize Blackbaud Application

Blackbaud environment admins must allow users in their organization to use the created application by adding it as an available app.

  1. From the Blackbaud Marketplace, log in with a Blackbaud environment admin account.
  2. Select the Manage menu option and choose to connect an app.
  3. Enter the created application ID to connect it to your organization.
  4. Verify that it is listed on the "Connected apps" page.

School Endpoints

If you use the Blackbaud Education Management platform, you will need to give additional permission for your app to access your Blackbaud School organization's data. If this is an internal script or app, the account used can be the same as your developer account to maintain simplicity. Otherwise, a different account can be used.

  1. Make sure the account used to access your organization data is a user in your Education Management platform and that it authenticates using its Blackbaud ID.
  2. Follow the instructions at https://developer.blackbaud.com/skyapi/apis/school/roles-tasks to give the necessary roles for this user to have access to the School API endpoints and the necessary data (some endpoints require additional role permissions such as Academic Group Manager or Schedule Manager). For example, you may decide to add your account to the following roles:
    • SKY API Data Sync
    • Academic Group Manager
    • Advisory Group Manager

Installing SKYAPI PowerShell Module

There are a number of different ways to install PowerShell modules. Adjust the directions below depending on your organization's needs and policies.

Option 1: Install From PowerShell Gallery

The SKYAPI PowerShell Module is published on Microsoft's central repository for PowerShell content called the PowerShell Gallery. PowerShell comes with the PowerShellGet module, which is used to install packages from the PowerShell Gallery.

If you are running PowerShell 6 or higher, you have a usable version of PowerShellGet.

  • PowerShell 6.0 shipped with version 1.6.0 of PowerShellGet.
  • PowerShell 7.0 shipped with version 2.2.3 of PowerShellGet.

If you are running Windows PowerShell 5.1, you should install a newer version of PowerShellGet. More information from Microsoft is available here. For best results, you should always install the latest supported version.

Run one of the following commands from the PowerShell console of the version of PowerShell you will be using the module under:

<#
    Install the Latest Version in the Default Location
    In PowerShellGet 1.x versions, the default install location is AllUsers ($env:ProgramFiles\PowerShell\Modules), which requires elevation for install.
    In PowerShellGet versions 2.0.0 and above, the default is CurrentUser (PS Desktop: $home\Documents\WindowsPowerShell\Modules or PS Core: $home\Documents\PowerShell\Modules), which does not require elevation for install.
#>
Install-Module -Name SKYAPI

# Specify the Location to Install
Install-Module -Name SKYAPI -Scope AllUsers
Install-Module -Name SKYAPI -Scope CurrentUser

# Specify an Older Version Example
Install-Module -Name SKYAPI -RequiredVersion 0.3.0

# Update an Already Installed Module to the Latest Version
Update-Module -Name SKYAPI

Option 2: Manually Install Module Files

Tip: Run the following command from the version of PowerShell you plan to use to see your specific module install locations:

$env:PSModulePath -split ';'
  1. Clone or download the repo.
  2. Since the file was downloaded from the internet, if necessary, unblock the ZIP file using Windows Explorer (right-click on the ZIP file and select Properties) or the Unblock-File cmdlet.
  3. Copy the SKYAPI folder to the location you desire. Below are some example locations.
    • PowerShell Desktop (5.1)
      • Current User: [Environment]::GetFolderPath("MyDocuments")\WindowsPowerShell\Modules
      • All Users: $Env:ProgramFiles\WindowsPowerShell\Modules
    • PowerShell Core (6+)
      • Current User: [Environment]::GetFolderPath("MyDocuments")\PowerShell\Modules
      • All Users: $Env:ProgramFiles\PowerShell\Modules
      • All Users (Specific Version Example): $Env:ProgramFiles\PowerShell\7\Modules

Configure SKYAPI PowerShell Module

Configuration File

You will need to store a configuration file in a secure location accessible by your application or script. It is a JSON file that looks similar to the following:

{
    "api_subscription_key":  "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "client_id":  "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "client_secret":  "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "redirect_uri":  "http://localhost:5000/auth/callback",
    "authorize_uri":  "https://oauth2.sky.blackbaud.com/authorization",
    "token_uri":  "https://oauth2.sky.blackbaud.com/token"
}
  1. Import the module, if necessary: Import-Module SKYAPI
  2. Run the Set-SKYAPIConfig cmdlet (change your path): Set-SKYAPIConfig -ConfigPath '.\Sample Usage Script\sky_api_config.json'
    • If the file does not already exist, it will automatically be created.
    • You will be prompted to enter or update these values. You can also pass configuration values as parameters when running the cmdlet.
    • An optional -Silent parameter will allow you to silently set or update values without being prompted for manual entry.

Tokens File

You will also need to authenticate your application using an account that has access to your organization's data. If using the School API, see the School Endpoints section for further information. Once authenticated, a tokens file will be stored in the secure location of your choosing, accessible by your application or script. Make sure you run the authentication cmdlet as the principal (user account) that the script or application will run under, otherwise the application will not be able to decrypt the tokens file.

  1. Import the module, if necessary: Import-Module SKYAPI
  2. Run the Set-SKYAPIConfigFilePath cmdlet (change your path): Set-SKYAPIConfigFilePath -Path "$env:USERPROFILE\SKYAPI\sky_api_config.json"
  3. Run the Set-SKYAPITokensFilePath cmdlet (change your path): Set-SKYAPITokensFilePath -Path "$env:USERPROFILE\SKYAPI\skyapi_key.json"
  4. Run the Connect-SKYAPI cmdlet with the 'ForceReauthentication' parameter: Connect-SKYAPI -ForceReauthentication
    • You will be asked to authenticate using the desired Blackbaud account that has access to your organization's data. Your access and refresh tokens will be stored in the file path you peviously specified and updated as necessary. If the file does not already exist, it will automatically be created.
    • This is a one-time step unless the refresh token expires (currently 365 days since the last refresh). As long as your application connects to the SKY API at least once within the window, you can access the SKY API data indefinitely or until you disconnect the application.
    • If you need to clear the browser cache, you can do so with the 'ClearBrowserControlCache' parameter: Connect-SKYAPI -ForceReauthentication -ClearBrowserControlCache

Sample Script

# Sample Blackbaud SKY API Module Usage Script

# Import the Module.
Import-Module SKYAPI

<#
    Set the Necessary File Paths.
    Both These *MUST* Be Set Prior to Running Commands.
#>
Set-SKYAPIConfigFilePath -Path "$PSScriptRoot\sky_api_config.json" # The location where you placed your Blackbaud SKY API configuration file.
Set-SKYAPITokensFilePath -Path "$env:USERPROFILE\SKYAPI\skyapi_key.json" # The location where you want the access and refresh tokens to be stored.

# Connect to the API and authorize if necessary (1st run, etc.).
Connect-SKYAPI

# Now you are ready to run the cmdlets.
Get-SchoolLevel

# Most endpoints also support the 'ReturnRaw' switch parameter to return the original JSON response from the Blackbaud SKY API.
Get-SchoolLevel -ReturnRaw

Other Notes

Security

  • The Config JSON file (e.g., sky_api_config.json): Stored in plain text. This file contains sensitive information, such as your application secret, and should be kept secure and treated like a password.
  • The Tokens JSON file (e.g., skyapi_key.json): Stored as a System.Security.SecureString. This type is like the usual string, but its content is encrypted. It uses reversible encrypting so the password can be decrypted when needed, but only by the principal that encrypted it.

Cmdlet Parameters

The majority of the SKYAPI module's cmdlets adhere to Microsoft's Strongly Encouraged Development Guidelines. However, for parameter names that are passed directly to the SKY API endpoints, rather than using Pascal Case we matched the endpoint's parameter naming (typically lowercase with underscores).

Known SKY API Limitations

The SKY API has some shortcomings. Especially for the School API, there are some known limitations.

  • Get-SchoolSection* API endpoints only return Academic sections. You can retrieve basic information for Activity or Advisory sections using Get-SchoolActivityBySchoolLevel and Get-SchoolAdvisoryBySchoolLevel or, if you need more detailed information, by using the Get-SchoolList cmdlet. Don't forget to give the SKY API role(s) access to the list you are pulling data from if you use Get-SchoolList.
  • Get-SchoolStudentEnrollment only lists the head teacher (no co-teachers) and only their first and last name (no user ID). You will need to pull the information using other Get-SchoolSection* cmdlets.

Troubleshooting

Issue: I am receiving an error message similar to "you do not have access to this route" with an error code of "401".
Resolution: The account you are connecting to the API with does not have the necessary access to retrieve the requested data. For example, when using the School API, you may need to give the Blackbaud account access to the "SKY API Data Sync", "Academic Group Manager", and "Advisory Group Manager" roles. See School Endpoints for more information. You can connect a different account by running Connect-SKYAPI again with the -ForceReauthentication and optionally the ClearBrowserControlCache switches.

Issue: When connecting to the API and the Microsoft Webview is being loaded, you receive an error message similar to "Add-Type : Could not load file or assembly" with an error code of "Exception from HRESULT: 0x80131515".
Resolution: The SKYAPI module was installed manually by being downloaded from the internet. You need to unblock the downloaded ZIP file before copying over the module files to your installation directory. We recommend deleting the module file and following the module installation instructions above.

Need more help or want to discuss the module? Submit an Issue or discuss over at the Blackbaud SKY Developer Forums

SKYAPI Basics

Common Functions/Cmdlets

  • Set-SKYAPIConfigFilePath
  • Set-SKYAPITokensFilePath
  • Get-SKYAPIConfig
  • Set-SKYAPIConfig
  • Connect-SKYAPI
  • Get-SKYAPIContext

Endpoints

Raiser's Edge

School

Clone this wiki locally