Learn REST Integrations Tool for System Administrators
Blackboard Learn allows administrators to integrate REST applications into your deployment of Learn. You do this by giving your integration's application ID available to Learn system administrators who can then configure access to your integration. The configure this access with the REST API Integrations tool located on the Learn system admin panel.
Overview of the REST API Integrations Tool
For the other tasks related in this document, use the REST API Integrations.
To navigate to the REST API Integrations tool:
- Select System Admin in the main screen of Blackboard Learn.
- Select the REST API Integrations link is in the Building Blocks section:
The main page for the REST API Integrations tool:
- Lists existing integrations
- Allows you to manage existing integrations
- Allows you to create new integrations
This list will be empty if you have not created any integrations.
Create an Integration
An integration, here, refers to an external REST application being registered to work in conjunction with Blackboard Learn. Before you create an integration, the best practice is to create a Learn user with entitlements that match those required by the REST application.
To create an integration and thereby allow an application to work with your instance of Blackboard Learn:
- On the REST API Integrations page, select Create Integration.
- In the Application ID space, enter the application ID proved by the integration's developers.
- Select Browse next to Learn User. Search through the list of Blackboard Learn users to find the user that the integration should act as.
Select a user that you specially create for the application and that has only the permissions that the integration needs to function properly.
- For third-party integration, set End User Access to Yes. End users will sign in with their own Blackboard Learn ID to use the integration. Each user's access is then limited to his or her own permissions. If you set End User Access to No, the integration always has access as if it were the Blackboard Learn user indicated on the form.
- Submit to save your settings for the integration.
- Select the Learn user in whose name the application acts. This user must have the entitlements required by the REST Application. For more information about identifying required entitlements, see Converting Documented Entitlements to GUI Privileges, below.
Learn user entitlements are allow a REST application to act in your Learn environment. The best practice is to restrict these except as necessary to allow the REST Application to function. The vendor or developer of the REST application should provide a list of required entitlements.
NEVER configure a REST application to act as a System Admin user. Doing so gives the REST application full access to all data and operations of your Learn environment possibly resulting in IRREPARABLE harm. If a vendor requests a System Admin user for their application, do not allow it. In such a case, please provide the vendor's contact and application information to firstname.lastname@example.org so that we can help the vendor correct the situation.
Managing your REST Integration
Once you have created a REST integration, you can manage it:
- Edit the integration settings
- Set the integration availability
- Delete the integration
Edit a REST Integration
The editor displays information about the integration and allows you to change the Learn user that the integration runs as. This allows you to manage the permissions on the integration.
To edit an application's settings, navigate to the REST API Integrations tool. Select Edit from the context menu of the integration that you want to edit. A screen opens like one below.
You may use the standard Learn user and role tools to create an integration-specific user.
Running an Integration
An REST integration can be run in two ways. In both cases, the application is actually remote to the Learn environment.
- A user selects a link within Learn which calls the remote application
- A remote system call from the REST application
Sample code for REST demos is covered in documents in the Examples section.
Converting Entitlements to GUI Privileges
The EntitlementsToAdminGUI worksheet attached (updated 08/10/2019 9:57 AM) helps identify the entitlements to a string which may be searched on in the role privilege selection page when creating the role for your REST Application user. Paste the documented entitlement from the REST API documentation to column A and the privilege will appear in column B.
Should the spreadsheet not have what you're looking for, here's the way to find these manually: Dropbox - 2018-10-30_13-39-25.FindingPrivilegeForGivenEntitlement.mp4