See Release Notes below.
This project is a Django/Python and Learn REST replacement for the Original York DSK Building Block for Learn.
This project is built to be deployed in a variety of ways:
- Heroku: You may read about Heroku here: https://heroku.com. See the Deploy to Heroku button below.
- Docker: You may read about Docker here: https://www.docker.com. See this project's
./docker/README.mdfor Docker details. - cHost: See this project's
./chost/README.mdfor cHost details. - Localhost: See
./local/README.mdfor running on localhost.
The DSKTOOL uses 3LO and as such requires a Learn account and use is restricted based on Learn account privileges.
Note: This is an open source community project and, even though I am an employee, is not supported or sponsored by Blackboard Inc.. If you find it of value please contribute! Pull requests welcome! Make a fork and share your work back to this project.
You must have registered an application in your Developer Portal (https://developer.blackboard.com) account and added it to your Learn instance.
NOTE: Make certain to store your Key and Secret as those will be required when you install the application.
- On your Learn instance create a user ‘DSKTOOLUSER’ and assign them a low, to no, privileged System Role - I have used "guest" - you may alternatively create a specific role if you choose.
Do not assign a System Administrator Role. You may assign the DSKTOOLUSER any Institution Role.
- Create a SYSTEM ROLE: DSKTOOLUSER_SYSTEM_ROLE with no privileges
- Create a USER: DSKTOOLUSER and assign the system role of DSKTOOLUSER_SYSTEM_ROLE
- and use DSKTOOLUSER as the user in the REST API Integration configuration in the next steps
- Navigate to the System Admin page and select the REST API Integrations link.
- Enter your Application Id into the Application Id field
- Set the REST integration user to your ‘DSKTOOLUSER’
- Set Available to 'Yes'
- Set End User Access to 'Yes'
- Set Authorized To Act As User to ‘Yes'
- Click Submit
Learn is now ready and you may proceed with the installation by clicking the below button and following the instructions.
Clicking any of the below 'Deploy to Heroku' buttons will open Heroku to your application setup screen and enable deploying the target branch.
Note: if you do not have a Heroku account you will be prompted to create one and you will be directed to the setup screen on account create completion.
Important: Do not use Development Branch for production! This development branch is intended for development/testing/preview purposes only and may not always provide the best experience.
On the setup screen you will need to name your application dyno, select a region and set the configuration variables:
- Enter an application name - Heroku will let you know if it is valid. e.g. PostDSKTOOL.
- Choose a region that applies or is closest to you.
- Set the required APPLICATION_KEY config variable using the APPLICATION KEY provided when you registered your Application in the Blackboard Developer Portal. (Contains hyphens)
- Set the required APPLICATION_SECRET config variable using the APPLICATION SECRET provided when you registered your Application. (Contains no hyphens)
- Set the BLACKBOARD_LEARN_INSTANCE config variable to the FQDN for your target Blackboard Learn instance. E.g.: demo.blackboard.com. DO NOT include the protocol (http:// or https://)
- Leave the required DISABLE_COLLECTSTATIC config variable set to the current setting of 1 - this is required for a successful deploy.
- Set the required DJANGO_SECRET_KEY config variable using the DJANGO SECRET gennerated from this website: https://djskgen.herokuapp.com NOTE: remove the single quotes e.g.:
=)**)-eozw)jt@hh!lkdc3k-h$gty+12sv)i(r8lp6rn9yn9w&NOT'=)**)-eozw)jt@hh!lkdc3k-h$gty+12sv)i(r8lp6rn9yn9w&'Retaining the single quotes will cause the install to fail.
After entering the above click the 'Deploy app' button at the bottom of the page.
This starts the deployment and on successful completion you will see a message at the bottom of the page 'Your app was successfully deployed.' along with two buttons, one for Managing your app and one to View - click 'View' button to open your app in your browser.
This URL is sticky so bookmark it for later use and you are done!
IMPORTANT: After significant testing I have found that the 3LO redirect to login, which this tool uses, may not work correctly if you are using Direct Portal Entry (where your login is on the community/institution landing page). I believe v1.0.5 mediates this issue.
Additionally, it appears that your 3LO session may expire hourly (check the "Who am I" link) requiring you to log out of the DSKTOOL via the "Learn Logout" link, return to the DSKTOOL homepage and when prompted relogin to Learn.
- Created a multistage build dockerfile to facilitate smaller application image.
- Container updated to run as 'dsktool' user.
- Pushed new images. See: https://hub.docker.com/r/northbynortheast/dsktool-for-learn/tags
A special thank you to Chinmaya Naguri (Ohio University Office of Information Technology) for his PR!
- Added session-based JWT page authorization
Once authenticated via 3LO, your 3LO session lasts for 4 hours.
Note: You should quit your browser after use or use the Learn Logout link to force expire 3LO authentication tokens.
JWT authorization tokens last for 15 minutes. Authorization tokens are refreshed on expiration. API Tokens expire very 60 minutes from first use and are refreshed on expiration. - Added authorization check to run top-level application APIs.
In this case, 'top-level' means any api used before being able to perform a search/submit workflow. - Added a Date Enrolled column to enrollments.
- Added a enhancements to the Reason for Change Report.
- Released comparable v1.2.8 docker image to https://hub.docker.com/r/northbynortheast/dsktool-for-learn/tags
As part of the move away from OSCELOT naming, I have made available a new github site with the new project name of DSKTOOL for Learn. With this release I have also changed the the docker hub URL. Watch release notes and docker-compose.yml file.
- Complete authorization check to run all internal application APIs.
- Add Availability option to Enrollments Course/User searches
- Add Date option to Enrollments Course/User searches
- Add Role option to Course Membership updates
- Clean up code redundancies
- Fixed Heroku deployment
- Fixed Docker deployment
- Upgraded Python to 3.10.5
- Upgraded Django to latest stable (4.0.6 as of this release).
- Removed OSCELOT references
- Fixed change report error on empty database.
- Added capability to clear report database.
- Added capability to download .zip of report database
- Released comparable v1.2.6 docker image to https://hub.docker.com/r/oscelot/oscelot-dsktool/tags
- Removed token expiration time from index page.
- Added 'Contains' search operator on Users and Courses - now supports 'Contains' and 'Exact' searches.
- Added User Family Name via 'Contains' only search operation.
- Added Course Name via 'Contains' only search operation.
- Added "Reason for change" feature - forces entry of why the change was made.
- Added how-to for hosting on CPANEL.
- Released comparable v1.2.5 docker image.
- Removed token information from index page.
- Added token expiration time to index page.
- Altered 3LO behavior with 'offline' scope: Admin is no longer required to log in hourly on API access_token refresh.
- Released comparable v1.2.1 docker image
- Added Date and Availability options to Users/Courses DSK search
- Added Course External Id to User Enrollment results
- Fixed a couple annoying UI issues that no one else probably noticed
- Released comparable v1.2.0 docker image
- Fixed issue with DSK lists being truncated at 100
- Released comparable v1.2.0 docker image.