Designdokument for Canvas-integrasjon

1 Innledning

Canvas-integrasjonens primære formål er å automatisk vedlikeholde Canvas med oppdatert informasjon fra kildesystemene SAP, FS og Cerebrum.

En egen mikrotjeneste, canvas-ms, fungerer som et løst koblet integrasjonspunkt i henhold til universitetets integrasjonsarkitektur (UiO:IntArk). Mikrotjenesten sørger for at Canvas holdes oppdatert med data fra kildesystemer.

Data som synkroniseres er:

• Brukerkontoer og tilhørende innloggingsinformasjon fra Cerebrum
• Undervisning og studentdeltakelse fra FS
• Rettigheter for fagpersoner og gruppelærere fra FS
• Organisasjonsstruktur fra SAP

1.1 Kontakt

• Systemeier: Avdeling for fagstøtte (AF)
• Prosjekt: Digitalt Læringsmiljø
• Drift: Seksjon for integrasjon og elektroniske identiteter (USITINT)
• Utvikling: Seksjon for integrasjon og elektroniske identiteter (USITINT)

2 Redegjørelse

Nye integrasjoner skal utvikles etter retningslinjer fra UiO:IntArk. Disse retningslinjene beskriver en tjenesteorientert arkitektur, hvor egne mikrotjenester har ansvar for å flytte data mellom systemer og tjenester. For integrasjon mellom kildesystemer og Canvas betyr dette at:

1. Tjenesten må lytte etter meldinger om endring i kildesystem fra integrasjonsarkitekturens meldingstjeneste.
2. Tjenesten må hente oppdaterte data fra kildesystem gjennom integrasjonsarkitekturens tjeneste for utveksling av data.
3. Tjenesten må implementere forretningslogikk basert på informasjon i meldinger og API.
4. Tjenesten må oppdatere målsystemet Canvas gjennom API-er.

2.1 Tidligere arbeid

Hendelsesdrevet oppdatering av Exchange

Integrasjon med epost- og kalendersystemet Exchange følger ikke UiO:IntArk, men er bygget etter en lignende arkitektur. Exchange-integrasjonen benytter en egen tjeneste i Cerebrum som oppdaterer Exchange gjennom Powershell/WINRM når det har skjedd endringer i data.

Hendelsesdrevet oppdatering av CIM

Integrasjon med HMS og beredskapssystemet CIM benytter samme løsning som Exchange-integrasjonen, men kommunikasjon med CIM går gjennom et REST-API.

Hendelsesdrevet oppdatering av Active Directory

Integrasjon med Active Directory i henhold til UiO:IntArk. En egen mikrotjeneste lytter etter meldinger om endring i Cerebrum, henter oppdaterte data fra API, og oppdaterer Active Directory ved å kjøre Powershell-kommandoer. Selve tjenesten er implementert i Powershell, som har skapt en del utfordringer. Tjenesten er ikke ferdigstilt.

Hendelsesdrevet oppdatering av Cerebrum

Integrasjon mellom SAP og Cerebrum delvis i henhold til UiO:IntArk. En egen tjeneste i Cerebrum lytter etter meldinger fra HR-systemet, henter oppdaterte data fra API, og oppdaterer Cerebrum-databasen direkte. Tjenesten er i produksjon, men kun personaldata synkroniseres via tjenesten.

Batch-oppdatering av Fronter

Integrasjon mellom Cerebrum og et tidligere læringssystem, Fronter. Oppdatering skjer ved at Cerebrum genererer en XML-fil med alle data Fronter ønsker fra UiO, og laster denne opp i en webtjeneste. Integrasjonen benytter ikke en mikrotjeneste, men håndterer samme type data.

2.2 Designvalg

2.2.1 Løsningen implementeres i Python

Tjenesten implementeres i Python, da dette er kjent for utviklingsteamet. Det er et språk som er enkelt å sette seg inn i for nye utviklere, og er også i utbredt bruk hos USIT for utvikling av andre tjenester og driftsverktøy. Videre finnes det gode tredjepartsrammeverk som utviklingsteamet har erfaring med for mye av den nødvendige funksjonaliteten.

2.2.2 Gjenbrukbar kode

Canvas-integrasjonen er den første mikrotjenesten som blir utviklet og ferdigstilt etter retningslinjer fra UiO:IntArk. Det er mest sannsynlig ikke den siste, og andre mikrotjenester vil måtte implementere lignende funksjonalitet. De fleste tjenestene vil måtte hente data fra kildesystemer, og mange vil også være lignende integrasjonstjenester. I utvikling av fremtidige tjenester må man gjerne:

• Abonnere på og behandle meldinger fra meldingstjenesten
• Finne ut hvilke tiltak som må gjøres for å oppdatere et system
• Gjøre oppslag i kildesystem
• Håndtere feil som kan forventes å oppstå

For å unngå duplisering av kode, er Canvas-integrasjonen delt opp i mindre, gjenbrukbare komponenter:

• Et system for å behandle og koble sammen meldinger og handlinger, med nødvendig feilhåndtering.
• Klienter for kommunikasjon med kildesystem.

2.2.3 Kun støtte for Python 3

Alle komponenter og verkøy utvikles kun for Python 3.6 eller nyere. Dette gjør at eksisterende tjenester som benytter eldre versjoner av Python ikke kan dra nytte av felleskomponentene som utvikles. Valget taes for å unngå ekstra teknisk gjeld som måtte blitt påtatt for å støtte eldre versjoner.

3 Detaljbeskrivelse

3.1 Teknisk formål

Tjenesten implementerer:

• Synkronisering av organisasjonsdata mellom SAP og Canvas
• Synkronisering av brukerkontoer mellom Cerebrum og Canvas
• Synkronisering av kurs, roller og kursdeltakelse mellom FS og Canvas
• Konfigurasjon av datastruktur for kurs (Courses og Sections) i Canvas, basert på konfigurasjonsdata fra FS.
• Konfigurerbare navn og identifikatorer på kurs og seksjoner i Canvas

3.2 Høynivådesign

Tjenesten består av en serie med oppgaver. Hver enkelt oppgave implementerer den nødvendige kommunikasjon og forretningslogikk for å oversette data fra kildesystem til et sett med objekter i Canvas. Oppgaver må typisk ha parameter for å identifisere hvilke kildedata som skal behandles. Typiske oppgaver er:

• Sikre at en gitt Canvas-brukerkonto finnes, og har oppdatert informasjon
• Sikre at en gitt Canvas-brukerkonto har riktige roller
• Sikre at et gitt Canvas-kurs finnes, og har oppdatert informasjon
• Sikre at et gitt Canvas-kurs har oppdatert deltakerliste

Oppgavene utføres når tjenesten får beskjed om at data for objektet er endret i et kildesystem. To prosess-grupper sørger for å kjøre riktig oppgave når kildedata endres:

Meldingskonsument (consumer)

Tar i mot meldinger om endring i kildesystem, oversetter melding til riktig oppgaveimplementasjon og parameter, og legger oppgave til i en oppgavekø

Arbeidsprosesser (workers)

Et sett med prosesser som behandler oppgaver i køen.

I tillegg finnes det et API som gir innsyn i oppgavekøen, og gjør det mulig å legge til oppgaver i køen for å gjennomføre synkronisering for et gitt objekt.

En endring i relevante kildedata for Canvas vil typisk gå gjennom følgende flyt:

1. Endring gjøres i kildesystem:
   1. Endringen gjøres synlig i kildesystemet sitt API.
   2. Kildesystemet sender melding til meldingstjeneste om endringen.
   3. Meldingstjenesten sender melding videre til integrasjonens egen meldingskø.
2. Meldingen mottas:
   1. Meldingen sendes fra meldingskø til mikrotjenesten canvas-ms.
   2. Meldingen tolkes og omsettes til en oppgave. Oppgaven legges til i oppgavekøen for senere behandling.
   3. Mottak av meldingen bekreftes, slik at den kan fjernes fra meldingskø.
3. Oppgaven behandles:
   1. Så snart en arbeidsprosess er ledig, vil den ta fatt på oppgaven.
   2. Oppgaveimplementasjonen lastes inn.
   3. Oppgaven utføres.
   4. Oppgavekøen oppdateres.

Oppgaver som fullfører uten feil vil bli fjernet fra oppgavekøen. Oppgaver som feiler vil normalt bli lagt tilbake i oppgavekøen for et nytt forsøk. Ofte vil slike feil forekomme fordi et API er utilgjengelig, og et nytt forsøk på et senere tidspunkt vil løse dette.

Oppgaver som feiler gjentatte ganger vil bli forkastet. I disse tilfellene vil det kreve manuell handling for å løse feilen. Loggen vil inneholde informasjon om oppgaver som har feilet, slik at driftspersonale kan feilsøke.

