Designdokument for Kada

1 Innledning

Formålet med Kada (Kalenderdata) er å sammenstille informasjon fra TP, FS og Cerebrum slik at man får et komplett sett med kalenderdata for alle ansatte og studenter.

Alle komponentene i tjenesten fungerer som løse integrasjonspunkter i henhold til universitetets integrasjonsarkitektur (UiO:IntArk). 

Mikrotjenesten Kada lytter på notifikasjoner fra TP, FS og Cerebrum, henter data fra disse systemene og vedlikeholder koblingen mellom personer og hendelser de skal delta på.

Mikrotjenesten Kada-Exchange lytter på notifikasjoner fra Kada og sørger for å vedlikeholde personers personlige kalender i Exchange.

1.1 Kontakt

• Systemeier: Gruppe for drift av macOS, mobile tjenester og meldingstjenester (GM3)
• Prosjekt: Kalenderdata
• Drift: Seksjon for integrasjon og elektroniske identiteter (USITINT)
• Utvikling: Seksjon for integrasjon og elektroniske identiteter (USITINT) og Gruppe for publiseringsløsninger (GPL)

Seksjon for digitale tjenester i Studieadministrasjonen er systemeier for kildesystemene FS og TP.

2 Redegjørelse

Hovedmålet med tjenesten er å sørge for at ansatte og studenter skal kunne forholde seg til ett system for å få oversikt over alle sine kalenderdata. Et premiss er at Exchange skal være den primære visningsflaten for disse dataene. I tillegg skal kalenderdataene knyttes til personlige kalendre i Exchange, som er den eneste måten å sørge for at opptattstatus blir synlig for andre i organisasjonen.

2.1 Løsningsdesign

Prosjekt Kalenderdata sitt mandat la føringer for løsningsdesignet, spesielt dokumentet Løsningsforslag og estimat for integrasjon av kalenderdata.

2.2 Integrasjonsarkitekturen

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. Dette betyr at:

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

I dette tilfellet består løsningen av de to mikrotjenestene Kada og Kada-Exchange som hver for seg følger flyten over.

2.3 Tidligere arbeid

Hendelsesdrevet oppdatering av Canvas

Integrasjonen som vedlikeholder læringsplattformen Canvas med data fra FS, SAP og Cerebrum følger samme arkitektur. Kada benytter seg av mange av de samme kodebibliotekene som Canvas-integrasjonen. Les mer om Canvas-integrasjonen.

2.4 Andre designvalg

2.4.2 Løsningen implementeres i Python

Komponentene implementeres i Python, da dette er mest kjent for utviklingsteamet som vil ha ansvaret for videreutvikling og vedlikehold. Det er et språk som er enkelt å sette seg inn i for nye utviklere, og er også i utbredt bruk hos USIT. Videre finnes det gode tredjepartsrammeverk som utviklingsteamet har erfaring med for mye av den nødvendige funksjonaliteten, inkludert kommunikasjon med Exchange via EWS.

2.4.3 Django brukes som rammeverk

Django er et webrammeverk for Python, som sammen med Django REST framework gjør det enkelt å lage gode API-er. Ved å ta i bruk et etablert og populært webrammeverk kan man enkelt dra nytte av funksjonalitet som er utviklet og vedlikeholdt av andre, og samtidig unngå en del sikkerhetsrelaterte fallgruver.

Hos USIT brukes Django også av DNS-administrasjonsverktøyet Mreg.

2.4.4 Gjenbruk av kode

Kada gjenbruker komponenter som er allerede er utviklet i forbindelse med liknende integrasjoner, blant annet:

• Et system for å behandle og koble sammen notifkasjoner og handlinger, med nødvendig feilhåndtering.
• Klienter for kommunikasjon med kilde- og målsystemer.

3 Detaljbeskrivelse

3.1 Teknisk formål

3.1.1 Kada

Tjenesten Kada implementerer:

