Spesifikasjon for integrasjon mellom Cerebrum og ePhorte

Spesifikasjon av integrasjonen mellom Cerebrum og ePhorte.

1   Introduksjon

Dette dokumentet beskriver integrasjon og dataflyt mellom Cerebrum og ePhorte.

Oppdatering av ePhorte skjer i tre trinn:

  1. Innlasting og oppdatering av person-, organisasjon- og tilknytningsinformasjon for ansatte, tilknyttede og gjester fra SAPUiO til Cerebrum.
  2. Populering av ephorte-roller og -tilgangskoder i Cerebrum.
  3. Synkronisering av informasjon om personer, roller, tilgangskoder og stedstilhørighet fra Cerebrum til ePhorte.

Dette dokumentet tar for seg punkt 2 og 3.

1.1   Datakilder

Ephorte får all informasjonen fra Cerebrum, men person-, organisasjon- og tilknytningsinformasjon stammer fra SAPUiO. Ephorte-roller og -tilgangskoder blir populert direkte i Cerebrum. En oversikt over dataflyten:

                                                      populering
                                                      av ePhorte-roller,
                                                      -tilgangskoder og
                                                      tildeling av
                                                      spread til ePhorte
                                                   +--------------------+
                                                   |                    |
+--------+                                   +----------+               |
|        |                                   |          |               |
|        |  persondata (navn, kontaktinfo)   |          |<--------------+
|  SAP   |---------------------------------->| Cerebrum |
|        |                                   |          |
|        |                                   |          |
+--------+                                   +----------+
                                                   |
                                                   |
            +---------+   Cerebrum-Ephorte synk.   |
            |         |<---------------------------+
            | Ephorte |
            |    WS   |
            |         |
            |         |
            +---------+
                 |                      +---------+
                 |  person- og          |         |
                 |  rolleoverføring     |         |
                 +--------------------->| ePhorte |
                                        |         |
                                        |         |
                                        +---------+

2   Begreper

Autoritativ kilde
En autoritativ kilde for en gitt type data regnes for å være mest pålitelig kilden for denne informasjonen. F.eks er SAPUiO autoritativ kilde for personnavn ved UiO.
SAPUiO
Autoritativ kilde for data om tilsatte, tilknyttede, gjester og steder ved UiO.
Cerebrum
System for identitetsforvaltning og integrasjon. Formidler blant annet informasjon fra FS og SAPUiO til andre systemer ved UiO.
ePhorte
Noark-basert saksbehandlings- og arkivsystem ved UiO.
Sted/stedkode/OU
Det er ved UiO definert en rekke steder, også kalt OU (Organisation Unit), som er ordnet som et hierarki med stedet 'UiO' på toppen. Hvert sted har blant annet et navn og stedkode.
Synkronisering
Overføring av data fra et system til et annet, i dette tilfellet fra Cerebrum til ePhorte.
Webservice
System for å sende informasjon fra en maskin til en annen over et nettverk. Bruker som regel SOAP-standarden og sender data i XML-format.
ePhorte-rolle
Personer i ePhorte kan ha en eller flere roller. En rolle er av en bestemt rolletype som avgjør hva slags operasjoner en person kan utføre i ePhorte, se Roller. En rolle gjelder kun et gitt sted og i et gitt arkiv.
ePhorte-tilgangskode
Personer i ePhorte kan ha en eller flere tilgangskoder. En tilgangskode avgjør hva slags type saker man har tilgang til og er begrenset til et sted. Det er mulig å angi at det skal være tilgang til kun egne saker av gitt type. Det er også mulig å angi tilgang til hele UiO for en gitt type saker.

2.1   Populering av ephorte-spesifikk informasjon i Cerebrum

Det er definert en egen spread, ePhorte_person, som styrer hvilke personer som blir synkronisert til Ephorte. Alle personer som har en eller flere roller får ephorte-spread. Hvis en person mister en ephorte-rolle og ikke har flere roller, fjernes også ephorte-spread.

Roller kan bli gitt til personer enten automatisk eller manuelt i bofh. Om en rolle er tildelt manuelt eller automatisk blir merket som 'T' elller 'F' i kolonnen auto_role i ephorte_role.

