Deze gids laat zien hoe je de LMS API binnen eJournal inschakelt. Let op: deze gids gaat ervan uit dat je over de benodigde bevoegdheden binnen het LMS beschikt.
Zorg ervoor dat je LTI al hebt gekoppeld; zie voor meer informatie deze gids.
Heb je al een bestaande LMS API-integratie met eJournal en wil je die alleen verbeteren door een systeemaccount in te schakelen, log dan in met het bestaande systeem- of beheerdersaccount en ga direct door naar stap 3.
¶ Stap 1: Stel de API-sleutel in het LMS in
- Ga in de beheerdersinstellingen naar 'Developer Keys'
- Klik op '+ Developer Key' en vervolgens op '+ API Key'
- Vul de volgende velden als volgt in:
- 'Key Name': "eJournal API"
- 'Owner Email': "admin@ejournal.app"
- 'Redirect URIs':
https://api.[your institute subdomain].ejournal.app/lms/authenticate/
- eJournal maakt gebruik van de volgende scopes:
- Under 'Assignments'
- url:GET|/api/v1/users/:user_id/courses/:course_id/assignments
- url:GET|/api/v1/courses/:course_id/assignments
- Under 'Courses'
- url:GET|/api/v1/courses
- url:GET|/api/v1/courses/:id
- 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
- url:GET|/api/v1/users/:user_id/profile
- Zorg ervoor dat de optie 'Allow Include Parameters' is ingeschakeld.
- Klik op 'Save' en zet de status op 'ON'. De Client ID en Client secret vind je onder 'Details'. De knop 'Show key' toont de secret; de waarde daarboven is de Client ID. Geef deze door aan eJournal.
- Ga naar 'Manage Extensibility'
- Klik onder 'OAuth 2.0' op 'Register an App'
- Vul de volgende velden in:
- Application Name:
eJournal - Redirect URI:
https://api.[your institute subdomain].ejournal.app/lms/authenticate/ - Scope:
core:*:* enrollment:orgunit:read enrollment:own_enrollment:read orgunits:course:read groups:group:read sections:section:read role:detail:read users:userdata:read - Access Token Lifetime: 3600 (ongewijzigd)
- Vink 'Prompt for user consent' en 'Enable refresh tokens' aan en accepteer de 'Non-Commercial Developer Agreement'
- Klik op 'Register'
- Geef de 'Client ID' en 'Client Secret' door aan eJournal
¶ Informatie over de scopes
| Scope | Pad(en) | Reden |
|---|---|---|
enrollment:orgunit:read |
|
Gebruikersgegevens ophalen om gebruikers naar eJournal te synchroniseren. |
orgunits:course:read |
|
Cursusgegevens ophalen om de cursus naar eJournal te synchroniseren. |
enrollment:own_enrollment:read |
enrollments/myenrollments/ |
De ingeschreven cursussen van de huidige gebruiker ophalen om een inzending naar eJournal te importeren. |
groups:group:read |
|
De groepscategorieën en hun groepen ophalen om groepen naar eJournal te synchroniseren. |
sections:section:read |
|
De secties ophalen om groepen naar eJournal te synchroniseren. |
role:detail:read |
roles/ |
De rollen van Brightspace ophalen om deze aan eJournal-rollen toe te wijzen. |
users:userdata:read |
users/ |
Gebruikersinformatie ophalen die wordt gebruikt voor gebruikerssynchronisatie. |
core:*:* |
|
|
We gebruiken de scope
core:*:*omdat we een aantal API's gebruiken die nog geen eigen specifieke scope hebben. Zie de documentatie hier.
¶ Stap 2: Sla de Client ID en secret op in eJournal
- Ga naar het beheerderspaneel
- Selecteer het tabblad integraties.
- Selecteer het onderdeel LMS.
- Sla onder de kop API de waarden uit de vorige stap op.
API succesvol gekoppeld!
¶ Stap 3 (optioneel): Een systeemaccount instellen
Onder de client secret vind je de mogelijkheid om een systeemaccount in te stellen. Is dit ingesteld, dan verlopen alle synchronisatieverzoeken via het systeembrede account. Dat is handig wanneer niet alle gebruikers toegang hebben tot alle accountinformatie, omdat het garandeert dat eJournal genoeg rechten heeft om alle relevante informatie op te halen. Volg deze stappen om het account in te stellen:
In je LMS
- Navigeer naar het LMS
- Log in met een bestaand systeem- of beheerdersaccount, of maak een nieuw account aan, ken het de vereiste toegang toe (zie hieronder) en log in met dit account
In je LMS ben je nu ingelogd als het bestaande of nieuwe systeemaccount in wording.
In eJournal
- Navigeer in eJournal naar de eJournal API-instellingen en klik op "authorize system account"
- Zorg dat je binnen het LMS op het juiste systeemaccount bent ingelogd voordat je op "authorize system account" klikt. Dat is het geval als je de stappen onder "In je LMS" hierboven hebt gevolgd. (Weet je het niet zeker, open dan een incognitotabblad en doorloop de stappen daar opnieuw, zodat je zeker weet dat de juiste gebruikerssessies actief zijn).
- Je wordt gevraagd de autorisatie in een nieuw tabblad op het LMS af te ronden
- Zodra dit is gelukt, sluit je dit tabblad en klik je in eJournal op "verify token"
- Als alles goed is gegaan, verschijnt er een bevestigingsmelding
Voordelen
- Voldoende zekerheid over zowel de cursusdeelname als de actuele status van gebruikers.
- Groepen automatisch actueel houden (inclusief verwijderen), omdat we dan de garantie hebben dat de gegevens volledig zijn — dit geldt ook voor de punten hieronder.
- Cursusleden automatisch actueel houden (inclusief verwijderen).
- Gebruikers op inactief zetten (op dit moment is die informatie niet betrouwbaar genoeg).
- Volledige gebruikersinformatie (geen ontbrekende attributen), zodat:
- We dubbele accounts voorkomen;
- (Handmatige) bulkacties mogelijk worden, zoals het toevoegen van docentenentries (bewijsstukken en/of resultaten die door de docent zijn ingediend) en het importeren van (samenwerk)groepen. Op dit moment kunnen deze acties niet altijd aan gebruikers gekoppeld worden doordat attributen ontbreken.
- Niet alle docenten krijgen een eigen autorisatievenster, waardoor we minder toegangstokens opslaan.
- Met een apart systeemaccount kun je de toegang goed afbakenen, terwijl de tokens die we nu opslaan lastig bij te houden zijn en mogelijk ruimere toegang geven.
- Een eventuele toekomstige uitbreiding van de vereiste API-scopes kan centraal geregeld worden, in plaats van dat elke gebruiker opnieuw afzonderlijk toegang moet verlenen, terwijl delen van de integratie ondertussen niet goed geregeld zijn.
Het systeemaccount moet toegang hebben tot de volgende endpoints in alle LMS-cursussen waarin eJournal wordt gebruikt. Dat betekent ook volledige toegang tot de informatie die wordt teruggegeven (bijvoorbeeld de login id zoals gedefinieerd in User):
- GET /api/v1/courses/:course_id/users
- GET /api/v1/courses/:course_id/sections (inclusief studenten)
In het groen zie je wat het systeemaccount toevoegt:
Het uiteindelijke 'get data'-verzoek wordt niet langer beperkt door de toegang van de gebruiker die de gegevens opvraagt. Dat is vooral handig bij het synchroniseren van cursusleden, of om te voorkomen dat er dubbele gebruikersaccounts worden aangemaakt door ontbrekende informatie.
Het systeemaccount moet toegang hebben tot de volgende endpoints in alle LMS-cursussen waarin eJournal wordt gebruikt. Dat betekent ook volledige toegang tot de informatie die wordt teruggegeven (bijvoorbeeld de gebruikersnaam zoals gedefinieerd in Enrollment.ClasslistUser):
- /d2l/api/le/(version)/(orgUnitId)/classlist/ [GET]
- /d2l/api/lp/(version)/enrollments/orgUnits/(orgUnitId)/users/ [GET]
- /d2l/api/lp/(version)/imsconfig/map/roles/ [GET]
- /d2l/api/lp/(version)/roles [GET]
- /d2l/api/lp/(version)/(orgUnitId)/groupcategories/ [GET]
- /d2l/api/lp/(version)/(orgUnitId)/groupcategories/(groupCategoryId)/groups/ [GET]
- /d2l/api/lp/(version)/(orgUnitId)/sections/ [GET]
- /d2l/api/lp/(version)/users/whoami [GET]
- /d2l/api/versions/check [POST]
Hier is een voorbeeld van zo'n accountopzet die je in Brightspace kunt importeren en als basis voor het bovenstaande kunt gebruiken: permissions system account.txt.
¶ Stap 4: Laat eJournal weten dat de API is ingesteld
Laat je contactpersoon bij eJournal weten dat de LMS API succesvol is gekoppeld. Weet je niet wie je vaste contactpersoon is, mail dan naar support@ejournal.app.
¶ Stap 5: Controle
Wil je dat liever, dan kun je een medewerker van eJournal vragen de API-verbinding te controleren.
Om er zeker van te zijn dat de API-integratie goed is ingesteld, kun je de volgende test uitvoeren:
- Start eJournal als docent via de LTI-integratie op opdrachtniveau.
- Sta studenten in de opdrachteditor toe LMS-inzendingen te importeren.
- Start eJournal als student vanuit dezelfde opdracht.
- Test of de student zijn LMS-inzending kan importeren (of, als de student nog geen inzendingen heeft, in elk geval zijn cursussen kan ophalen).
Dat is alles! Loop je ergens tegenaan, neem dan contact op met je vaste contactpersoon (of support@ejournal.app).