Skip navigation
All Places > Blackboard Developer Community > Blackboard Learn Developers > Blog > Authors mkauffman
1 2 3 Previous Next

Blackboard Learn Developers

36 Posts authored by: mkauffman

I'm writing this as we've had a few questions from developers come in who have never written a Web Application in their life. I hope this helps.

 

First, get up to speed on developing web applications. A Google search for 'web application in <your favorite language>' is a good start. Here's an example result that I found Quickstart: use Visual Studio to create a Python web app - Visual Studio | Microsoft Docs - Side comment - Visual Studio Code is one of the nicest tools I've seen come out of Microsoft.

 

Next, when you start coding your Web Application to integrate with Blackboard Learn, we recommend use of our REST APIs plus LTI. Use LTI as the starting point for the user of the Learn instance. Why? You get information about the user and any course context from the LTI launch parameters. Then, if necessary the LTI Tool Provider that you write can make additional REST API calls back into the Blackboard Learn instance that made the launch. You can also, for some cases just write a REST application that a user connects to Learn via Three-Legged OAuth and then makes REST calls on behalf of that user. Note that everything, your server/Tool Provider & Learn running in production will/should be using HTTPS via the standard port 443. See the following list of resources for getting started.

 

Here are several resources for developing REST Applications for Blackboard Learn:

We offer weekly technical office hours everyone is welcome to attend, free of charge: https://community.blackboard.com/groups/technical-office-hours (Link to join is on the upper right of the page.) LTI is an industry standard. Below are links to several resources:

 

I hope this helps you get started! Below is a high-level architecture diagram as an example. It's not meant to be all-inclusive, but does show one type of relationship between the User, the Blackboard Learn System, and your Application.

Blackboard-AppIntegrationArchitecture.jpg

mkauffman

Space Matters

Posted by mkauffman Mar 20, 2019

If you're having problems getting Let's Encrypt to work with your AMI, space matters.

 

Only this works - notice the space on either side of the :

ssldomain : <FQDN>

sslemail : <email address>

 

Not -

ssldomain: <FQDN>

sslemail: <email address>

 

Not -

ssldomain:<FQDN>

sslemail:<email address>

 

Reference https://community.blackboard.com/docs/DOC-4242-using-the-blackboard-learn-ami-for-rest-and-lti-development#jive_content_…

I just had a couple of great questions come in. After discussing with product management, here are the answers as of the date of this blog post. (Can you guess?)

 

Question: I want to move courses from one Bb instance to another, programmatically.  Assuming I have course exports from the source instance, is there an API to create courses in the target instance?

Answer: No

 

Question: Is there an API call to export an IMS Common Cartridge from a course.

Answer: No

 

More detail: Exporting and importing Common Cartridge data via REST APIs are not currently on the 2019 roadmap.

 

If you have a need for the above, head on over to https://community.blackboard.com/community/developers/learn/rest/pages/rest-api-ideas and rally your fellow developers around these. We may say "no", but not "never"*.

 

*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.

 

See I'm sorry, Dave, I'm afraid I can't do that. for the answer to the question about displaying B2 content in an Ultra course. You can probably guess by the title, no is the answer.

 

I'm writing this post because we've had an additional question surface as Blackboard Partners have started providing  LTI integrations in addition to their B2s. The question being, "When I convert my Original course to an Ultra course, will my B2 links automatically be converted to the LTI link for the Partner content?" The answer is "No*."

 

*Except for a few Partner Cloud partners who are working with our team on a "migration tool" for their content. More details to come later in 2019.

View the WS logs via a Kibana query of:  path="/usr/local/blackboard/logs/ws/WS_common.log"

When you create a Learn REST integration you see these options - End User Access - Authorized To Act As User. What is the difference? If you've been working with REST in Learn for some time, you know that End User Access has been available since we enabled Three-Legged OAuth  (3LO) Checking End User Access allows the user associated with your REST application to act as the user who logs into your application using the Three-Legged OAuth process.

 