• Håndtering av notifikasjoner fra FS og TP
• Mellomlagring av data fra TP:
  • Timeplaner for emner.
  • Timeplaner for faglærere.
  • Metadata (tittel, type, pensum, sted, ...) for hver enkelt kalenderhendelse.
  • Informasjon om rom og bygninger.
  • Informasjon om faglærere.
• Mellomlagring av data fra FS:
  • Informasjon om hvilke undervisningsaktiviteter hver enkelt student er påmeldt.
• Oppslagstjeneste for kalenderhendelser, med mulighet for filtrering
• Utsending av notifikasjoner dersom
  • informasjon om en kalenderhendelse endrer seg
  • en person legges til eller fjernes fra en kalenderhendelse

3.1.2 Kada-Exchange

Tjenesten Kada-Exchange implementerer

• håndtering av notifikasjoner fra Kada
• synkronisering av kalenderhendelser fra Kada til Exchange

3.2 Høynivådesign

Tjenestene består av en serie med oppgaver. Hver enkelt oppgave implementerer den nødvendige kommunikasjon og forretningslogikk for å oversette data fra kildesystem til ønsket tilstand i målsystemet. Oppgaver må typisk ha parameter for å identifisere hvilke kildedata som skal behandles.

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:

Notifikasjonskonsument (consumer)

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

Arbeidsprosesser (workers)

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

3.2.1 Kada

Siden Kada fungerer som et kildesystem for Kada-Exchange, må den også sende notifikasjoner. Det er skrevet funksjonalitet som skriver en notifikasjon til en lokal notifikasjonstabell ved opprettelse, sletting eller endring av objekter eller deres relasjoner til andre objekter.

Notifikasjonsprodusent (publisher)

Venter på at notifikasjoner skrives til notifikasjonstabellen. Transformerer radene i notifikasjonstabellen til en notifikasjon, sender disse til notifikasjonskøen og sletter notifikasjonsraden.

3.3 Lavnivådesign

3.3.1 Kada

Kada er bygget for å være et helt generisk system for å holde styr på personer, hendelser og relasjonen mellom disse. Det bygger på webrammeverket Django. Funksjonaliteten som implementerer støtte for å ta i bruk data fra TP og FS befinner seg i tilleggsmoduler kalt Kada-TP og Kada-FS. De fungerer fint hver for seg, men for å få full kalenderoversikt for både ansatte og studenter må begge aktiveres.

kada-tp

Implementerer logikk relatert til behandling av notifikasjoner og data fra TP. Tilleggsmodul for Django. Benytter tp-client.

kada-fs

Implementerer logikk relatert til behandling av notifikasjoner og data fra FS. Mellomlagrer kobling mellom FS-personløpenummer og brukernavn for bedre ytelse. Tilleggsmodul for Django. Benytter fs-client.

3.3.2 Oppgavekøer

Oppgavekøene i Kada og Kada-Exchange er implementert i tofh, som er et generelt verktøy for å kalle på prosesseringslogikk ved mottak av notifikasjoner fra kildesystemer. Les mer om tofh.

3.3.3 Klientbiblioteker

Alle API-er som benyttes i denne og liknende integrasjoner har hvert sitt klientbibliotek. Felles for klientene som prater med REST API-er er at de benytter tredjepartsbibliotekene requests (HTTP-kommunikasjon) og pydantic (validering av data).

Bibliotekene inneholder typisk:

• Støtte for autentisering.
• Funksjoner for å hente ut og oppdatere objekter i API-et.
• Validering av data man får fra API-et i henhold til definerte datamodeller.
• Støtte for uthenting av oppdelte (paginerte) lister.
• Støtte for å følge referanser i API-et. 

fs-client

Klientbibliotek for å hente ut 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).

kada-client

Klientbibliotek for å hente og validere data fra Kada sitt REST-API.

tp-client

Klientbibliotek for å hente og validere data fra TP sitt REST-API.

