Gå til hovedinnhold

Legge til tabeller i kjerne-APIet

Kjerne-APIet i FS-plattformen er et internt API som tilgjengeliggjør data og forretningslogikk fra FS til utviklere som skal lage eksterne APIer. Det finnes flere teknikker for å utvide kjerne-APIet. I dette dokumentet finner du veiledning for hvordan du utvider kjerne-APIet ved å legge til en tabell eller en join mellom flere tabeller i fra FS-kjernen.

Legge til en tabell som finnes i FS​

For å legge til en tabell som finnes i FS, er det tilstrekkelig å legge inn et view-element for tabellen i fila kjerneapi-runtime/src/main/resources/configuration.xml, som inneholder følgende data:

  • view.viewId: Et løpenummer som skal være unikt. Dette gir en unik identifikator for tabellen i Bruk første ledige. OBS! Før du merger inn endringen din, må du dobbeltsjekke at løpenummeret du har valgt, ikke er blitt tatt av noen andre i mellomtiden.
  • view.viewName: Det du vil viewet skal hete i kjerneapiet
  • view.tableName: Navnet på tabellen i FS
  • view.columns: Alle kolonner du vil ha med ut i viewet. Dersom viewet inneholder fødselsnummer, skal du også legge til PERSONLOPENR (denne blir lagt til via en join mot person-tabellen som gjøres automatisk).
  • view.plattformId: Konfigurasjon av kolonnerekkefølgen for primærnøkkelen til viewet. Legg inn columns for alle kolonner som inngår i primærnøkkelen. Dersom tabellen i databasen har FODSELSDATO og PERSONNR i primærnøkkelen, erstatter du disse med PERSONLOPENR.
  • view.access: Tilgangskontroll for tabellen. Se tilgangskontroll

Legge til et view basert på en join mellom flere tabeller eller en filtrert tabell​

Det er også mulig å legge til views som joiner flere tabeller. Dette gjør du ved å legge til en fil i katalogen kjerneapi-db/src/main/resources/no/fellesstudentsystem/kjerneapi_db/views. Fila skal starte med en header med følgende innhold:

--liquibase formatted sql
--changeset [forfatter]:[LiquibaseId] runOnChange:true

Eksempel:

--liquibase formatted sql
--changeset kjetil:EmneSoknad runOnChange:true

Deretter skriver du SQLen for viewet.

LiquibaseId-en og navnet på fila må være det samme som navnet på viewet i SQLen.

I configuration.xml (se over) må du legge inn:

  • view.viewId: Et løpenummer som skal være unikt. Dette gir en unik identifikator for tabellen i Bruk første ledige. OBS! Før du merger inn endringen din, må du dobbeltsjekke at løpenummeret du har valgt, ikke er blitt tatt av noen andre i mellomtiden.
  • view.viewName: Samme som viewname definert i SQL-fila
  • view.tableName: Navnet på den tabellen du vil at primærnøkkel og fremmednøkler skal genereres fra. Hvis du ikke vil at nøkler skal genereres, kan du droppe dette steget, men da må alle nøkler legges til som syntetiske nøkler i kjerneapi/jooq-configuration.xml (se under).
  • view.columns: Alle kolonner som inngår i primærnøkler og fremmednøkler du vil ha med ut i viewet.
  • view.plattformId: Konfigurasjon av kolonnerekkefølgen for primærnøkkelen til viewet. Legg inn columns for alle kolonner som inngår i primærnøkkelen. Dersom tabellen i databasen har FODSELSDATO og PERSONNR i primærnøkkelen, erstatter du disse med PERSONLOPENR.

Ekstra nøkler​

Helt unntaksvis kan vi legge til ekstra primær- og fremmednøkler ved å redigere <primaryKeys> og/eller <foreignKeys>-elementene i kjerneapi/jooq-configuration.xml. Denne funksjonaliteten er ment som et supplement til autogenerering av nøkler, og ikke som en snarvei for å legge inn relasjoner mellom tabeller som ikke er koblet sammen i databasen. Dersom vi har behov for en slik relasjon i GraphQL-APIet, skal det løses på andre måter, f.eks. ved å legge inn en condition i kjerne-APIet. Forøvrig jobbes det med funksjonalitet i Graphitron for å erstatte de fleste behov for bruk av syntetiske nøkler.

Fjerne klokkeslett fra datofelter​

Oracle-felter med type Date inneholder både dato og tidspunkt. Noen av disse feltene er egentlig ment å uttrykke datoer uten klokkeslett. I FS er dette løst med en constraint, men det er ikke gjennomført konsekvent. Dette fører til at enkelte datofelter blir representert som DateTime i kjerne-APIet, i stedet for Date. Dette skal selvsagt løses i databasen på sikt, men vi har en midlertidig løsning som går ut på å legge inn et unntak i kjerneapi-runtime/src/main/resources/configuration.xml under trunkatedDates.

F.eks:

<view>
    ...
    <columns>
            ...
    </columns>
    <truncatedDates>
        <column>DATO_FRA</column>
        <column>DATO_TIL</column>
    </truncatedDates>
    ...
</view>
Denne endringen får konsekvenser for alle APIer på FS-plattformen som bruker feltet

Dersom du legger trunkering på et felt som er i bruk i et API i FS-plattformen fra før, vil du få byggefeil. Dersom APIet det er snakk om, er i produksjon, må du antakelig velge en annen strategi for å få dataene korrekt ut i feltet du ønsker å eksponeret. Når det er sagt, er det som regel entydig hvorvidt et felt er ment å inneholde en dato eller en dato med klokkeslett, så dette er en relativt trygg endring i de fleste tilfeller.