Rutiner

Interne, tekniske rutiner for FS-API.

Brukere og tilganger

Innledning

Vi har to databaser for autentisering/autorisering (bruker FSWS_AUTH):

FSWSDMO brukes av to miljøer:
- Test
  - Kjører på fsapi-test.uio.no
  - Har tilgang til alle demobaser
- Utv
  - Kjører på fsapi-utv.uio.no eller lokalt
  - Har tilgang til utviklingsbasen (I1234_FS_WS@FSUTV)
FSWSPRD brukes av ett miljø:
- Prod
  - Kjører på api.fellesstudentsystem.no
  - Har tilgang til alle prodbaser

Vi starter som regel med å gi tilgang i Test (hvis ikke Prod eksplisitt etterspørres med en gang).

Auth-tabeller

Følgende tabeller brukes i API-sammenheng:

PERSON

Kontaktperson for WSBRUKER
Sortér for eksempel på NAVN eller EPOST for å finne om personen eksisterer fra før

WSBRUKER

Systembruker (vi opererer ikke med personlige brukere, de er knyttet til institusjon)
NAVN (brukernavn) følger en viss policy (som i varierende grad følges):
- For institusjonsbrukere (egen utvikling ved institusjonen) bruker vi institusjonsakronym med evt. tall eller målsystem til slutt, f.eks:
  - uit, uit2, uit_canvas
- For leverandørbrukere (3.partsleverandører) bruker vi leverandørakronym_institusjonsakronym, f.eks:
  - altran_nord, bouvet_uio
- For interne systembrukere gjelder omtrent det samme som for leverandørbrukere, med et mulig test/prod-ledd i midten, f.eks:
  - bibsys_hvo, epn_test_aho
KONTAKT refererer PERSON.ID
DB er datakilde
- NB! Det er viktig at dette er en gyldig datakilde (sorter på feltet hvis du er usikker på gyldige verdier)
INSTITUSJONSNR må stemme overens med DB
- Dvs. begge må peke på en rad i WSINST_DB med samme kombinasjon (dette er å betrakte som en designfeil, som vil bli rettet opp)
PASSORD
- Kryptert passord genereres på Linux:
  - echo -n passord | openssl dgst -sha1 -binary | base64
- Ukryptert passord sendes på SMS til PERSON.TELEFON
ALLE_INSTITUSJONER skal i praksis alltid være N

WSBRUKER_ROLLER

Gir tilgang til personrelaterte ressurser
NAVN refererer WSBRUKER.NAVN
ROLLE refererer WSROLLE.ROLLEKODE
Rollekoder som slutter på -SPERRET brukes til å midlertidig fjerne tilganger uten å slette dem

Ressurstilgang

Ressursene kan deles inn i åpne og lukkede.

Lukkede ressurser

Dette er ressurser som inneholder person-tilknyttede opplysninger, dvs. refererer /personer/ID (direkte eller indirekte). Disse krever eksplisitt tilgang for WS-bruker:

GET
- Individ: Kun individoppslag
- Collection: Innebærer også Individ
POST
- Individ: Update
- Collection: Create
DELETE
- Individ: Slett individ
- Collection: N/A

Åpne ressurser

Resten av ressursene krever bare WS-bruker (bl.a. alle under Koder).

Kommunikasjon

Mail

Må sjekkes flere ganger daglig
Det er den enkeltes ansvar å følge opp (evt. delegere) oppgaver
Hvordan man gjør dette, er opp til den enkelte (bare det fungerer)

Slack

Bruk kanal fsapi-integrasjon (anbefaler å Star’e), ikke direkte meldinger
Svar i egne tråder, for å holde toppnivået ryddig

RT (måter å gi folk beskjed på)

Sette sak over til vedkommende
Sette vedkommende på cc
Comment med cc

Jira (måter å gi folk beskjed på)

Comment + mail/Slack med link

Jira

Opprett alltid en Jira-sak, for enhver endring
Husk å sette følgende felt:
- Epic Link
- Fix Version (hvis usikker, bruk f.eks. 1.N.N for å angi at den ikke brekker v1)
Sett disse hvis aktuelt/informasjon foreligger
- Sprint
- RT URL / Mail Subject 1
- Affects Version
- Link Issue (Refers, Depends On…)
  - Kan også brukes ifm. setting av Status:
    - Avhenger av noe som ikke er ferdig => On Hold
    - Avhenger av noe som er ferdig => Open/In Progress
Hold Status ajour!

Bitbucket

Branching

Pipeline
- develop => release/Candidate => master
Navngiving
- prefix/FSWS-nnnn-beskrivelse-av-saken
Prefix:
- master => hotfix
- rel/cand => bugfix
- develop => feature / bugfix
Prinsipper:
- Når branchen er testet
  - PR for merge tilbake
  - Merge med sletting
- Sync bakover i pipeline så tidlig som mulig (for å minimere konflikter)
- Alt som ligger i develop er testet og klar for neste release

Commits

Commit-message: '[FSWS-nnnn] Beskrivelse av saken'

Oversikt over endringer i release

Ligger her
Trekkes ut fra Jira første gang
Bearbeides
- Fjern interne punkter som ikke gir mening utad
- For alle app/db-par, fjern db-punktet
- Fjern " (app)" fra app-punktene
- Omformuler evt. kryptiske punkter
Hvis nye saker kommer til i releasen, legg dem til manuelt

Deployment

Hovedpunkter

