Greg-intergrasjon i Cerebrum

Gjester og gjesteroller

Informasjon om gjesteroller finnes på https://www.uio.no/for-ansatte/arbeidsstotte/lonnsadministrasjon/gjest.html#roller. I Cerebrum representeres disse rollene som tilknytninger:

• Emeritus → TILKNYTTET/emeritus
• Gjesteforsker → TILKNYTTET/gjesteforsker
• Ekstern konsulent → TILKNYTTET/ekst_partner
• Ekstern parner → TILKNYTTET/ekst_partner

Integrasjon

For å bygge brukerkonto for gjester, trengs en integrasjon mellom Greg og Cerebrum. Denne integrasjonen består kort oppsummer av:

1. Synk av persondata og roller fra Greg til Cerebrum
2. Automatisk brukeroppretting for gjester

Meldinger

Greg sender meldinger hver gang noe relevant endres, og sender også melding når eventuelle start- eller sluttdatoer inntreffer for f.eks. roller.

Meldinger følger CloudEvents 1.0.1.

Eksempel-meldinger:

{"specversion": "1.0", "id": "27", "source": "greg:uio:test", "data": {"person_id": 4}, "type": "person.add"}
{"specversion": "1.0", "id": "28", "source": "greg:uio:test", "data": {"person_id": 4}, "type": "person.update"}
{"specversion": "1.0", "id": "26", "source": "greg:uio:test", "data": {"person_id": 3}, "type": "person.delete"}
{"specversion": "1.0", "id": "29", "source": "greg:uio:test", "data": {"person_id": 4}, "type": "identity.add"}
{"specversion": "1.0", "id": "31", "source": "greg:uio:test", "data": {"person_id": 4}, "type": "identity.delete"}
{"specversion": "1.0", "id": "37", "source": "greg:uio:test", "data": {"person_id": 4}, "type": "role.add", "data"}
{"specversion": "1.0", "id": "38", "source": "greg:uio:test", "data": {"person_id": 4}, "type": "role_type.add"}
{"specversion": "1.0", "id": "39", "source": "greg:uio:test", "data": {"person_id": 4}, "type": "role.update"}

API

OpenAPI-dokuemntasjon fra testmiljø: https://greg-uio-test.uio.no/schema/swagger-ui/

Relevante endepunkter:

• GET /api/v1/person/{id} - Persondata for en person-id fra Greg
• GET /api/v1/person/ - Utlisting av alle personer, f.eks. til fullsync

Flyt

1. Mottakk av melding.

   • Funksjon for å oversette meldinger til tasks.
   • consumers/consume-tasks.py lytter etter meldinger, og bruker nevnte funksjon for å lage tasks som legges i kø.

2. Import/sync av persondata.

   En jobb kjører regelmessig for å behandle task-kø. Denne kan f.eks. kjøre hvert 10. minutt.

   Importen må:

   • Slå opp persondata i Greg
   • Ut fra resultat, finne ut om dette skal ignoreres eller føre til oppretting, oppdatering, eller avvikling av et personobjekt.
   • Utføre den relevante endringen (se persondata)

3. Opprette brukerkonto.

   En regelmessig jobb kjører gjennom og oppretter brukerkonto til gjester, tilsvarende som ansatt-automatikk.

Import av persondata

Selve import av personinformasjon følger også en stegvis flyt:

1. Oppslag - en klient slår opp personinformasjon i Greg-API (Cerebrum.modules.greg.client)

2. Normalisering - funksjoner for å validere, filtrere og normalisere data (Cerebrum.modules.greg.datasource).

   • Validering — sjekke at API-et ikke returnerer uventede data eller mangler obligatoriske felter.
   • Filtrering - fjerne irrelevante felter.
   • Normalisering - konvertere felter til Python-verdier (f.eks. ISO-datotekst til datetime.date-objekt eller None), sørge for at tekstfelter settes til None hvis de er tomme, eller at det benyttes en gitt unicode-normalform).

3. Oversetting - funksjoner for å hente ut og oversette normaliserte data fra Greg til Cerebrum-data (Cerebrum.modules.greg.mapper). Denne modulen styrer hvordan Cerebrum-data og Greg-data hører sammen. F.eks. at person.identities[type=passport_number] fra Greg er en ekstern identifikator av type PASSNR i Cerebrum, eller at GREG_PID skal hentes fra person.id i Greg.

4. Matching - funksjoner for å finne eksisterende objekter (gjest -> person, orgunit -> ou) i Cerebrum (Cerebrum.modules.import_utils.matcher). Disse funksjonene bruker typisk data fra en mapper-funksjon for å hente ut ekstern-id, og slår opp om det alt finnes et tilhørende objekt i Cerebrum.

4. Oppdatering - funksjoner for å opprette, oppdatere og avvikle gjester i Cerberum (Cerebrum.modules.greg.importer og Cerebrum.modules.import_utils.syncs).

Utplukk

Cerebrum skal kun importere og vedlikeholde personer fra Greg som er gyldig gjest. Dette betyr at vi kun oppretter/oppdaterer person-objekt i Cerebrum dersom Greg kan presentere:

