Anthology Dev docs

DevCon 2022 Presentations!

2022-07-12T00:00:00+00:00

DevCon 2022 Presentations!

We will be adding sessions here as soon as we get the presentations! If you want to see your DevCon presentation, please write us at developers@anthology.com. All times are in ET.

Day 1 @ DevCon 2022

BB Rest Helper

⏲ 1:00 PM - 1:45 PM Session
👨‍💻 Presenter: Javier Gregori

Creating a proof of concept for an integration from scratch can be tedious, there are many basic elements such API authentication or logs that will need to be sorted out before being able to work on meaningful code, and even then, lots of code will need to be written and tested for API Requests. This library abstracts the common and boring operations that Blackboard developers face when interfacing with the REST API so they can focus their effort in creating the cool features they need for their integrations. This library is intended to explore Blackboard REST APIs and to help create POCs for integrations. Please note this tool is not supported by Blackboard and no warranties of any kind are provided. In this presentation you will get to know the Bb_rest_helper library, and how to set up with Visual studio code and Jupyter notebooks to make the REST of your life easier

Description

The Bb Rest Helper includes 5 classes to simpilfy common API operations with Blackboard APIs;

Get_Config. This class is used to get configuration variables (url,key,secret)from an external configuration file in Json format. If you are authenticating for more than one API (i.e. Learn and Collaborate) you will need separate configuration files (i.e. learn_config.json and collab_config.json).
Auth_Helper. This class is used to get the token that then will be used in the API calls. Provides different methods for the different APIs.
Bb_Requests. This class is used to simplify calls to the Blackboard Rest APIs. Provides methods for GET, POST, PUT, PATCH and DELETE requests.
Bb_Utils. A set of convenience functions (Logging, printing…), this will be extended over time.
Ally_Helper This class is used to simplify interaction with Ally as a service, includes methods to authenticate, upload a file, check processing status and retrieve the feedback. As it is an initial release for this API with limited features, it is implemented as a separate class to provide easier access to these methods rather than having to code them manually or with the Bb_rest_helper library.

Companion Links

Presentation PDF

Day 2 @ DevCon 2022

Blackboard Learn REST APIs for Beginners

⏲ 11:40 AM - 12:25 AM Session
👨‍💻 Presenter: Davey Herrera

Presentation PDF

Video companion

Migrating a B2 to LTI & REST Deep dive

⏲ 1:45 PM - 3:00 PM Session
👨‍💻 Presenter: Eric Preston

Moving to Ultra: A Phased Approach

⏲ 4:15 PM - 5:00 PM Session
👩‍💻 Presenter: Michelle Donaldson

Day 3 @ DevCon 2022

Making ultra your own: UEF for Beginners

⏲ 11:30 PM - 12:15 PM Session
👨‍💻 Presenter: Chris Filkins

For years, many of us have relied on Building Blocks as a way to add features and functionality into our Blackboard Learn courses. One of the best tools we ever used was the javascript Hacks tool, which leveraged the renderingHook function to allow a system administrator to further modify and customize their Learn environment with custom tools, banner, footers, etc. Unfortunately, the Ultra experience no longer supports the renderingHook function, removing the key mechanism for these customizations.

In order to restore some of these capabilities, Blackboard Learn implemented a new feature set called the Ultra Extension Framework (UEF). This new framework opens a number of doors for developers to once again customize and extend their Blackboard Learn environments after switching to the Ultra experience. The Ultra Extension Framework consists of two key components – telemetry data for user activity, and injection points to add content at various locations within the Ultra interface.

The telemetry data can include a number of different events, including hover, click, route, as well as portal windows being created and removed. After initially launching as an LTI tool, an UEF tool can subscribe to any number of these events, and typically runs as javascript inside of a hidden iframe within the Ultra interface. From there, the custom script can then submit requests to the Ultra interface to create new panels, banners, notifications, popups, or even a custom help provider.

The attached presentation will provide some sample code snippets from projects that we have deployed in our production environment, including banners and custom help providers.

Best Practices for Building Your LTI Advantage & REST Applications For Learn, From Registration through Release

⏲ 9:00 AM - 9:45 PM Session
👨‍💻 Presenter: Mark Kauffman

In this session Mark will give best practices for integrations that use LTI 1.3 and/or the Blackboard Learn REST APIs. There are many ways to improve your integration’s performance and use, beginning with registration on the developer portal through the day it’s installed on client systems. Given Mark’s extensive experience working with 3rd-party integrations, he’s selected those commonly missed best practices that, when you use them, will position your integration for maximum success.

LTI 1.3 tools must generate their own keys and JWKS URL

2021-07-22T12:46:00+00:00