Alle personer får automatisk rollen SB (saksbehandler).

Tilgangskodene for «Under arbeid», AR og UA (utgått) blir tildelt av automatikken. Tilgangskodene tilordnes til stedkoden for egne saker (999999 i Cerebrum). Det kan ikke gis tilgangskoder til en person som ikke har ephorte-spread, dvs en person som ikke har minst en ephorte-rolle.

Det vil antageligvis også bli aktuelt å synkronisere stedsdata, men dette gjøres ikke nå fordi ephortes web service ikke støtter oppdatering av steder. Slik det er nå oppdateres steder manuelt i ephorte-applikasjonen. Cerebrum henter denne stedinformasjonen og sammneligner med stedsinformasjonen fra SAPUiO. Uoverenstemmelser blir logget og automatisk varslet.

2.1.1   Automatisk populering av roller

Alle ansatte skal ha en saksbehandlerrolle i ePhorte. Dette populeres automatisk ved at alle som har ANSATT-tilknytning fra SAP får saksbehandlerrolle knyttet til stedet de er ansatt.

2.1.2   Manuell tildeling av roller

Manuell tildeling og manipulering av roller gjøres i bofh med kommandoene:

  • ephorte add_role
  • ephorte list_roles
  • ephorte remove_role

Det er kun superbruker og de som er med i gruppen ephorte-admins som har tilgang til disse kommandoene.

2.1.3   Manuell tildeling av tilgangskoder

Manuell tildeling og manipulering av tilgangskoder gjøres i bofh med kommandoene:

  • ephorte add_perm
  • ephorte list_perm
  • ephorte remove_perm

Bofh-koden er definert i cerebrum/Cerebrum/modules/no/uio/bofhd_ephorte_cmds.py.

3   Data som skal overføres

Det skal overføres informasjon om personer, roller, samt steder disse rollene er knyttet til. Kriteriene for hvilke personer, roller og steder som blir synkronisert er gitt i Synkronisering.

3.1   Persondata

Persondataene som blir overført er følgende:

first name

Kommer fra SAPUiO.

Cerebrum: hentes med Person.getdict_persons_names, dvs fra person_name, der source_system=co.system_cached og name_variant=co.name_first.

last name

Kommer fra SAPUiO.

Cerebrum: hentes med Person.getdict_persons_names, dvs fra person_name, der source_system=co.system_cached og name_variant=co.name_last.

full name

Kommer fra SAPUiO.

Cerebrum: hentes med Person.getdict_persons_names, dvs fra person_name, der source_system=co.system_cached og name_variant=co.name_last.

initials
Brukernavn til personens primærbruker. Kommer fra Cerebrum.
feide_id
initials + '@uio.no' Genereres ved overføring.
email
Personens primary_email_address. Kommer fra Cerebrum.
address

adress_text, p_o_box, postal_nr, city. Kommer fra SAPUiO.

Cerebrum: hentes med Person.list_entity_addresses, der entity_type=co.entity_person, source_system=co.system_sap og address_type=co.address_street.

phone

Kommer fra SAPUiO.

Cerebrum: hentes med Person.list_contact_info, der source_system=co.system_sap og contact_type=co.contact_phone.

3.2   Roller

ePhorte-roller i Cerebrum har følgende data som blir synkronisert:

role_type

Det er per dd åtte forskjellige rolletyper i ePhorte:

  • AR1, Arkivansvarlig
  • AR2, Arkivar
  • AR3, eSak
  • LD, Leder/saksfordeler
  • LD LES, Leserolle Leder
  • SY, Systemansvarlig
  • SB, Saksbehandler
  • MAL, Malansvarlig
  • SUB, Superbruker
standard_role

Kan ha to verdier, 'T' og 'F', som står for True og False. Verdiene blir mappet til '-1' '0' av web-servicen og avgjør om rollen skal settes som standard_rolle eller ikke i ePhorte.

TODO: beskriv hva som skal skje med standard-rolle ved opprettelse av nye personroller, sletting, etc.

adm_enhet
stedet rollen er knyttet til, gitt som stedkode.
arkivdel