Dersom en oppgave ikke kan bli avsluttet uten feil, vil det være mulig at Canvas-objekter knyttet til oppgaven ikke har riktig informasjon. Det vil da være nødvendig å sette i gang oppgaven manuelt. Egne driftsverktøy bistår dersom en manuell inntreden er nødvendig:

• API-et gir mulighet for å legge en enkeltoppgave tilbake i oppgavekøen.
• Egne scripts sørger for å oppdatere alle objekter i Canvas dersom tilstanden i systemet skulle avvike veldig fra data i kildesystem.

3.3 Lavnivådesign

Tjenesten består av flere, mindre komponenter. Hver enkelt komponent er et programvarebibliotek for Python, pakket etter retningslinjer for distribusjon.

Selve oppgavekøen og prosessene er implementert i tofh, som er en generell tjeneste for denne typen integrasjon. Oppgaver som ligger i køen er implementert i canvas-ms. De ulike oppgaveimplementasjonene benytter gjenbrukbare komponenter som fs-client, sap-client, cerebrum-client, og canvas-client for å kommunisere med relaterte systemer.

3.3.1 klient-biblioteker

Alle REST-API som benyttes i Canvas-integrasjonen får et eget klient-bibliotek, slik at arbeid med API-kommunikasjon kan gjenbrukes i andre tjenester.

Bibliotekene inneholder typisk:

• Støtte for autentisering.
• Funksjoner for å hente ut og oppdatere objekter i API-et.
• Støtte for uthenting av oppdelte (paginerte) lister.
• Støtte for å følge referanser i API-et.

fs-client

Klient-bibliotek for å hente ut Canvas-relaterte data fra FS sitt REST-API.

Spesielt for klienten er:

• Tolking og oversetting av FS-identifikatorer (f.eks. hente ut Emne-identifikator fra en Undervisning-identifikator)
• Bruk av FS-identifikator i søk (f.eks. list alle Undervisning-objekter som hører til en gitt Emne-indentifikator)
• Støtte for FS sin egen autentiseringsmekanisme (Basic-auth for å hente JWT, JWT Bearer-token for alt annet).

sap-client

Klient-bibliotek for å hente ut Canvas-relaterte data fra SAP sitt REST-API.

cerebrum-client

Klient-bibliotek for å hente ut Canvas-relaterte data fra Cerebrum gjennom REST-API.

canvas-client

Klient-bibliotek for å vedlikeholde data i Canvas gjennom Canvas sitt REST-API. Klienten har funksjonalitet for å hente ut og oppdatere de fleste typer objekt i Canvas.

3.3.2 tofh

tofh implementerer en abstrakt mikrotjeneste for å gjøre integrasjon mellom et målsystem og flere kildesystemer, hvor kildesystemene har støtte for publisering av endringer via meldingskøer og API-er.

Tjenesten består av:

Konfigurasjon

En liste over kjente oppgaver.

Oppgavekø

Oppgaver legges i en kø, som senere behandles av arbeidsprosesser. Arbeidsprosesser benytter en oppgaveimplementasjon for å oppdatere målsystem med endringer.

Lasting av oppgaveimplementasjon

En oppgave implementeres i en Python-funksjon som kan importeres og kjøres av arbeidsprosesser.

Utplukkskriterier for meldinger

Utplukkskriterier er typisk en eller flere regulære uttrykk som sammenlignes med metadata fra meldinger (f.eks. routing key), og definerer hvilke meldinger som gjør at en oppgave utføres.

Tolking av meldinger

Tolking av meldinger implementeres i en Python-funksjon som kan importeres og kjøres av meldingskonsument. Slike funksjoner skal da hente ut nødvendig informasjon fra støttede meldinger.

Oppgavekøen i tofh er et overbygg over en eksisterende task queue-implementasjon, Celery, og tilfører bl.a. støtte for å laste inn oppgaver dynamisk fra konfigurasjon.

Mottak av meldinger i tofh er implementert ved hjelp av tredjepartsbiblioteket pika, og er en generell asynkron AMQP-konsument. Ved mottak av melding vil et tofh-callback kjøres av konsumenten. Dette callbacket sørger for å:

1. Hente metadata fra melding og sammenligne disse mot utplukkskriterier i konfigurasjon.
2. Laste inn og kjøre funksjonalitet for å hente ut relevante data fra melding (oppgaveparameter).
3. Legge til oppgave og verdier for oppgaveparameter i oppgavekø.
4. Bekrefte mottak av melding.

3.3.3 canvas-ms

canvas-ms er et python-bibliotek som knytter sammen meldinger, kommunikasjon med kildesystem, provisjonering av målsystem, og forretningsregler som styrer hvilke data som skal overføres.

