Ny Cristin-eksport

Dagens løsning

Det finnes i dag to eksporter som eksporterer til Cristin. Begge eksportene dumper «alt» via en XML-fil definert i http://www.cristin.no/institusjonsdata/

Denne dumpen inneholder:

  • Organisasjonsdata (OU-struktur med sekssifrede stedkoder)
  • Persondata
    • ansettelsesforhold
    • gjesteroller (e.g. emeritus)

Alle rollene angis med stedkode i OU-treet.

Ny løsning

En ny løsning bør være basert på rest-baserte WS'er, og meldingskøer. Det er flere mulige designvalg, men dette dokumentet fokuserer på to alternativer:

  • Cerebrum rest-grensesnitt + meldinger
  • Cristin WS og push fra Cerebrum

Begge disse alternativer bør uansett kombineres med jevnlig (f.eks. ukentlig) fullsync, slik at ev. feil ikke blir hengende. I tillegg vil institusjonsdata ikke være en del av disse to forslagene; disse vil uansett ikke endres fra dag til dag.

Et problem som må løses er hvilke personer som skal med til Cristin. I begge tilfellene beskrevet i dokumentet, må prosessen som leser Cerebrum-rest kunne avgjøre om personen skal ignoreres. En mulighet er kanskje bruk av eget Cristin-spread, som settes automatisk ved import fra HR-system, men som kan justeres manuelt på mere problematiske tilfeller.

En tredje mulighet hadde vært om Cristin selv snakket direkte med HR-system, men det er ikke vurdert i dokumentet.

Cerebrum rest

Dette alternativet avhenger av at Cristin kan lytte på meldinger fra en meldingskø. Cerebrum sender meldinger via RabbitMQ, hvor meldingene i et SCIM/JWT-format angir hva som er endret. Cristin vil lese meldingene og oppdatere seg mot et rest-grensesnitt.