Følgende arkivdeler er definert:

  • SAK UIO, Saksarkiv ved Universitetet i Oslo
  • STUD UIO, Studentarkiv ved Universitetet i Oslo
  • EIEND UIO, Eiendomsarkiv ved Universitetet i Oslo
  • AVTALE UIO, Avtalearkiv ved Universitetet i Oslo
  • SAK SO, Saksarkiv ved Samordna Opptak
  • SAK NIKK, Saksarkiv ved NIKK
  • PERS UIO, Personalarkiv ved Universitetet i Oslo
  • KHM FORN, KHM (Kulturhistorisk museum) - Fornminnneforvaltning
  • SAK FSAT, sakarkivet ved FSAT
  • CRISTIN, Current Research System in Norway
  • FELLESKLAG, Felles klagenemnd
  • FS, Felles studentsystem
  • KHM OBJEKT, Gjenstander og objekter ved Kulturhistorisk museum
  • KLAGE SO, Klager på opptak ved Samordna opptak
  • KLAGENEM, Klagenemnder Samordna opptak
  • NASJONKLAG, Nasjonal klagenemnd
  • NI, Nasjonal institusjon for menneskerettigheter
  • NORDEM, The Norwegian Resource Bank for Democracy and Human Rights
  • OMBUDSTUD, Studentombud
  • ROMANI, Tater- / Romaniutvalget
  • UIO ENERGI, UiO Energi

eSak kan be om å få opprettet nye arkivdeler ved behov.

Fra Cerebrums ståsted er en arkivdel og et arkiv det samme. fra eSAKs ståsted er det en forskjell. Se Arkivverkets arkivterminologi for utfyllende forklaring om begrepene.

journalenhet

Følgende journalenheter er definert:

  • J-NIKK, Journalenhet for NIKK - Nordisk institutt for kvinne- og kjønnsforskning
  • J-SO, Journalenhet for SO - Samordna Opptak
  • J-UIO, Journalenhet for UiO - Universitetet i Oslo
  • J-FSAT, Journalenhet for FSAT
  • J-SMR, Journalenhet Norsk senter for menneskerettigheter
  • J-OMB, Journalenhet for studentombud
rolletittel
brukes ikke, sender ""
stilling
urukes ikke, sender ""

3.3   Tilgangskoder

ePhorte-tilgangskoder i Cerebrum har følgende data som blir synkronisert:

perm_type

Følgende tilgangskoder er definert i ePhorte. Av disse er noen utgått, men de må fortsatt være registrert i Cerebrum og ePhorte. De gjeldende tilgangskodene er:

  • US, Unntatt etter offentlighetsloven ved SO
  • UN, Unntatt etter offentlighetsloven ved NIKK
  • PR, Rettssaker
  • PV, Personalsaker
  • PD, Disiplinærsaker personal
  • PO, Personers økonomiske forhold
  • AR, Under arbeid
  • OF, Unntatt etter offentlighetsloven
  • SV, Studentsaker
  • SD, Disiplinærsaker studenter
  • FO, Forskningssaker
  • AI, Anskaffelser
  • VS, Varsling studenter
  • VA, Varsling ansatte
  • OS, Studentombud

De utgåtte tilgangskodene er:

  • UO, Unntatt etter offentlighetsloven
  • P , Personalsaker
  • P2, Personers økonomiske forhold
  • P3, Disiplinærsaker personal
  • P4, Rettssaker
  • S , Studentsaker
  • S2, Disiplinærsaker studenter
  • UA, Under arbeid
  • PA, Personalsaker AKAN

Ikke alle disse brukes av arkiv-personalet, men det er ikke vesentlig for synkroniseringen.

adm_enhet
stedet rollen er knyttet til, gitt som stedkode.
requestee
Den som har gitt tilgangskode til personen, angitt ved initials.

3.4   Steder

Stedsdata skal ikke synkroniseres. Synkronisering av roller og tilganger baserer seg på at stedene gjenkjennes i ePhorte med stedkode.

4   Synkronisering

Det skal overføres informasjon om alle personer som har en eller flere ephorte-roller i Cerebrum. I tillegg overføres det informasjon om roller, tilgangskoder og stedene de er tilknyttet.

Hvilke personer som skal synkroniseres styres av ephorte-spread (spread_ephorte_person).

4.1   Registrering av ephorte-roller i Cerebrum