LTI 1.3 tools must generate their own keys and JWKS URL

When we started supporting LTI 1.3/Advantage (back in May of 2019) we chose to generate public/private key pairs for the tools. The tool vendor was then responsible for copying and storing those values on their side.

But the IMS Global community has moved away from that model and now suggests that tool vendors generate their own key pairs for LTI authentication and provide their public key via a JWKS URL. This model is more secure because there is not copying of a private key and allows the LTI Tool provider to follow best practices with key rotation.

We decided to follow that suggestion. If you want to register a new tool with Learn, you have to provide the JWKS URL information. And if you have an existing tool that use the Anthology-generated private key, please keep in mind that we’ll be terminating support in the near future.

NOTE: Once you’ve made the change, you must have our mutual clients redeploy your LTI 1.3 tool. Redeploy means the following:

Admin -> Integrations, LTI Tool Providers -> Register LTI 1.3/Advantage Tool
Enter the same client ID for your tool that was previously deployed. Click the [Submit] Button.
Your tool will be redeployed to use your new JWKS URL.

Follow the above steps exactly. Do NOT have them delete the integration as that will destroy all existing links to your tool, which can not be recovered.

Here is a video explanation of both the steps you need to take to update your tool’s JWKS URL and the step you will need to have our mutual clients take. Note that after you update your tool’s JWKS URL on the developer portal our mutual clients will NOT able to use your product until after they redeploy as described above and in the video.

FAQ:

Is this just a background change, and it will not impact anything on the front end?
-> There is no impact to how our mutual clients use the LTI Tool or Learn.
Does making the change at the central location serve the purpose, or are we required to plan anything around individual connections for separate schools?
-> You will need to work with the individual schools to ensure that after you make the chage they redploy your tool as described above.
Will schools transition seamlessly once we transition from a static public key to keyset URL (JWKS), or does it require any intervention from the Black side or the school admins?
-> The school admins will need to redeploy your tool as described above.
Currently, both static public key and keyset URL (JWKS) are going through successfully. Is it because Anthology hasn’t yet discontinued supporting the static public key?
-> Anthology will continue supporting the keys that were originally provided until further notice, likely until the end of 2022*.

As always, if you have any questions, check out the contact us page and let us know!

*Statements regarding our product development initiatives, including new products and future product upgrades, updates or enhancements represent our current intentions, but may be modified, delayed or abandoned without prior notice and there is no assurance that such offering, upgrades, updates or functionality will become available unless and until they have been made generally available to our customers.

Use One-Time Session Token to Authenticate with UEF

2021-05-10T16:13:00+00:00

Use One-Time Session Token to Authenticate with UEF

In testing with the Google Canary Chrome Browser, one of our clients discovered an issue that was blocking users from logging in to their Learn instance. After much troubleshooting, we discovered a multi-layer issue that brings us to, you guessed it, cookies.

This affects clients in SaaS with Ultra Base Navigation enabled using Ultra integrations that rely on UEF

Here is a brief description of the contributing factors:

First, the client had built a custom Ultra login page. The page included code designed to ensure that Learn login pages would never render inside of an iframe within Learn. It looks like this:

if ( top != self )
{
    top.location.replace( self.location.href );
}

In and of itself there’s nothing wrong with it. We, at Anthology, have removed it from the default Ultra login page, but many clients use it in Original login pages, and so it’s moved with them into Ultra.

If you are unsure whether you have a custom login page, visit help.blackboard.com for more information.

Secondly, when a user logged in, Ultra Extensions automatically fired off an LTI launch to UEF-enabled tools. The way UEF works is: after the LTI launch is validated, the tool redirects to the Learn REST endpoint to initiate a UserAuth flow. In our documentation, we call this a Three-Legged OAuth or 3LO. In most cases, it’s a process that relies on a session cookie to hold everything together. This impending release of Chrome (and other browsers) will block this cookie because everything is happening across domains and involves the use of iframes.

So what happens is that, even though the integration is configured in Learn to not force the end-user to authorize the integration, the lack of the session cookie means that Learn has no idea that this user is logged in, so it pops open the login page.

Remember that code snippet above in the custom login page? Well, that takes over the entire browser page with the Learn login. And when the user logs in again, it renders the JavaScript meant for the UEF iframe into the page. In other words, it overtakes your Learn browser session. There is no way to actually get past that screen.

Related, this same issue affects Safari users when cross-site tracking is disabled.

So what can you do?

Well, that depends upon who is reading this blog. If you are an administrator trying to get your users back in Learn, the most immediate fix is to remove that snippet from your login page. It won’t fix your broken UEF integration, but it will at least let your users log in and interact with Learn.