cerebrum-client

Klientbibliotek for å hente og validere data fra Cerebrum sitt REST-API.

exchange-client

Klientbibliotek for å hente og oppdatere kalenderdata via Exchange sin SOAP-tjeneste (EWS). Bygger på tredjepartsbiblioteket exchangelib.

3.3.4 Kort om driftsregime

Kildekodeavhengigheter og det virtuelle Python-miljøet til Kada og Kada-Exchange styres ved hjelp av verktøyet Pipenv. Denne sørger for å låse alle avhengigheter og deres under-avhengigheter til en spesifikk versjon, slik at nye versjoner av pakker kan kvalitetssikres før de rulles ut.

Kada og Kada-Exchange bygges som container images og lastes opp til Harbor, UiOs register for container images. Harbor håndhever tilgangskontroll til bildefilene og skanner jevnlig etter sårbarheter.

Hver komponent/prosess kjører i hver sin Docker-container. Eventuell kommunikasjon mellom mikrotjenestene skjer gjennom UiOs API gateway.

Tjenestene konfigureres via konfigurasjonsfiler som er montert opp i containeren. Stien til konfigurasjonsfilen settes i en miljøvariabel.

Konfigurasjonsfiler for tjenestene og Docker Compose genereres via Ansible-skript som befinner seg i Git-repoet kada-deploy. Eventuelle hemmeligheter sikres ved hjelp av Ansible Vault der privatnøkkelen befinner seg på serveren det deployeres til.

Les mer om sikring av containerbaserte tjenester.

4 Avhengigheter

4.1 Systemet er avhengig av

Mikrotjenestene er avhengig av en rekke andre systemer for innhenting og oppdatering av data:

• FS: Tjenesten Kada må ha notifikasjoner fra FS og tilgang til FS sitt REST-API for å få oppdaterte data om kursdeltakelse.
• TP: Tjenesten Kada må ha notifikasjoner fra TP og tilgang til TP sitt REST-API for å få oppdaterte data om timeplaner.
• Cerebrum: Tjenestene Kada og Kada-Exchange må ha tilgang til Cerebrum sitt REST-API for å få kunne koble personidenfikatorer fra ulike kildesystemer til riktig mailboks/kalender.
• Exchange: Tjenesten Kada-Exchange er avhenging av tilgang til Exchange sin SOAP-tjeneste (Exchange Web Services) for å vedlikeholde personlige kalendre.
• Postgres: Tjenesten Kada bruker Postgres som databaselager.
• Harbor: Tjenestene Kada og Kada-Exchange startes fra container-images som er lagret i tjenesten Harbor.
• Notifikasjonstjeneste: Tjenesten er avhengig av UiO:IntArk sin notifikasjonstjeneste (RabbitMQ) for å få notifikasjoner fra kildesystemer.
• API-gateway: Tjenesten er avhengig av UiO:IntArk sitt aksesspunkt for API-er for å
  • hente data fra kildesystemer.
  • oppdatere data i målsystemer.
• Celery: Tjenestene som bygger på tofh som oppgavekø 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 avhengige av

Exchange vil være avhengig av mikrotjenestene for å få oppdaterte kalenderdata. Et tjenestebrudd vil gjøre at kalenderdataene som er tilgjengelig for sluttbrukere ikke er i tråd med endringer som skjer i kildesystemene.

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.

Timeplanlegging (TP)

TP er systemet for timeplanlegging og eksamensplanlegging ved UiO. Les mer om TP 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.

Exchange

Exchange er e-post- og kalendersystemet ved UiO. Les mer om e-post og kalender på UiO.

6 Lenker og referanser

6.1 Kildekode

• kada: Kada, Kada-TP og Kada-FS
• kada-exchange: Kada-Exchange
• kada-client: Klientbibliotek for kommunikasjon med Kada sitt API
• kada-deploy: Deployeringsverktøy (tilgangsbegrenset)