Roller i ePhorte kan tildeles på tre måter:

  • Saksbehandler, tildeles automatisk basert på tilsetting.
  • Systemadministrator, tildeles automatisk på bakgrunn av medlemskap i gruppen 'ephorte-admins' i Cerebrum.
  • Manuell registrering av roller i Cerebrum (alle typer).

4.1.1   Saksbehandler

Alle personer med en ansatttilknytning ved UiO får automatisk tildelt standard saksbehandlerrolle (SB) i UiOs arkiv i ePhorte, 'SAK UIO'.

På samme måte får alle personer tilknyttet enhetene NIKK (stedkode 390920) og SO (stedkoder 332520 og 3905**) standard arkivrolle i sine respektive arkiv, 'SAK NIKK' og 'SAK SO'.

Saksbehandlerrollen tildeles for alle stedene som en person har ansattilknytning til dersom stedet kan mappes til et ephorte-sted, se Rollers stedstilknytning.

Når stillingen i SAPUiO som danner grunnlag for tilknytningene registrert i Cerebrum opphører, fjernes saksbehandlerrollen.

4.1.2   Systemadministrator

Hvis en bruker er meldt inn i gruppen 'ephorte-admins' i Cerebrum vil denne få systemadministratorrolle i ePhorte. Medlemmene i denne gruppen skal ha:

  • rollen "SY"
  • admindel "UIO" (sko 900199)
  • arkivdel "SAK UIO"
  • journalenhet "J-UIO"

Det skal foreløbig ikke lages egne admin-grupper for systemadministratorer ved NIKK og SO.

Merk at utmelding fra gruppen i Cerebrum ikke fører til at systemadministratorrollen ugyldiggjøres i ePhorte. Rollen må fjernes manuelt i bofh av en systemadministrator for ePhorte. Systemadministratorroller kan også gis i bofh av en som allerede er systemadministrator.

Cerebrum: Merk at medlemmene i ephorte-admins er brukere i Cerebrum, mens det i ePhorte er personer (brukerens eier) som er systemadministator. Det kompliseres ytterligere ved at personer i ePhorte representeres av personens primærbruker fra Cerebrum.

4.1.3   Manuell registrering av roller i Cerebrum

Det er også mulig å gi, liste og fjerne roller manuelt i Cerebrum via bofh med kommandoene:

  • ephorte add_role
  • ephorte list_roles
  • ephorte remove_role
  • ephorte set_standard_role

Dette gjelder alle typer ephorte-roller. Merk at disse kommandoene er kun tilgjengelige for brukerreg og systemadministrator for ephorte.

4.2   Registrering av ephorte-tilgangskoder i Cerebrum

Tilgangskoder avgjør hva slags type saker en person har tilgang til. En ephorte-systemadministrator kan gi, fjerne og liste tilgangskoder i bofh med kommandoene:

  • ephorte add_perm
  • ephorte list_perm
  • ephorte remove_perm

Merk at tilgangskoder kun kan bli gitt personer som har en eller flere roller i ePhorte. Det gir ingen mening å tildele tilgangskoder til perosner som ikke finnes i ephorte.

4.3   Synkronisering av personer

Det skal overføres informasjon om alle personer som har registrert en eller flere ephorte-roller i Cerebrum. Hva som skjer i synkroniseringen avhenger av om personinformasjonen i Cerebrum har blitt endret, og om personen er registrert i ePhorte fra før.

Cerebrum: rent teknisk styres hvilke personer som skal synkroniseres med en egen ephorte-spread, spread_ephorte_person. Hvis en person blir tildelt en ephorte-rolle og personen ikke har ephorte-spread fra før blir ephorte-spread gitt automatisk. Hvis en person mister alle sine ephorte-roller, blir ephorte-spread automatisk fjernet.

4.3.1   Hva vil det si at en person finnes i ePhorte?

Før det kan avgjøres om en person skal oppdateres eller opprettes må det sjekkes om en person finnes i ePhorte fra før. Dette er ikke helt trivielt, fordi det som i ePhorte er en person er i Cerebrum personens primærbruker, og denne kan bli endret hvis en person har flere brukere i Cerebrum.