The new kid on the block, Authorized To Act As User, allows you, the Learn Admin to set the system to bypass the "Blackboard User Authorizes, User Authorizes" steps shown on the Three-Legged OAuth diagram. Why would you do that? There are cases, say if you're a copier company and your copier determines whether the user valid and authorized, the the REST Application running on the copier may need to bypass these steps, because the way some copier's "browsers" are built they can't follow the redirect.

 

And finally, for completeness, to answer the Partner who reached out about these final questions:

Also, once I specify a 'Learn user' in the REST API integration, are all REST calls performed as that user? 

When using OAuth2 (Basic), yes.

 

Is there anyway to choose at runtime which learn user to perform the REST calls as?

You can't do that. You can only use 3LO to have the user log in, then all REST calls are made as if they were made by that user.

 

Reference http://oauthbible.com/ . What we've called "Basic" is two-legged.

 


Had a case come in with several questions about the LTI Placement Options. There's certainly many options so I've written this Blog Post in Q& A format for future reference. The definitive documentation is on https://help.blackboard.com Cheers!

 

When creating a LTI TP, what does 'Allow Membership Service Access' mean?

- It allows one to enable names and roles for the integration. Q2 2018 (3400.0.0) included the LTI Names and Roles Provisioning service.

Reference: https://blackboard.secure.force.com/btbb_articleview?id=kA4390000008SoQ

See https://www.imsglobal.org/specs/ltimemv1p0 for the specification.

 

It appears that once an LTI TP & associated placement is created, and the placement 'Availability' is set to 'Yes', course builders and instructors can access the LTP TP placement _in any course_. Is there a way to make the LTI TP / Placements only show up [for instructors] for a specific course?

- No there is not.

 

What is the purpose of the LTI TP > Placement > Handle? Does it affect how the LTI 1.0 link is stored in Bb?

- It's a unique handle that you define for your placement. If there's a collision you'll be informed when submitting the form. The handle was useful for Java B2 developers and may be useful with our REST API implementation for managing LTI placements.

 

What's the difference between a Course Content Tool (no deep linking), and a Course Tool?

- A Course Content Tool can only be placed on a Course Content page. The tool can be used by a student to access TP content. A Course Tool is really meant for the instructor only. However, one can make it available to students, resulting in some very awkward behaviors. If you make a placement a Course Tool, and make it available to both instructors and students, then it will only be available to include as a Tool Link, and will not appear in the Course Tools section of a course. However, if the placement is available only to instructors, then it will appear in the Course Tools drop down. If you want the placement to appear both as in the 'Course Tools' drop-down list and as a Tool Link choice then only make it available to instructors.

 

How do you make the LTI TP 'Course Tool' placement display in the left-hand nav menu under 'Course Tools'?

- Use the near the upper right of the left-hand nav, select Tool Link, the Type drop-down will have the Course Tool placement you created.

 

Where does the LTI TP 'System Tool' placement get displayed?

- See https://help.blackboard.com/Learn/Administrator/SaaS/Integrations/Learning_Tools_Interoperability
A System tool can be opened without accessing a course. In the Original experience, the tool appears in the Tools menu of the My Institution tab. In the Ultra experience, the tool appears in the Tools base navigation section.

You can also place a System Tool in an Institution Page module.

 

Where does the LTI TP 'Administrator Tool' placement get displayed?

- On the System Admin page, in the Tools and Utilities section.

mkauffman

AMI? HTTPS - Use HTTPS!

Posted by mkauffman Jan 24, 2019

This one is short. If you can't access your AMI, you might check that you're using https:// in your browser address field. We've had reports of being unable to access, http:// won't work.

 

Example: http://bykerk-kauffman.com/

bykerk-kauffman.com refused to connect.

Try:

ERR_CONNECTION_REFUSED

Now try: https://bykerk-kauffman.comhttp://bykerk-kauffman.com/

Ta Da!

 

