Some sample code to use the SKY API in Visual Basic

Brian Gray

I write all of the programs that access the SKY API in Visual Basic. I use the SKYLib•Net library from Protege Solutions. It handles a lot of the ugly details so that I can focus on the data. You can download the library and an example program at the Protege website. https://protege.com.au/skylib

The download is free and will work with your Blackbaud database. You pay for the library only if you find it useful to you. It runs in a rate-limited mode until you buy a license. (This is not a sponsored post. I'm just a satisfied user of that software.)

The code sample below will give you an idea of what accessing the SIS data using the SKYLib library looks like.

Make the connection to the SIS database:

Private Sub ConnectToBbSKY(Optional ByVal UseBasicAuth As Boolean = True)   
Try

       ' Initialize the API and fill the call selector according to the selected Blackbaud product.


       Api.SubscriptionKeyPri = SsesLibrary.SsesLibrary.GetPasswordFor("SKYLib", "Primary")

       Api.SubscriptionKeySec = SsesLibrary.SsesLibrary.GetPasswordFor("SKYLib", "Secondary")

       Api.RedirectUri = SsesLibrary.SsesLibrary.GetPasswordFor("SKYLib", "Redirect")

       Api.ClientId = SsesLibrary.SsesLibrary.GetPasswordFor("SKYLib", "AppID")

       If UseBasicAuth Then

           Api.BasicAuthCredential = SsesLibrary.SsesLibrary.GetPasswordFor("SKYLib", "BASICAuth")

       Else

           Api.ClientSecret = SsesLibrary.SsesLibrary.GetPasswordFor("SKYLib", "AppSecret")

       End If


       Dim SKYLIB_KEY As String = SsesLibrary.SsesLibrary.GetPasswordFor("SKYLib", "Key")


       ' Manual user authorization can be disabled for unattended applications such as Windows Services. 

       Api.DisableUserAuth = False


       Dim connected As Boolean = AppLicense.Init(LicenseKey:=SKYLIB_KEY)

       If Not connected Then

           MyLogger.Log(AppLicense.ErrMsg)


           If UseBasicAuth Then

               ' we tried with the Basic Auth key and failed.  Try the App Credential

               MyLogger.LogError("BasicAuth failed.  Using Client/Application Secret.")

               Api.ClientSecret = SsesLibrary.SsesLibrary.GetPasswordFor("SKYLib", "AppSecret")

               Api.BasicAuthCredential = ""

               connected = AppLicense.Init(LicenseKey:=SKYLIB_KEY)

           End If


           If Not connected Then

               MyLogger.LogError("Client/Application Secret failed. (1)")

               Return

           End If

       End If


       ' The license expiry date, type and state are available for reference.

       If AppLicense.Valid Then

           MyLogger.Log(AppLicense.State)

           MyLogger.Log("The SKYLib.NET license type is: '" + AppLicense.Type + "'.")

           MyLogger.Log("Registration code: " + SKYLib.AppLicense.RegistrationCode)


           Api.MaxRetries = 4

           Api.RetryInterval = {15, 60, 300} ' 1st: 10 sec, 2nd: 1 min, 3rd: 5 min, 4th: 5 min (last value is used for subsequent intervals)

           Api.ThrowErrorOn.CallQuotaExceeded = True

           Api.ThrowErrorOn.ServerOutage = False

       Else

           MyLogger.LogError("SKYLib.NET is running in rate-limited mode. Need a valid license")

       End If


       If (Api.CheckVersion() AndAlso Api.LatestVersion > Api.CurrentVersion) Then

           MyLogger.LogWarning("A new version of the SKYLib.NET library is available. The new version is " +

               Api.LatestVersion.ToString() + ".")

       End If


       If Api.School.TestConnection() Then

           MyLogger.Log("Connection to BBSky (School API) succeeded")

       Else

           MyLogger.LogError("Connection to the School API failed")

       End If


   Catch x As Exception

       MyLogger.LogError(x.Message)

   Finally


   End Try
End Sub

(Most of the code above for connecting to the database came from the sample program that comes with the SKYLib library download.)

Read user data via the UserExtendedGet endpoint:

Private Sub GetStudentInfo(roleIDList As String)


    Dim moreToDo As Boolean

    Dim nextRec As Integer = 1

    Dim dStartTime As Date = DateTime.Now


    Try

        Do

            Dim usersList As School.Model.UserExtendedCollection =

                Api.School.V1UsersExtendedGet(roleIDList, marker:=nextRec)


            For Each user As School.Model.UserExtended In usersList.Value

                If Not user.Deceased Then

                    StudentsCoreByUserID.Add(user.Id.ToString, user)

                    If String.IsNullOrEmpty(user.NickName) Then

                        MyLogger.LogWarning("No nickname in Core for " + user.FirstName + " " +

                                            user.LastName + " - " + user.Id.ToString)

                    End If

                End If

            Next


            nextRec = ParseNextLink(usersList.NextLink)

            moreToDo = nextRec > 0


        Loop While moreToDo

    Catch ex As Exception

        MyLogger.LogError(ex.ToString)

    End Try


    MyLogger.Log("GetCoreData(): Read Core data for " + StudentsCoreByUserID.Count.ToString() + " students")



    Return

End Sub

Read an Advanced List via the ListSingle endpoint. This is a generic function that will read any list and return the data to me.

Private Function GetListData(listID As Integer, label As String) As List(Of Dictionary(Of String, School.Model.Field))


    Dim result As New List(Of Dictionary(Of String, School.Model.Field))

    MyLogger.Log(String.Format("GetListData({0}): {1}", listID, label))


    Dim page As Integer = 1

    Dim done As Boolean = False

    Try

        While Not done

            Dim list As School.Model.ListResult = Api.School.V1ListsAdvancedByListIdGet(listID, page)

            Dim rows As List(Of School.Model.Row) = list.Results.Rows


            For Each row As School.Model.Row In rows

                Dim fieldData As Dictionary(Of String, School.Model.Field) = GetFieldData(row)

                result.Add(fieldData)

            Next


            done = (rows.Count = 0)

            page += 1

        End While

        MyLogger.Log("Record count = " + result.Count.ToString)

        Return result


    Catch ex As Exception

        MyLogger.LogError("GetListData(): " + ex.ToString)

        Return Nothing

    End Try


End Function



Private Function GetFieldData(aRow As School.Model.Row) As Dictionary(Of String, School.Model.Field)


    Dim fieldData As Dictionary(Of String, School.Model.Field)

    fieldData = aRow.Columns.ToDictionary(Function(c) c.Name)


    Return fieldData

End Function

An example of how I use my GetListData function (above) to process the data

   Private Sub GetFakeAndAlt()

 
   FakeAndAlt = New HashSet(Of String)

   Dim CoreID As Integer

   Dim Status As String = ""


   Try

       ' Advanced List - (API Acccess) API - Special Student Enrollment

       Dim listData As List(Of Dictionary(Of String, School.Model.Field)) = GetListData(117174, "API - Special Student Enrollment")


       listData.ForEach(

       Sub(row)

           CoreID = row("UserID").Value()

           If Not IgnorableUserIDs.Contains(CoreID) Then

               Status = row("Enrollment").Value()


               If Status IsNot Nothing Then

                   Status = Status.ToLower.Trim

                   If Status.Equals("fake student") Or

                       Status.Equals("alternate study") Or

                       Status.Equals("medical leave") Or

                       Status.Equals("academic incomplete") Then


                       FakeAndAlt.Add(CoreID.ToString)

                   End If

               End If

           End If


       End Sub)


   Catch ex As Exception

       MyLogger.LogError("GetFakeAndAlt(): " + NL + ex.ToString)


   End Try
End Sub