Vi sier at en person med gitt feide_id (se Persondata) fra Cerebrum finnes i ePhorte hvis det er en person i ePhorte hvis PERSON.PE_BRUKERID er identisk med feide_id fra Cerebrum.

Det kan forekomme at personer skifter feide-id. Isåfall opprettes ny person i ePhorte.

4.3.2   Oppdatering av person i ePhorte

Hvis en person i dumpen fra Cerebrum ikke finnes i ePhorte fra før, skal det opprettes en ny person i ePhorte. I tillegg lagres navn, adresse, og roller i egne tabeller.

Hvis en person i dumpen fra Cerebrum finnes i ePhorte fra før, og enten navn-, adresseinformasjon eller roller er forskjellig vil disse persondataene bli oppdatert i ePhorte.

4.3.3   "Sletting" av person i ePhorte

Hvis en person tidligere har hatt en eller flere roller i ePhorte og disse har blitt fjernet i Cerebrum skal personen registreres som inaktiv i ePhorte ved neste synkronisering. Personen vil da ikke lenger ha tilgang i ePhorte.

4.4   Synkronisering av roller

Rolledataene for hver person fra Cerebrum sammenlignes med rollene som finnes for den personen i ePhorte fra før. Roller identifieres med følgende tuppel:

(role_type, adm_enhet, arkivdel, journalenhet)

Hvis dette tuplet er likt for to roller, er rollene identiske.

Hvis en rolle fra Cerebrum ikke finnes i ePhorte skal denne opprettes. Hvis det for en person finnes en rolle i ePhorte som ikke er med i dumpen fra Cerebrum skal denne rollen slettes i ePhorte. En rolle markeres som slettet ved at dens tildato blir satt.

4.4.1   Rollers stedstilknytning

Fra SAPUiO får Cerebrum informasjon om i overkant av 600 steder (heretter kalt "uio-steder"). Stedene er ordnet i et hierarki, hvor UiO er øverste node, med fakulteter, Institutter, osv nedover i hierkiet.

I ePhorte er det definert ca 200 steder i universitetets stedstruktur som er relevante i ePhorte-sammenheng (heretter kalt "ephorte-steder"). Dette er et subsett av uio-steder og vedlikeholdes av SAPUiO i samarbeid med eSak. Disse er merket i SAPUiO med stedtype=Arkivsted.

Det er inntil videre ingen synkronisering av steder fra Cerebrum til ephorte. Dette skyldes at denne informasjonen ikke kan oppdateres vie ephortes web-service. Dermed vedlikeholdes stedene manuelt i ePhorte. Internt i ePhorte er det lagret i tabellen ADMINDEL. Synkroniseringen sjekker at det ikke er avvik mellom stedene registrert i ephorte og SAPUiO.

En rolle skal knyttes til et sted i ephorte-steder, basert på stedet personen har ansatttilknytning til. Dersom stedet personen er knyttet til ikke finnes i ephorte-steder, forsøker man å tildele rollen ved overordnet enhet i uio-steder. Hvis heller ikke dette stedet er med i ephorte-steder skal det logges en feilmelding. Feil av denne typen skal regelmessig sendes e-post-listen 'esak-hjelp@admin.uio.no'.

4.5   Synkronisering av tilgangskoder

Tilgangskodedataene for hver person fra Cerebrum sammenlignes med tilgangskodene som finnes for den personen i ePhorte fra før. Tilgangskoder identifieres med følgende tuppel:

(perm_type, adm_enhet)

Hvis dette tuplet er likt for to tilgangskoder, er tilgangskodene identiske.

Hvis en tilgangskode fra Cerebrum ikke finnes i ePhorte skal denne opprettes. Hvis det for en person finnes en tilgangskode i ePhorte som ikke er i Cerebrum, skal denne tilgangskoden slettes i ePhorte.

4.5.1   Tilgangskoders stedstilknytning

Tilgangskoder er knyttet til steder. I motsetning til rollers stedtilknytning må tilgangskoder være knyttet direkte til et ephorte-sted.

Merk at det er opprettet noen fiktive stedkoder i Cerebrum, som bare brukes i forbindelse med populering av stedkoder i ePhorte:

  • 999991, Ephorte, ufordelte saker - brukes som sted for ufordelte saker
  • 999999, Ephorte, egne saker - brukes for å angi at en tilgangskode kun gjelder for egne saker