If you are a developer that has built a UEF integration, we actually implemented a fix for this in April: a way to bypass the need for a session cookie in this process. In the LTI launch, we now provide what is called a one-time session cookie. This is present in both LTI 1.1 and 1.3 launches.

If you are using LTI 1.3, there’s a small bug in this. I will share a workaround that will both get around this bug, but not fail when the bug is fixed.

This one-time session cookie is added to the claims in the LTI 1.3 JWT and the form POST parameters in LTI 1.1. You can grab that value from the LTI launch, return it as a parameter in your 3LO authorization code request, and your problem will be solved.

LTI 1.3

In LTI 1.3, you will see the value in the https://blackboard.com/lti/claim/one_time_session_token claim. This token is made up of a specially generated token value. It should also be followed by a comma and the user’s UUID. The bug is that the comma is missing. Luckily, the user’s UUID is the sub token in the same set of LTI claims. We intend to fix this, but to ensure your code works both now and after the fix, you can simply look for the comma. If it’s not there, append it and the sub and you will be off and running. Here’s a Python 3 code snippet to illustrate how this might look. We will be updating our UEF sample code, but at the time of this writing, we have not done so.

    # Get the value of the one time session token from the LTI claim
    one_time_session_token  = message_launch_data['https://blackboard.com/lti/claim/one_time_session_token']

    # If there is no comma in the value, we've hit the bug. Add it and the user's UUID
    if "," not in one_time_session_token:
        one_time_session_token += "," + message_launch_data['sub']

    # Add the one_time_session_token to the query parameters to send to the Authorization Code endpoint
    params = {
        'redirect_uri' : Config.config['app_url'] + '/authcode/',
        'response_type' : 'code',
        'client_id' : Config.config['learn_rest_key'],
        'one_time_session_token' : one_time_session_token,
        'scope' : '*',
        'state' : str(uuid.uuid4())
    }

    # Encode the parameters
    encoded_params = urllib.parse.urlencode(params)

    # Redirect the successful LTI validation to the Authorization Code endpoint
    return(redirect(learn_url + '/learn/api/public/v1/oauth2/authorizationCode?' + encoded_params))

LTI 1.1

By now, I hope you are using LTI 1.3, but I know many are not. As a result, we also added a one-time session token to LTI 1.1 launches. This will come in the form POST parameter ext_one_time_session_token. Just like in the 1.3 example, your application should take this value from the LTI launch, append it to the authorization code request endpoint as one_time_session_token=that_token and redirect them to the authorization code endpoint.

Summary

We have validated this fix with one of the partners that was affected. If you are a developer, please fix the issue immediately! If you are an administrator of a Learn SaaS instance using Ultra, and you have UEF integrations, make sure you do not have that JavaScript snippet on your login page. And if you do, please remove it. Then let your UEF integration partners and developers know that this fix must be made as soon as possible.

Regardless of whether you are an administrator or a developer, please feel free to reach out to us at developers@anthology.com with any questions.

Happy coding!

How to Create a User With Limited Entitlements For REST API Calls

2021-01-06T12:59:00+00:00

How to Create a User With Limited Entitlements For REST API Calls

First, as our documentation states, a Learn admin should never be told to associate a user with Learn admin privileges with any REST API integration, see this document. Hence we often get questions from folks on how to create a user to associate with a REST API integration that has limited capability on a Learn system. One way is to research and design your REST application to use OAuth 2 3-legged Authentication. See the documents referenced below. 3LO guarentees that the user using your REST Application can only do what they can do via the Learn UX when they are logged into Learn.

However, if your application is using our OAuth 2 2-legged Authentication read on. Or I should say, watch on. I created the following to answer the question “Is it possible to create a user that has only the necessary permissions and avoid using “Learn System Admin” user?”

The answer is yes! Here’s a video explaining exactly how to proceed.

Reference Documentation:

Caliper Documentation Updated for 1.1

2021-01-05T12:59:00+00:00

Caliper Documentation Updated for 1.1

We have spent some time over the holiday break updating and organizing our documentation better. One of the longest outstanding changes was to update the Caliper event samples from 1.0 to 1.1.

I am pleased to announce that we have finally completed this project. The event guide is largely unchanged, but the individual events have all been updated to show current sample payloads from each event, allowing you to better anticipate the messages you will receive and better plan your storage and reporting requirements.

Over the next few weeks, we will be highlighting some of the other key updates that we hope will help ease the onboarding process for new developers and make finding exactly what you need when you need it for everyone.

Happy Coding!

SOAP EOL Explained

2020-12-16T12:00:00+00:00

SOAP EOL Explained