We've had several issues pop up we our support team tries to install a 'new' B2s from 3rd-party vendors onto a SaaS system and they can't upload the B2 into our SaaS B2 library. They can't because the vendor has given the B2 the same vendor ID, handle, and version in the B2 manifest included in the .war file that has already been assigned to a different B2 that has already been loaded onto some other client's SaaS system.

 

Background: There is a Blackboard B2 Library for SaaS. All B2s are stored there prior to deploying the B2 to SaaS systems. I.E. if I want my B2 with a vendor ID of Kauffman, and a handle (program name) of video-server and a version of 4.0.3 to be deployed to a client’s SaaS system, it first goes into Blackboard’s B2 Library for SaaS.

 

This single B2 library for SaaS will only allow one version of a vendor’s B2. I.E. If Vendor: kauffman, Handle: video-server, version: 4.0.3 is already in the B2 library, then kauffman-videoserver version 4.0.3 can NOT be assigned to a different build of the B2 for a different client and uploaded into the library.

 

This means that there can be only ONE version of a given B2 in the library for deployment to SaaS environments. A vendor can NOT develop a client-specific B2 and give the B2 the same vendor ID, handle and version that another client has already installed in SaaS. Each B2 given to Blackboard or a Blackboard SaaS Client MUST have a unique vendor ID, handle, and version value. The best practice for a vendor’s client-unique B2s in SaaS is to make the B2 configurable by the client to set some value that indicates which client it's deployed to, or even better, write the B2 code so it figures out who owns the system it's deployed on. To differentiate, one could also give client-unique versions of a B2 a different version or different program-id, or a different handle though that’s not best practice because it massively increases the number of the ‘same’ B2 in the library and makes it difficult to differentiate which B2 is meant for which SaaS system.

Once in a while a question comes in about where to find information on Behind the Blackboard. For example a case just came in asking if Q4 2018 is out and if so, where to find the download. If you're having difficulty finding information on like this, this brief video shows you how to find answers.

 

Happy New Year!

mkauffman

Adios PK1 Persistent IDs

Posted by mkauffman Dec 5, 2018

In previous Learn APIs (Java and SOAP) the database Primary Key served as a means of identifying Learn Objects. These Primary Keys, or PK1s, are used internally to the Learn system, but are no longer viable as unique identifiers for the objects bound to that database specific identifier.

 

As we continue rolling out our REST APIs we're working to improve API reliability and the longevity of applications build using them. Part of that decision is a move away from facilitating API use of PK1s as a means of accessing objects via the database primary key, i.e. the PK1, often referenced as the object's id in our APIs and REST results.

 

There are many compelling reasons for this decision, including creating a loose coupling between the Learn internal database and external code, thereby avoiding issues that inevitably arise when a system is migrated. Migrating a systems database generates new Primary Keys for the object data migrated, and thus created in the new database - this is a characteristic of databases. We may continue to include PK1s in REST results for Courses and Users for use in requests as a convenience*, but these PK1s should never be used as permanent external identifiers of Learn objects.

 

One example of this change as several have pointed out, is the difference between the soon-to-be deprecated SOAP and our REST membership endpoints. With SOAP calls to the CourseMembership endpoint returned a CourseMembershipVO that contained a field 'id' which is the PK1/ID. That data point is not available from the REST membership endpoints. This is because we have eliminated the id/PK1 field from the response returned by the REST GET/learn/api/public/v1/courses/{courseId}/users endpoints to meet the above stated goals toward reliability and longevity.

 

What do you use instead of the PK1?

What may have seemed like a good, solid identifier really is not. The way forward is to start using the different objects' UUIDs as returned in REST requests.

 

You need to replace any use of PK1 or ID as the unique identifier, whether using SOAP or Java APIs. When migrating your application to using REST APIs you may use a lazy identifier migration. In this model you may add the UUID field to your database and populate as you access those objects at runtime. If your code finds your UUID fields empty when making a Learn access, you use the courseID and userName you have to look up the UUID for the course membership, the UUID for the course, and the UUID for the user and populate those fields. Doing it this way eliminates the need for one mass migration, you get the new data as you go. If you see other creative means forward, please share here.

 