I tillegg har også stedkoden 900199 en spesielt rolle, då den er toppnoden for UiO og brukes for å dekke hele UiO.

4.6   Tilgang til ePhorte

Tilgang til bruk av ePhorte er begrenset. Det er to kriterier som må tilfredsstilles for at en person kan benytte ePhorte:

  • Personen må ha FEIDE-tilgang
  • Personen må minst en ephorte-rolle registrert i Cerebrum.

Hvem som blir tildelt ephorte-roller i Cerebrum er beskrevet i Registrering av ephorte-roller i Cerebrum.

5   Bugs, mangler og ting som burde fikses

  • populering av ephorte-spread og roller må kikkes på. Det ser ut til at det ikke spread alltid fjernes når det burde, noe som resulterer i at litt flere personer enn det som er riktig eksporteres til ephorte.

  • Sletting av roller foregår ved å slette rollen i bofh med kommandoen "ephorte remove_role". Rollen blir da slettet i Cerebrum og ved neste synk så vil rollen slettes i ePhorte. Måten vi sletter på i ePhorte styres av vår ePhorte-modul som kobler seg til ePhortes web-service.

    Tidligere ble sletting av roller utført ved å slette databaseoppføringen rått og brutalt. I ePhorte ser man dette ved at rollen forsvinner fra listen over roller en person har. En ulempe med denne metoden er at vi ikke har noen historikk (som vi kjenner til) over hvilke roller en gitt person har hatt.

    For å kunne beholde noe historikk bestemte vi oss for å slette roller på en annen måte, nemlig ved å sette en tildato, slik at en slettet rolle er synlig i ePhorte ved at man har en periode (startdato og tildato) som denne rollen gjaldt.

    Desverre har det vist seg at denne metoden har noen uheldige konsekvenser:

    • Hvis man har slettet en rolle for en person og man senere forsøker å opprette samme rolle (samme person, rolletype og sted) så vil ikke det fungere siden ePhorte mener rollen finnes fra før.

      Dette kan fikses ved å sette tom verdi i tildato-feltet. Går det an å gjøre via syncen?

    • Hvis en person har flere roller, og den av de som er standardrolle blir slettet, så vil ikke personen kunne logge inn i ePhorte. Det er fordi standardrollen må være et gyldig valg ved innloggingen, noe den ikke er når tildato er i fortiden.

      Dette problemet kan løses ved å legge til en sperre i bofh slik at det ikke går an å slette en rolle som er standardrolle.

    • Det kan også være andre ting vi ikke har oppdaget.

  • Hvis en person har flere roller og det endres hvem av dem som er standardrolle, men ikke noe annet blir endret så blir ikke ephorte oppdatert. Dette er en bug.

  • Fornavn kan ikke være lengre enn 30 tegn i ePhorte. Dette må vi klage på.

  • Skal vi vise slettede roller (med tildato) i ephorte_list_roles?

  • Det viser seg at det for mange personer er flere uavhengige brukere i ephorte. Finn hvor mange, hvordan dette har skjedd, og hva som kan gjøres med dette.

    ~@cerebellum > /cerebrum/bin/sync_ephorte.sh /tmp/ -p /cerebrum/etc/passwords/ephorte-conn-prod.props -d person -t Person | cut -d ";" -f 4 | grep "@UIO.NO" > /tmp/ephorte_prod_person_dump.dat ~@cerebellum > python src/uiocerebrum/hacks/find_ephorte_person_duplicates.py /tmp/ephorte_prod_person_dump.dat Fant 12147 brukere 69 personer har to eller flere brukere i ephorte: p_id 131509, brukere: ['margit', 'annmarn'] p_id 754562, brukere: ['mehwiss', 'mehwissi'] p_id 197568, brukere: ['torebul', 'torekb'] ...

  • Det er mange personer med ephorte-spread som ikke (lenger) har ansatt-aff. Kan vi få til en automatisk opprydding av dette? Bruk cerebrum/contrib/no/uio/list_ephorte_info.py for å sjekke dette.

Av jsama
Publisert 27. apr. 2015 12:12
Del på e-post