Format på meldingene er dokumentert annetsteds TODO: sett inn lenke til dette når dokumentet er ferdig. Meldingene følger stort sett SCIM notify draft standard (https://tools.ietf.org/id/draft-hunt-scim-notify-00.txt), men ikke alle attributtnavn passer med Cerebrum.

Dette dokumentet beskriver Cerebrums REST-grensesnitt slik det ser ut i dag. Det kan dog også være heldig om vi får et tre med SCIM-struktur, siden SCIM er en standard in spe på området. Det må dog vurderes hva som skal til for å oppnå dette, spesielt siden Cerebrums datamodell ikke helt dekkes av SCIM. (http://www.simplecloud.info/specs/draft-scim-api-01.html).

OU-data

OU-struktur endres sjelden. Cristin har mange attributter på OU som ikke kommer til å endres:

  • nøkkel (institusjon, avdeling, underavd, gruppe) (Kan teknisk sett endres i Cerebrum-API, men dette er nøkkelen)
  • enhetErstattesAv
  • land
  • Dato (brukes ikke av Cerebrum)

For resten vil Cerebrum sende en endringsmelding. Disse vil ha en url som peker på en OU (slutter på «ous/$id», hvor $id er et tall som Cerebrum bruker som nøkkel).

Øvrige:

  • Ovenliggende sted. Vil generere en endringsmelding på OU med attributt «parent».
  • Navn og akronym. Endringsmelding med attributt «name»
  • postadresse, postnr, poststed, [land]. Endringsmelding, attributt «address».
  • telefonnr: Attributt «phone», «cellPhone» eller «privatePhone»
  • fax: Attributt «fax».
  • mail: Attributt «externalMail» eller «mail».
  • URL: Attributt «url».
  • NSD-kode: Ingen melding. Bør ikke forekomme.

Tjenesten går til REST-URL, og vil der finne alle attributtene som er interessante.

Cerebrum rest returnerer et JSON-objekt med bl.a.

  • «institusjon», «fakultet», «institutt», «avdeling» mappes til Cristins nøkkel (i rekkefølge).

  • «names» er en array med navn, kodet med sprog og type:

    • «variant» angir type navn: En av «OU name», «OU acronym», «OU short», «OU long» og «OU display»
    • «language»: sprog som navn finnes på.
    • «name» angir selve navnet.

    Her kan navn settes fra navn, long, display eller short (første som finnes), og akronym fra acronym. En gjennomtenkt algoritme som rangerer navnevariantene på både sprog og variant er antageligvis unødvendig, da det nesten garantert finnes et foretrukket førstevalg. Jeg foreslår å sortere på sprog først, så på type, og ta det første.

  • «contact» angir en array med kontaktinfo:

    • «value» telefonnummer etc. basert på typen
    • «type» er bl.a. «PHONE», «FAX», «EMAIL», «MOBILE» og «URL» (øvrige bør ignoreres)
    • Øvrige er «alias», «preference», «entity_id», «description» og «source_system». Kan ses bort ifra.

    første kontaktopplysning bør benyttes.

Per dags dato er postadresse ikke returnert.

Eksempel på objekt:

{
  "fakultet": 33,
  "avdeling": 0,
  "contexts": [],
  "href": "/v1/ous/567",
  "contact": [
    {
      "entity_id": 567,
      "description": null,
      "source_system": "SAP",
      "value": "postmottak@usit.uio.no",
      "alias": null,
      "preference": 0,
      "type": "EMAIL"
    },
    {
      "entity_id": 567,
      "description": null,
      "source_system": "SAP",
      "value": "22852730",
      "alias": null,
      "preference": 0,
      "type": "FAX"
    },
    {
      "entity_id": 567,
      "description": null,
      "source_system": "SAP",
      "value": "http://www.usit.uio.no/",
      "alias": null,
      "preference": 0,
      "type": "URL"
    },
    {
      "entity_id": 567,
      "description": null,
      "source_system": "SAP",
      "value": "22852470",
      "alias": null,
      "preference": 1,
      "type": "PHONE"
    }
  ],
  "names": [
    {
      "variant": "OU acronym",
      "name": "USIT",
      "language": "nb"
    },
    {
      "variant": "OU display",
      "name": "Universitetets senter for informasjonsteknologi",
      "language": "nb"
    },
    {
      "variant": "OU name",
      "name": "Universitetets senter for informasjonsteknologi",
      "language": "nb"
    },
    {
      "variant": "OU short",
      "name": "USIT",
      "language": "nb"
    },
    {
      "variant": "OU acronym",
      "name": "USIT",
      "language": "en"
    },
    {
      "variant": "OU short",
      "name": "USIT",
      "language": "en"
    },
    {
      "variant": "OU name",
      "name": "Centre for Information Technology Services",
      "language": "en"
    },
    {
      "variant": "OU display",
      "name": "Centre for Information Technology Services",
      "language": "en"
    }
  ],
  "institutt": 0,
  "stedkode": "330000",
  "id": 567
}

Personopplysninger

Cristin trenger også en del personopplysninger. Cristin bruker fødselsnummer som nøkkel for persondata, og skulle fødselsnummeret endres, må dette overføres. En melding som angir fødselsnummer i listen over endrede attributter, blir mottatt. TODO: Hvordan skal man kunne slå opp tidligere fnr?

Andre personopplysninger

  • etternavn (endret attributt «name» i melding)
  • fornavn (endret attributt «name» i melding)
  • adresse (attributt «address»)
  • telefonnr (attributt «phone», «cellPhone» eller «privatePhone»)
  • telefaxnr (attributt «fax»)
  • epost (attributt «email» på konto, ev. «externalMail»)
  • URL (attributt «url»)
  • personligTittel (attributt «title»)

For å hente ut disse verdiene, må man bruke Rest-kall. URL i melding gir et objekt med bl.a. disse feltene:

birth_date:

Fødselsdato

names:

Liste over navn, som er objekter med feltene

  • source_system (kildesystem)
  • variant (FIRST, LAST, FULL, PERSONALTITLE eller WORKTITLE)
  • name Selve navnet

Cristin bør her plukke FIRST og LAST med source_system = «Cashed», samt PERSONALTITLE hvis det finnes

De øvrige feltene Cristin trenger (postadresse foreløpig unntatt), hentes ved flere rest-kall (føy til nytt stielement i URL):

/contacts:

Gir et objekt med ett element: «contacts». Denne er en liste over kontaktinfoelementer, som er identiske med OU sine. Brukes til å sette telefonnumre og URL. Ekstern epost kan også være registrert i listen, men det anbefales å benytte primærkontoens e-post, hvis noen.

/external-ids:

Gir en liste over eksterne ID'er, som inneholder både fødselsnumre og ansattnumre. Cristin bruker i dag fødselsnumre, og bør da hente verdien med source_system satt til gjeldende HR-system. Listen inneholder objekter med

  • source_system (kildesystem)
  • type (bl.a. NO_BIRTHNO og NO_SAPNO (gitt SAP som HR-system) for hhv. fødselsnummer og ansattnummer)
  • id (selve ID'en)

Eksempel på persons/id:

{
  "birth_date": "1970-01-01T00:00:00",
  "contexts": [
    "LDAP_person",
    "UA@uio",
    "ePhorte_person",
    "CIM_person"
  ],
  "href": "/v1/persons/85073",
  "id": 85073,
  "names": [
    {
      "source_system": "Cached",
      "variant": "FIRST",
      "name": "Tor"
    },
    {
      "source_system": "SAP",
      "variant": "FIRST",
      "name": "Tor"
    },
    {
      "source_system": "Cached",
      "variant": "FULL",
      "name": "Tor Test"
    },
    {
      "source_system": "Cached",
      "variant": "LAST",
      "name": "Test"
    },
    {
      "source_system": "SAP",
      "variant": "LAST",
      "name": "Test"
    }
  ]
}

Eksempel på persons/id/contacts:

{
  "contacts": [
    {
      "entity_id": 85073,
      "description": null,
      "source_system": "SAP",
      "value": "+4722859999",
      "alias": null,
      "preference": 0,
      "type": "PHONE"
    },
    {
      "entity_id": 85073,
      "description": null,
      "source_system": "example.com",
      "value": "http://example.com/tortest/",
      "alias": null,
      "preference": 1,
      "type": "URL"
    },
    {
      "entity_id": 85073,
      "description": null,
      "source_system": "SAP",
      "value": "99999999",
      "alias": null,
      "preference": 1,
      "type": "MOBILE"
    },
    {
      "entity_id": 85073,
      "description": null,
      "source_system": "VOIP",
      "value": "+4722859999",
      "alias": "59999",
      "preference": 1,
      "type": "EXTENSION"
    },
  ]
}

Eksempel på persons/id/external-ids:

{
  "external_ids": [
    {
      "source_system": "SAP",
      "type": "NO_BIRTHNO",
      "id": "01017099999"
    },
    {
      "source_system": "SAP",
      "type": "NO_SAPNO",
      "id": "999999"
    }
  ]
}

brukernavn

Brukernavn kan medføre ekstra vansker. Cerebrum har et konsept primærbruker. Den brukeren, som til enhver tid er primærbruker, definerer brukernavnet i Cristin. Denne kan endres ved endringer på konto:

  • Create eller delete
  • account_type-endringer

Ved noen av disse, anbefales det å gå inn i API, for så å sjekke primærbruker til eier av konto.

TODO: Dette er/vil være noe flere abonnenter har bruk for; kan man bygge inn i Cerebrum?

Hvis man allerede har URL til personobjektet i REST, kan brukernavn hentes ved å føye til /accounts. Dette gir et objekt med attributtet «accounts», som er en liste med objekter. Se efter objektet med primary-attributtet satt til true. Her er brukernavnet id.

For å finne e-post-adressen, går man til URL angitt ved href på primærkontoen. Her er e-postadressen gitt ved attributtet primary_email.

Har man fått en lenke til en konto i meldingen, kan man finne eier ved attributtet owner. Vi er kun interessert hvis owner.type = person.

Eksempel på persons/id/accounts:

{
  "accounts": [
    {
      "href": "/v1/accounts/torte",
      "id": "torte",
      "primary": true
    },
    {
      "href": "/v1/accounts/torte2",
      "id": "torte2",
      "primary": false
    }
  ]
}

Eksempel på accounts/brukernavn:

{
  "create_date": "1970-01-01T00:00:00",
  "name": "torte",
  "contexts": [
    "NIS_user@ifi",
    "AD_account",
    "NIS_user@uio",
    "exchange_acc@uio"
  ],
  "owner": {
    "href": "/v1/persons/85073",
    "type": "person",
    "id": 85073
  },
  "href": "/v1/accounts/839022",
  "primary_email": "torte@usit.uio.no",
  "expire_date": null,
  "active": true,
  "id": 839022
}

Tilknytninger

Cristin trenger informasjon om hvordan en person er tilknyttet (eller om han ikke lenger er det). Dette kommer fra endringer i affiliations, altså atributt «affiliation» på personen.

Cristin vil trenge informasjon om hvorvidt en person er ansatt eller emeritus.

En stilling inneholder:

  • institusjonsnummer, avdnr, undavdrn, gruppenr (nøkkel til OU)
  • stillingskode
  • datoFra
  • datoTil (ikke obligatorisk)
  • stillingsbetegnelse (avledes normalt av stillingskode)
  • stillingsandel (prosenttall, desimaltall)

En gjestetilknytning bruker «gjestebetegnelse» heller enn attributtene som begynner med «stilling».

Mapping av Cristin-felter til Cerebrum rest:

  • nøkkel finnes ved å slå opp lenke til URL
  • stillingskode og stillingsandel lagres ikke i Cerebrum i dag. (UiO-eksporten leser inn SAP-filen for å finne dette)
  • stillingsbetegnelse lagres som stillingstittel.
  • datoFra kan bruke create_date. (Men denne vil ikke ta hensyn til stillingens egentlige startdato, men når man ble knyttet til angitte OUmed angitte status.)

Eksempel på utlisting:

{
  "affiliations": [
    {
      "status": "ANSATT/tekadm",
      "create_date": "2016-01-01T00:00:00",
      "source_system": "SAP",
      "affiliation": "ANSATT",
      "last_date": "2016-10-14T00:00:00",
      "ou": {
        "href": "/v1/ous/2926742",
        "id": 2926742
      },
      "deleted_date": null
    }
  ]
}

Mangler i Cerebrum i dag

Cerebrum REST mangler i dag et par ting:

  • OU postadresse
  • persontitler (entity_name_with_language)
  • Stillingskode og stillingsandel
  • Stillingsbetegnelse på affiliation

Cristin-WS + push fra Cerebrum

Denne løsningen bør implementeres så likt som mulig Cerebrum-Rest-løsningen:

  1. Egen service lytter på meldinger,
  2. henter data ut fra Cerebrum og
  3. dytter disse inn i Cristin.

Hente ut av Cerebrum kan gjøres på to måter:

  1. Bruke rest-grensesnittet til Cerebrum, eller
  2. Cerebrum-API direke.

Uttrekk via REST-grensesnitt bør være å foretrekke, selv om å bruke Cerebrums interne API direkte kan gjøre utviklingstiden (og kjøretiden) kortere. Fordelen med en løsere tilknytning til Cerebrum, er at det er lettere å integrere direkte med HR-systemer for data Cerebrum ikke leverer.

Publisert 21. okt. 2016 10:42 - Sist endret 10. nov. 2016 11:57