Det er også her Canvas-oppgaver er implementert - disse oppgavene består typisk av å:

1. Hente data fra kildesystemer
2. Hente data fra Canvas
3. Sammenligne data
4. Synkronisere data som er utdatert

Ikke alle brukerkontoer i Cerebrum gir Canvas-bruker. Hovedregelen her er at primærbruker for en gitt person blir overført. Dette er den samme brukerkontoen som benyttes i Feide. I tillegg vil brukerkontoer som er sperret i Cerebrum også være sperret i Canvas. Enkeltbrukere kan også utelates i integrasjonen, dersom det skulle være særskilte behov for dette.

Det blir også kun opprettet Course-objekter i Canvas for Utdanningsenheter og utdanningsaktiviteter som er merket med eksport i FS. Videre kan flagg i FS benyttes for å markere om en utdanningsenhet eller utdanningsaktivitet skal opprettes som et eget Course-objekt, eller slåes sammen til ett enkelt Course-objekt med flere seksjoner. Alle terminer i et flerterminemne (undervisningsenheter som er delt over HØST/VÅR) vil alltid bli slått sammen til et Course-objekt eller en enkelt seksjon.

Navn og identifikatorer på Course-objekter, seksjoner, o.l. i Canvas kan konfigureres. Informasjon om emnet kan benyttes i navnet, mens identifikatorer (SIS-ID) kan inneholde felter fra tilhørende FS-indentifikator.

4 Avhengigheter

4.1 Systemet er avhengig av

Mikrotjenesten er avhengig av en rekke andre systemer for innhenting og oppdatering av data.

• FS: Tjenesten må ha meldinger fra FS og tilgang til FS sitt REST-API for å få oppdaterte rolledata, kursdata og data om kursdeltakelse.
• SAP: Tjenesten må ha meldinger fra SAP og tilgang til SAP sitt REST-API for oppbygging av organisasjonsstruktur og potensielt HR-data dersom dette skulle bli aktuelt i fremtiden.
• Cerebrum: Tjenesten må ha meldinger fra Cerebrum og tilgang til Cerebrum sitt REST-API for å få oppdaterte data om brukerkontoer som også skal eksistere i Canvas.
• Canvas: Tjenesten er avhenging av tilgang til Canvas sitt REST-API for å sammenligne og oppdatere data.
• Meldingstjeneste: Tjenesten er avhengig av UiO:IntArk sin meldingstjeneste for å få meldinger fra kildesystemer.
• API-gateway: Tjenesten er avhengig av UiO:IntArk sitt aksesspunkt for API-er for å hente data fra kildesystemer.
• Celery: Tjenesten benytter task queue-implementasjonen Celery (les mer om Celery-prosjektet), og må ha tilgang til lagringsbackends for denne:
  • Backend for oppgaver i kø, enten en AMQP-kø eller en Redis-database.
  • Backend for oppgaveresultater, enten en Redis-database eller en Postgres-database.

4.2 Andre systemer er avhengig av

Canvas er avhengig av denne mikrotjenesten for å få oppdaterte data. Et eventuelt tjenestebrudd vil gjøre at Canvas-data ikke er i tråd med endringer som skjer i kildesystemer.

Dette betyr at korte tjenestebrudd i mikrotjenesten eller dens avhengigheter vil forårsake forsinkelse i synkronisering mot Canvas, og typisk føre til brudd i tjeneste for nye studenter og kurs. Videre vil eventuell sperring av brukerkonto utgjøre en sikkerhetsrisiko dersom dette ikke blir synkronisert mot Canvas.

5 Relaterte systemer

Felles Studentsystem (FS)

FS er Universitetet i Oslo sitt system for data om studenter og studier. Les mer om FS ved UiO.

SAP

SAP benyttes ved Universitetet i Oslo som lønns- og personalsystem, og inneholder bl.a. data om organisasjonsstruktur. Les mer om SAP ved UiO.

Cerebrum

Cerebrum er Universitetet i Oslo sitt system for håndtering av elektroniske identiteter og styring av tilgangskontroll i IT-systemer. Les mer om Cerebrum.

Canvas

Canvas er et læringssystem (LMS) som benyttes ved Universitetet i Oslo. Systemet benyttes for kommunikasjon mellom studenter og unvervisere, bl.a. ved publisering av læringsressurser. Les mer om Canvas ved UiO.

Canvas erstatter tidligere læringssystemer som Fronter.