Sync evt. bugfix/hotfix tilbake til fra-branch
Godkjenn/merge alle aktuelle PR
Kjør full test i Utv
Avtale med www-drift (standby)
Stopp MQ-jobb (som FS-bruker) – Foreløbig 185/FSDEMO/PROD og 184/FS08DMO/PRD
1. BEGIN PK_FSAPI_MQ.P_Stopp_Jobb (NULL, 0); END;
  1. Setter ENABLED = FALSE
  2. Lar evt. kjørende jobb gå ferdig
2. Sjekk jobbdefinisjoner og kjørende jobber (se under)
3. Hvis det haster og det tar lang tid før kjørende jobb er ferdig
  1. BEGIN DBMS_SCHEDULER.Stop_Job (Job_Name => 'JOB_nnnn_FSAPI_MQ_SEND'); END;
  2. Der nnnn = Institusjonsnr (med ledende 0)
Vis static-side for applikasjon
Git tag/merge
Erstatt app med statisk webside
Rull ut fs-api-db i alle baser
1. cd …/fs-api-db
2. git checkout <release-branch>
3. sqlplus FS/passord@database
  1. start FSAPI_offisiell.sql
  2. NB! Det funker ikke å kompilere CC-fil alene, eller å gjøre endringer i genererte filer (se under)
4. tail -50 FSAPI_core.lst
  1. Sjekk at det ikke rapporteres noen feil (bortsett fra evt. ORA-04043 på DROP PACKAGE)
Rull ut app

Spørringer

Jobbdefinisjoner

select JOB_CREATOR, JOB_NAME, ENABLED
     , replace (replace (replace (JOB_ACTION,'begin ',''), ' end',''), ';','') JOB_ACTION
     , to_char(START_DATE     ,'DD.MM.YYYY HH24:MI') START_DATE
     , to_char(LAST_START_DATE,'DD.MM.YYYY HH24:MI') LAST_START
  from ALL_SCHEDULER_JOBS
 where JOB_NAME like '%MQ%'
 order by 1, 2
;

Kjørende jobber

select OWNER, JOB_NAME
     , ELAPSED_TIME
  from ALL_SCHEDULER_RUNNING_JOBS
 where JOB_NAME like '%MQ%'
 order by 1, 2
;

Conditional Compilation

Innledning

Dette er en måte i PL/SQL å inkludere/utelukke kode ut fra direktiver (en form for heltalls-“variable“ som settes i compile-time, litt à la preprosessoren i C). Denne mekanismen er brukt til å styre om deler av en SQL skal være med i en gitt sammenheng, for å bedre ytelsen:

Sortering, paginering og wildcard i ID-komponenter er meningsløst for individkall
- Dette er gjennomført for alle ressurser
Tunge joiner og unioner kan droppes hvis koblingsinformasjon ikke er angitt
- Foreløbig gjennomført for Person (join med Student/Fagperson utelukkes hvis ikke etterspurt)

Tekniske detaljer

Dette er implementert på følgende måte:

De gamle filene FSAPI_Pakke.pks/pkb er erstattet av FSAPI_Pakke_CC.pks/pkb
- Disse inneholder direktiver
Kallende script FSAPI_core.sql (som kalles av FSAPI_offisiell.sql eller FSAPI_intern.sql) setter direktiver før kompilering av CC-filene
Dette skjer flere ganger, for forskjellige kombinasjoner av direktiv-verdier
For hver gang legges direktiv-behandlet kode i genererte pakkefiler
- Disse har direktiv-verdiene i suffiks på navnet:
  - FSAPI_Pakke_N.pks/pkb
  - FSAPI_Pakke_N_MM+.pks/pkb
- Der
  - N = 1 (individ) / 2 (collection)
  - M = 0 (false) / 1 (true) – Om aktuelt join-/union-ledd er med
- De genererte pakkefilene representerer altså forskjellige kombinasjoner av direktiv-verdier
  - Så å si alle funksjoner i en CC-fil har direktiver for individ/collection
    - Unntaket er 1:1-subressurser (f.eks. F_GET_Personbilder), som kun har mening i individsammenheng
  - Derimot vil join-/union-direktiver kun forekomme for et fåtall av funksjoner i en pakke (hvis noen)
    - Resten av rutinene i fila blir da like for forskjellige kombinasjoner av join-/union-direktiver
I tillegg er det introdusert skall for de forskjellige pakkene (FSAPI_Pakke_sh.pks/pkb)
- Det er disse som nå kalles av applikasjonen (de har navn uten suffiks)
- De avgjør, ut fra parameterverdier, hvilken generert pakkevariant som skal kalles

Dette innebærer at:

Master-logikken ligger i CC-filene, men
CC-filene kan ikke kompileres alene, kun fra kallende script (som setter direktiv-verdier)
1. FS-skjemaet: FSAPI_offisiell.sql
2. Innnn_FS_WS: FSAPI_intern.sql
Det er meningsløst å endre genererte pakkefiler, da disse overskrives ved neste kompilering

Restart av containere

Dette gjøres via Rundeck:

Gå til FSAT-VIP => Restart av FSAPI docker containere
Velg miljø, trykk Run Job Now

Publisert 16. juni 2020 13:45 - Sist endret 28. mars 2022 18:23

Rutiner

Brukere og tilganger

Innledning

Auth-tabeller

PERSON

WSBRUKER

WSBRUKER_ROLLER

Ressurstilgang

Lukkede ressurser

Åpne ressurser

Kommunikasjon

Mail

Slack

RT (måter å gi folk beskjed på)

Jira (måter å gi folk beskjed på)

Jira

Bitbucket

Branching

Commits

Oversikt over endringer i release

Deployment

Hovedpunkter

Spørringer

Jobbdefinisjoner

Kjørende jobber

Conditional Compilation

Innledning

Tekniske detaljer

Restart av containere

Besøksadresse

Postadresse

Kontakt