This guides show you how to enable the LMS API within eJournal. Please note that this guide assumes you have the required privileges within the LMS.
Make sure you already integrated LTI, for more information see this guide.
¶ Step 1: Configure the API Key in the LMS
- Go in the admin settings to 'Developer Keys'
- Click on '+ Developer Key', then '+ API Key'
- Fill the following fields in as follows:
- 'Key Name': "eJournal API"
- 'Owner Email': "admin@ejournal.app"
- 'Redirect URIs':
https://api.[your institute subdomain].ejournal.app/lms/authenticate/
- eJournal makes use of the following scopes:
- Under 'Assignments'
- url:GET|/api/v1/users/:user_id/courses/:course_id/assignment
- url:GET|/api/v1/courses/:course_id/assignments
- Under 'Courses'
- url:GET|/api/v1/courses
- url:GET|/api/v1/courses/:course_id/students
- url:GET|/api/v1/courses/:course_id/users
- Under 'Sections'
- url:GET|/api/v1/courses/:course_id/sections
- Under 'Submissions'
- url:GET|/api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id
- Under 'Users'
- url:GET|/api/v1/users/:id
- Make sure the 'Allow Include Parameters' option is enabled.
- Click on 'Save', and switch the state to 'ON'. The Client ID and Cliend secret can be found under 'Details'. The 'Show key' button showing the secret, and the value above being the Client ID. Report these back to eJournal.
- Go to 'Manage Extensibility'
- Under 'OAuth 2.0' click 'Register an App'
- Fill in the following fields:
- Application Name:
eJournal - Redirect URI:
https://api.[your institute subdomain].ejournal.app/lms/authenticate/ - Scope:
core:*:* enrollment:orgunit:read enrollment:own_enrollment:read groups:group:read sections:section:read - Access Token Lifetime: 3600 (unchanged)
- Tick 'Prompt for user consent', 'Enable refresh tokens' and accept the 'Non-Commercial Developer Agreement'
- Click 'Register'
- Report back the 'Client ID' and 'Client Secret' to eJournal
¶ Scope information
| Scope | Path(s) | Motivation |
|---|---|---|
enrollment:orgunit:read |
enrollments/orgUnits/{orgID}/users/ |
Retrieve user data in order to synchronize users to eJournal. |
enrollment:own_enrollment:read |
enrollments/myenrollments/ |
Fetching enrolled courses of the current user in order to import a submission to eJournal. |
groups:group:read |
|
Fetching the group categories and their groups in order to synchronize groups to eJournal. |
sections:section:read |
|
Fetching the sections in order to synchronize groups to eJournal. |
core:*:* |
|
|
We make use of the
core:*:*scope because we use some APIs that have not yet received their own dedicated scope. See the docs here.
¶ Step 2: Save the Client ID and secret in eJournal
Within the eJournal admin panel, navigate to the tab "LTI Integration". Here under the LMS API header, store the values from the previous step.
API successfully connected!
¶ Step 3: Let eJournal know the API is setup
Let your eJournal point of contact know the LMS API is successully connected, if you are unsure who your assigned point of contact is you can email support@ejournal.app.
¶ Step 4: Verification
When preferred, you can ask an eJournal staff member to verify the API connection.
To make sure the API integration is succesfully setup you can make use of the following test:
- Launch eJournal as a teacher using the LTI integration on assignment level.
- In the assignment editor, allow students to import LMS submissions.
- Launch eJournal as a student from the same assignment.
- Test if the student is able to import their LMS submission (or when the student has no submissions yet, at least is able to retrieve their courses).
That's it! If there is any issue, please reach out to your assigned point of contact (or support@ejournal.app).