In summary, now is the time to start moving away from using API functionality that uses a PK1 or Database dependent object IDs and move to using the object’s UUID.

 

  *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.


Here's a handy URL to have when for some reason the credentials you have for the front-end login to your Learn system don't work. https://help.blackboard.com/Learn/Administrator/Hosting/Authentication/Auth_Recovering  If you have back end access, this is like having a key hidden under the rock in your back yard. Run the tool and it gives you a one-time login to the front end so you can reset your username/password.

mkauffman

REST API Deprecation Process

Posted by mkauffman Oct 22, 2018

We've had questions come in regarding REST API v1 deprecation. The answers to these questions inline below:

 

 

   When it comes to V1 route deprecation what will be process of notifying the V1 route consumers?

 

   - What will be the notification process?

 

Deprecation of REST APIs take place only when a new version is released - the deprecation is noted on the API documentation page: https://developer.blackboard.com/portal/displayApi

 

 

   - How long will it take to completely remove once notified? 

 

Removal of deprecated REST APIs from product will take place minimally* one year after deprecation is noted in the API documentation.

*In extremely rare cases this removal may take place sooner than one year - if that is the case it will be noted in the above noted documentation.

 

 

   - Will the V1 routes be removed from existing BB Learn instance versions?

 

Deprecated APIs will continue to work with releases prior to the Learn version from which they are removed.

 

E.G.: API is deprecated in 3300.0 and removed in 3400.0 - the deprecated API will continue to work with all supported Learn versions prior to 3400.0.

 

   - If not, from which Blackboard instance version upwards will V1 routes be removed and when is it scheduled?

 

 

See above.

mkauffman

Leave Some Breadcrumbs

Posted by mkauffman Oct 12, 2018

This one is for B2 developers. All of our current supported Learn builds have a left-navigation menu that comes and goes as you shrink and grow the browser window. Try it. Go into a course and shrink the browser window. You'll see the navigation menu disappear. Now grow the browser window and mouse over the left side of the window. You'll see an arrow that lets you make the navigation menu visible again. But, if your B2 is displaying content on the course page, without the bbNG: pageHeader and bbNG:breadcrumbBar tags, the left-navigation menu will disapper and you will not be able to get it back. Unless you reload the page.

 

This B2 has a sample course tool link which works correctly. GitHub - mark-b-kauffman/bbdn-bblogbackb2: Demo the use of Logback to create log files.

 

Here's a video demonstration: Dropbox - 2018-10-12_16-08-30.UseBreadcrumbs.KeepTheNavMenu.mp4

 

Leave some breadcrumbs!

mkauffman

It's Only A Model

Posted by mkauffman Oct 12, 2018

Camelot (it's only a model) - YouTube

Ok, this is not a blog post about silly movies. I'm writing because of a recent occurrence of difficulty noticing/finding a very important piece of our REST API documentation, the .... wait for it.... Model. As described below reading through the API Models can help reduce the number of REST API calls you make and improve your experience with Blackboard Learn REST endpoints in general.

 

Here we go. When you visit a REST API, you'll see the following Response Example Value.

RESTAPI.ExampleValue.jpeg

All well and good. But! There is a lot of important information hiding under the greyed out Model link. See it? When you click on it, you see the following Model!

RESTAPI.Model.jpeg

 

You really want to read all of that because... way down in the text you'll read:

Since: 3300.9.0

user (

User):

The user associated with the membership.

Shown when adding the query parameter: "expand=user". And can be filtered with the "fields" query parameter, for example "filter=user.uuid,user.externalId".

Which means that you CAN get all of the information you'd like about users in a course when pulling course memberships, without making additional REST calls to the /users endpoint.

 

Be certain to check out the Models!