This project is a multi-purpose application designed to demonstrate several integration methods available with Blackboard Learn. The application is an LTI 1.1, LTI 1.3, and Advantage Tool Provider. It also has code to emit Caliper events, as well as act as a very basic caliper eventstore.
- Node and npm - Installing node on Windows requires installing a number of additional packages. It will warn you and if you don't want the script to do it automatically, the installer will give you a link to instructions to run the installs manually.
You can override a number of configuration properties by creating a config_override.json file in server/config. Below is an example:
{
"frontend_url": "https://example.com/",
"provider_port": "9008",
"database_directory": "server/src/database",
}If you want to run under SSL you should use a reverse proxy, like nginx or ngrok.
All packages needed are in the package.json.
You should have node installed (built with v10.22.1). Then from the project directory at the command line,
type npm start. This will install all of your dependencies and start the server.
Access the application via http://localhost:3000. You can customize the host name and port number by creating a server/config/config_override.json file (see the server/config/config.json file for a template)
To launch the LTI 1 tool, you must launch into the application as an LTI Tool with the url, http://localhost:3000/lti.
Upon launch of the LTI Tool, the user is given a few options:
- Send Outcomes: Send a Grade to the Tool Consumer with LTI Outcomes
- Caliper: Register your Tool as a Caliper Provider and then emit an event to the caliper service. In addition, an endpoint is provided to consume caliper events from the Blackboard Learn server.
- Blackboard REST: The application provides a method to retrieve a REST token and then retrieve the user and course objects based on the UUID passed in the LTI launch.
- Deep Linking: The application provides a method to send Content Item Messages back to Learn simulating a Content provider. This provides a menu of predefined message loads as well as the option to add a custom load.
- Names & Roles Service: Request members for course that launched the tool.
- Assignment & Grades Service: With LTI Advantage a new service is available to get, create, and update line items in the gradebook.
- Return to Learn: This will take the return URL in the LTI Launch and return the user to that place in Blackboard Learn. If no URL is provided, the user is returned to the top-level domain they came from.
To launch the Content Provider simulation call the tool with this url, http://localhost:3000/CIMRequest for use with LTI 1.1. Add the parameter "custom_option" with a value of 1 - 5 (e.g. CIMRequest?custom_option=1) and the corresponding predefined message load from the menu
The application is very simple in its current iteration. Essentially there is one page with a bunch of buttons. Click the one you want. If you are testing caliper, ensure you click the register caliper button at least once. This registers your tool with Blackboard and provides the application with the API Key and Caliper end point. Also, if you wish to ingest Blackbaord's caliper events, you will need to register your application as a caliper event store, which is done in Blackboard Learn.
See the developer documentation site for more details.
This is not meant to be a Node.JS tutorial. It is simply an example of how one might implement the various features therein. Pull requests are welcome!
Implementation of IMS Global LTI v1.3 and LTI Advantage.
A screencast of the rough LTI Advantage setup is shown in Eric Preston's demo at 23:00.
-
Start the server with
npm start.Check that you can access https://example.com/applications
You should see the following output:
Home page: https://example.com/ Registered Applications List: https://example.com/applications LTI 1 Tool Provider: https://example.com/lti LTI 1 Content Item: https://example.com/CIMRequest LTI 1.3 Login URL: https://example.com/login LTI 1.3 Redirect URL: https://example.com/lti13 LTI 1.3 Direct Target URL: https://example.com/lti13 LTI 1.3 Deep Linking URL: https://example.com/deepLinkOptions LTI 1.3 Bobcat Target URL: https://example.com/lti13bobcat LTI 1.3 Proctoring URL: https://example.com/proctoring JWKS URL: https://example.com/.well-known/jwks.json Data will be saved in data Listening on 3000 -
Register your application on the Blackboard Developer Portal
-
Create an account on https://developer.blackboard.com .
-
Navigate to My Apps and register a new application
-
Enter the following fields:
- Application Name: LTI 1.3 Example App
- Description: LTI 1.3 example App
- Domain(s): example.com
- Login Initiation URL: https://example.com/login
- Tool Redirect URL(s): https://example.com/lti13
Click Register application and generate API key
-
Click Done
-
Make a note of the Application ID, key, and secret
-
-
Configure the server
Navigate to https://example.com/applications and click the '+' to add your application. Enter the following into the fields:
- Application Name: The name of your application so it's easily identifiable
- Application Key: The Application ID from the developer portal
- Application Secret: The Application key from the developer portal
- Application Id: The Secret from the developer portal
- DevPortal URL: Select the instance of Developer Portal that was used to create the application:
- Stage: The Learn instance is registered with our beta cloud and the application was created at https://devportal-stage.saas.bbpd.io
- Production: The majority of client and test instances are in this category. The Learn instance is registered with our cloud and the application was created at https://developer.blackboard.com
- CI: Internal only (most developers' instances connect to blue-next and applications are created at https://devportal-ci.saas.bbpd.io) Click SAVE
-
Add the tool to your Learn instance
- Sign into your Learn instance as an administrator
- Navigate to Administrator Tools > Integrations > LTI Tool Providers > Register LTI 1.3 Tool
- In the Client ID field enter the Application ID copied from the developer portal
- Click Submit
-
Create a placement for the tool
In the LTI Tool Providers list, select LTI 1.3 Example App > Manage Placements > Create Placement Enter the following fields:
- Label: LTI 1.3 Example App
- Handle: LTI 1.3 Example App
- Type: Course tool
- Tool Provider URL: https://example.com/lti13
- Click Submit
-
Launch the tool
Navigate to a course. Under Course Management > Course Tools you should see your LTI 1.3 Example App
The normal LTI Resource link should launch to http://localhost:3000/lti13.
This tool supports the LTI asset processor spec. All calls currently hit http://localhost:3000/lti13.
The following functionality is supported:
- Deep link launch in order to link the processor to the platform item. A processor can be returned, similar to other deep link items.
- Asset processor settings launch via LtiAssetProcessorSettingsRequest message type. Echos request payload.
- Asset processor EULA launch via LtiEulaRequest message type. Echos request payload.
- Asset processor report launch via LtiReportReviewRequest message type. Echos request payload.
- Submissions are accepted via the LtiSubmissionNotice message type. These trigger the following behavior:
- After 1 second each asset is downloaded via the provided URL with a LTI token.
- A Processing and Processed message is sent to the platform. A score of 75/100 is reported.
Note: Very little validation is performed in above workflows. For instance, checksums are not verified on assets, so this is suitable for basic testing.
If enabled on the LMS this will be available in the tool.
If enabled on the LMS this will be available in the tool.
The Deep Linking Request should launch to http://localhost/deepLinkOptions to be able to select content items and counts to return. Possible content items are:
- LTI Link
- Content Link
- Embedded LTI Links
- HTML/File/Image Links
- Asset processor
Custom JSON can also be entered and used to create deep linked items.
Docker specific files are included (Dockerfile, docker-compose.yml, launch.sh).
Build the LTI tool container with docker build -t lti-tool .. Then start containers using docker-compose up.
-
$CourseGroup.id
To be used for the integration of Cloud Document contents. Resolve the UUID of the assigned group of the content.
minimum-learn-version: To be used internally for now. Minium version to be defined.
-
$User.externalIdentifiers.UPN for Microsoft
To be used for the integration of Cloud Document contents. Resolve the UPN (User Personal Name) of a user for this Microsoft Integration. For Ultra, the UPN will be the registered institutional email of the user.
minimum-learn-version: To be used internally for now. Minimun version to be defined.