Back in the day, January 4, 2019 to be exact, Blackboard announced deprecation of our SOAP Web Services with this article Blackboard SOAP Web Services Deprecation

Now, almost two years later in our Learn SaaS Relase Notes we’ve written “As of December 31, 2020, Learn SOAP Web Services are no longer supported, as they have reached the end of life per our deprecation policy.” What does this mean for you as a develoepr?

The most common concern is “Will my SOAP code continue to work in an earlier version of Learn?” or some variation. Here’s a recent example: “Will this be for all versions, or will SOAP API still be available on version 3800?”

The answer is that client’s self and manged-hosted systems that are on older versions of Learn will not be impacted. If your client is runnign 3800.0.3 and upgrades to the most recent Cumulative Update, the SOAP Webservices should continue to work for them.

For self and managed-hosted clients that are on 3900.0.0 and are now upgrading using the same build numbers as in SaaS, SOAP will not be supported in any release post Dec 31, 2020.

Another common quesiton is from those using the Learn LIS 2.0 SIS integration, which is SOAP based. No, we are keeping the LIS 2.0 SIS integration in the product at this time. It will not be affected.

If you have additional questions, drop a line to developers@anthology.com and we’ll update this blog post with the answer.

Happy 2021!

Cookies and Browsers

2020-10-15T12:00:00+00:00

Cookies and Browsers

Most people like cookies. Internet browsers used to like cookies, but a lot has changed in the last few years.

We are seeing a lot of applications stop working in some browsers because cookies are not being shared, and this post hopes to help explain why that is happening and what can be done about it.

A web application may set a cookie to track a user’s session. This is very common, however if your web application is going to be hosted in an iframe, then there’s a good chance your cookie won’t be sent back to you. This is because browsers are clamping down on sending “3rd-party” cookies back to applications hosted in an iframe. Note that a 3rd party is a site that is hosted on a domain different than the 1st party, or your web application. The reason is because these cookies can be used for tracking your internet and browsing activity. Safari has disallowed this for years as a user privacy measure.

Another case where cookies aren’t being sent back is during a form POST back to your application. If you set a cookie, then launch to a 3rd party application, if that application does a form POST back to you, the browser will likely not send your cookie back because it is trying to help prevent cross-site request forgery attacks.

Rather than detail all the scenarios and work arounds here I link to two web pages that are immensely helpful in explaining the situation and some possible workarounds.

The TL;DR is if you must set a cookie in your web application, be careful how you configure that cookie’s properties, and understand that at least in Safari, your cookies may not get passed back to you. The other browser makers are going to get as restrictive as Safari soon.

Student Id Template Variable

2020-10-07T08:40:00+00:00

New! Student Id Template Variable

New in SaaS and the forthcoming 3900 release* an @X@user.student_id@X@ template variable!.

Statements regarding our product development initiatives, including new products and future product upgrades, updates or enhancements represent our current intentions, but may be modified, delayed or abandoned without prior notice and there is no assurance that such offering, upgrades, updates or functionality will become available unless and until they have been made generally available to our customers.

-markk

Oct 2020 - Changes that will impact Learn B2 Integrations

2020-10-04T08:40:00+00:00

Changes that will impact B2 Integrations

Read this article . Download Oct 2020 - Changes that will impact Learn Integrations.docx to find out how to get early access for testing.

-Mark Kauffman

Ally as a Service and UEF Documentation now available

2020-09-03T12:40:00+00:00

Ally as a Service and UEF Documentation now available

Today we launched two new sections of developer documentation - Ally as a Service (AaaS) and the Learn Ultra Extension Framework (UEF). These new APIs give you access to integration points and functionality that allows you to bring the power of Blackboard into your applications, and ultimately, your user’s experience.

Ally as a Service is a standalone, separately licensed API to apply specific components of Ally’s approach to content within your application. In its initial form, you are able to upload files, process them through Ally’s accessibility checklist, and retrieve data that tells you what can be improved. This is only the tip of the iceberg, so make sure you continue to monitor this amazing capability for enhancements moving forward. For more information, including a conversation about pricing, reach out to your Account Executive.

The Ultra Extension Framework Premium APIs allow an integration to subscribe to events happening real-time in the Ultra UI, and respond to those events by interacting directly with the UI to do things like open panels, display modals, show messages and notifications, and augment the help system in Learn. Partners will need to be at a bronze level or higher to access these Premium APIs. See the partnership team for more information. If you are not a partner, check out how to become a partner. Licensed clients need only request access. Access is granted to your group in the developer portal, much like rate limits. Just open a case on Behind the Blackboard to get started!

As always, let us know if you have any questions!

Happy Coding!