• Minimum en gyldig, aktiv rolle. En gyldig rolle er en rolle som kan mappes til en tilknytningstype i Cerebrum. En aktiv rolle har start_date i fortid og end_date i fremtid.
• registration_completed_date må være satt (og ikke en fremtidig dato).
• Ved oppretting - minimum ett gyldig id-nummer. Aksepterte id-nummer er norwegian_national_id_number og passport_number. For at id-nummeret skal være gyldig, må det være verified (manual eller automatic).
• Person må også ha enkelte samtykker (godta personvern-policy, godta it-reglement), men dette vil ivaretaes i Greg. Det skal ikke være nødvendig for Cerebrum å kontrollere at disse er gitt.

Persondata

Personer fra Greg må oppdateres/vedlikeholdes med:

Fødselsdato

Hentes fra date_of_birth. Settes kun ved oppretting av person.

Kjønn

Finnes ikke i Greg, men er påkrevd i Cerebrum. Kan settes til X (gender_unknown) ved oppretting.

Tilknytning

Regnes ut fra personens roller (roles).

Ekstern ID

Må sette GREG_PID (externalid_greg_pid) fra id. Må sette/oppdatere NO_BIRTHNO og/eller PASSNR fra personens identifikatorer (identities). Ekstern-id fra person.identities må være verified (manual - en sponsor har kontrollert legitimasjon, eller automatic - ekstern-id er blitt automatisk satt fra Feide, ID-porten eller annen integrasjon som vi kan stole på).

Kontaktinfo

Vi må oppdatere PRIVATEMOBILE fra Greg. Mobilnummer hentes fra person.identities[type == private_mobile]. Kontaktinfo krever ikke en verified-verdi.

Samtykke

Vi må oppdatere samtykke til publisering av personinformasjon i katalog-tjenester, consents[].type[identifier == publish]).

I første omgang: Melde inn i gruppe Greg-aktivt-samtykke.

TODO: Hvordan representere samtykker fra eksterne systemer? Vi må finne en bedre løsning som gjør at vi ikke trenger å sjekke tilknytninger, kildesystem og gruppemedlemsskap ved eksport.

Avvikling

Dersom en person ikke lenger er gyldig gjest i Greg, må Greg-relaterte data fjernes i Cerebrum.

Utplukk er ulikt fra oppretting. Person skal avvikles dersom ingen gyldig, aktiv rolle lenger finnes i Greg. Dersom andre kriterier for oppretting (fødselsnummer, passnummer, registration_completed_date) forsvinner, skal vi likevel oppdatere og vedlikeholde persondata, så lenge det finnes en gyldig, aktiv rolle.

Fjerne:

• Tilknytninger fra greg
• Ekstern-id fra greg, bortsett fra GREG_PID.
• Kontaktinfo fra greg
• Samtykker
• Navn (kildesystem GREG, evt. navn fra greg som har blitt brukt i Cached kan beholdes)

Samtykke

Greg har pdd. tre typer samtykke:

• IT-reglement (ikke direkte relevant for Cerebrum - registrering er ikke fullført før dette blir gitt)
• Personvern-policy (ikke direkte relevant for Cerebrum - registrering er ikke fullført før dette blir gitt)
• Publisering av personinformasjon - dette må vi representere og vedlikeholde i Cerebrum, og bry oss om i ulike eksporter.

Vi får enda en samtykke-kilde som må blandes inn med samtykke fra FS og reservasjon fra HR-system.

Brukerkonto

Vi må ha automatisk (gjen-)oppretting av brukerkonto for gjester. Det betyr at:

• Nye personobjekter fra Greg (samt personobjekter som aldri har hatt noen brukerkonto) skal automatisk få opprettet en brukerkonto.
• Eksisterende personer med brukerkonto skal få denne automatisk gjenopprettet, så langt det er mulig (typisk unntak: personer med flere brukerkontoer?)

Forhåndsarbeid

OU-import må utvides til å inkludere og oppdatere ou-id fra OrgReg.

Meldinger og tasks

Meldinger kan mottas, parses og omformes til tasks ved bruk av consumers/consume-tasks.py, i samarbeid med:

Cerebrum.modules.greg.datasource

Modul for konvertering av data fra Greg - her bør det implementeres en funksjon for å parse relevante data fra meldinger i Greg

Cerebrum.modules.greg.tasks

Modul som implementerer/definerer task-køer for Greg. Her bør det implementeres tilsvarende funksjonalitet som i f.eks. Cerebrum.modules.no.dfo.tasks.

Sluttresultatet er en funksjon som kan legges inn i konfigurasjonen til consume-tasks.py, og omforme meldinger til tasks fortløpende.

Import

Cerebrum.modules.greg.mapper

Bør inneholde mapping fra Greg-spesifikke data til Cerebrum-spesifikke data. F.eks. at role.type: "foo" skal bli til TILKNYTTET/foo i Cerebrum, og at norwegian_national_id_number er NO_BIRTHNO i Cerebrum.

Cerebrum.modules.greg.importer

Funksjonalitet som tar informasjon, ferdig pre-prosessert fra mapper, og skriver dette til Cerebrum.

Automatisk oppretting av brukerkonto

TODO