Dokumentasjon av EndringsloggAPI i Matrikkelen

Dette dokumentet inneholder dokumentasjon av webservice for endringslogg.

Forklaring på endringsloggen og hvordan endringer blir lagret og hentet ut

Når boble-objekter i domenemodellen opprettes, oppdateres, endrer logisk ident eller slettes, registreres det endringshendelser i databasen. Disse lagrer bl.a tidspunkt for endring, brukernavn på den som utførte endringen, og i visse tilfeller dataelementer som er interessant som historikk. Endringene hentes ut gjennom en webservice som gir et xml-dokument med ett element for hver endring. Hvilken type endring det er snakk om (Nyoppretting, Oppdatering etc) er definert som xml-attributtet endringstype. Attributtet kilde angir i hvilken kontekst endringen er oppstått. I tillegg vil endringen ha felt for unik id til det objektet endringen gjelder. Dette er det samme som primærnøkkelen i Matrikkelens database. Merk at det ikke gis garanti om at unik id ikke endres over tid. Hver endring har et endringsnummer-attributt som tilordnes i stigende rekkefølge, ikke nødvedigvis kontinuerlig, dvs det kan vært huller. Attributtene er forklart litt nøyere i det følgende.

Endringstype

Endringstype forteller hva slags endring endringen er. Mulige verdier er Nyoppretting, Oppdatering, Identendring og Sletting. Endringsobjektene har to identelementer: ident og utgattIdent. Disse refererer til det endrede objektets ident. Avhengig av typen endring vil de to identelementene ha forskjellig betyding:

Endringskilde

Attributtet kilde angir i hvilken kontekst endringer er opprettet. Den kan ha følgende verdier:

Kobling til domeneobjekt

Hver endring har referanse til intern id for objektet endringen gjelder. Dette bruker endringsloggwebservicen til å koble endringer med siste versjon av objektene endringene gjelder for endringer av typen Nyoppretting eller Oppdatering. Disse id-referansene er ikke håndhevet med fremmednøkler i databasen. Det betyr at en endring via id-referansen kan referere til et objekt som ikke lenger finnes i. Figuren nedenfor viser dette.
Endring med slettet objekt har fortsatt id
Dette vil i utgangspunktet si at f.eks. en oppdateringsendring kan referere til et objekt det senere i loggen finnes sletteendring for.
Selv om slettemeldingen ikke inneholder selve objektet som er slettet, vil eksterne registre likevel kunne synkroniseres ved å identifisere objekter som skal slettes vha utgattIdent.

Bruk av endringsloggen

Endringsloggen er primært ment som en synkroniseringsmekanisme for å holde andre systemer ajour med Matrikkelen. Loggen holder derfor generelt ikke rede på alle historiske tilstander av de endrede objekter. Hver endring refererer primært til objektene via logisk ident, og det forventes at eksterne systemer benytter disse til å identifisere sine kopier for oppdatering og sletting etc.

Endringsloggen inneholder i prinsippet en liste over alle de ganger et objekt har endret seg, men det bare mulig å hente ut nåværende versjon av selve objektet. Dvs., et objekt kan f.eks over tid ha fått 1 Nyopprettingsendring og 10 Oppdateringsendringer i endringsloggen. Det er mulig å hente ut objektet sammen med endringen og her er det viktig å forstå at det objektet man får er slik det er i Matrikkelen når endringen hentes ut og ikke slik objektet var da endringen oprindelig ble gjort.


Figuren nedenfor viser situasjon der navnet på en veg endres to ganger. Begge endringene vil referere til siste versjon av vegen.


Loggen inneholder bare siste versjon av et objekt



Endringsloggen tilbyr operasjoner for å finne ut hvor mange endringer som er registrert (siden siste gang)  og hva som er siste endringsnummer. Metoden for å beregne hvormange endringer som er registrert er ressursskrevende og bør derfor brukes sparsomt. Det er greit å kalle metoden en gang per objektklasse ifm. initiell nedlastingen for å få et øvre estimat for antall endringer det finnes for en gitt type. Man kan da selv (i klienten) holde styr på hvormange endringer man har lastet ned, beregne hva som gjenstår og ut fra det evt. vise fremdrift for nedlastingen.

Metoden som henter ut endringer vil returnerer et endringslogg objekt med 0 endringer når det ikke er fler endringer igjen for de angitte søkeparametre. Anbefalt algoritme for nedlasting av endringer er:

1.  les siste endringsnummer sisteEndringGammel fra fil eller 0 hvis initiell nedlasting.
2.  sisteEndringNy = findAntallEndringerEtterEndringsnr(sisteGammel, [kommunenr], null, context);
3.  if (sisteEndringNy==sisteEndringGammel) exit;
4.  for (objektklasse : objektklasser) {
5.     siste = sisteEndringGammel;
6.     while (true)
7.        endringer = findEndringerEtterEndringsnr(siste, [kommunenr], 1000, objektklass, false, true, context);
8.        if (endringer.getEndringerArray().length==0) break; // har fått alle endringer for objektklassen
9.        prossesserEndringer(endringer, sisteEndringNy);
10.       siste = endringer.getSisteEndringsnr()
11.    }
12.    if (sisteEndringNy < siste) {
13.       // Det har kommet inn nye endringer i Matrikkelen siden nedlastingen startet.
14.       // Man må selv vurdere om dette er et problem.
15.       // I prinsippet kan det komme endringer hele tiden
15.    }
16. }
17. skriv sisteEndringNy til fil
18. exit;

Metoden som prossesserer endringene vil iterere igjennom alle endringer og typisk skrive dem til en lokal database. Denne metoden må også ta stilling til hva som skal skje hvis man får endringer med endringsnummer større enn sisteEndringNy. En mulighet vil være å springe over disse endringer og ta dem med i neste incrementelle nedlasting. Hvis man gjør det trenger man kun å huske på sisteEndringNy for å vite hvor langt man har kommet. Hvis man prossessere endringer med endringsnummer større en sisteEndringNy, må man ta vare på siste endringsnummer for hver objektklasse.

Rekkefølge på objekter

I utgangspunktet returneres endringer i den rekkefølge de er registrert. Dette kan imidlertid by på enkelte problemer. Man kan tenke seg følgende scenario:

Det opprettes en Veg1, senere en Adresse1 som refererer til Veg1. Senere opprettes en ny Veg2, og Adresse1 endres deretter til å referere til Veg 2. Siden endringene i endringsloggen alltid inneholder siste versjon av objektet, vil objektet i endringen for Adresse1 i segmentet som hentes ut i figuren nedenfor inneholde siste versjon av Adresse1, som nå refererer til Veg2. Siden segmentet slutter før endringen der Veg2 blir opprettet opptrer, vil det det se ut som om den nyopprettede Adresse1 refererer til en ikke-eksisterende veg, nemlig Veg2.

Uthenting av intervall hvor objekter refererer til andre so kommer senere

Her finnes to strategier:
  1. Godta at objekter kan referere til ukjente identer, og så anta at de blir definert ved en senere anledning, f.eks. ved neste batch. Det kan da opprettes en kryssreferansetabell eller liknende, som brukes til å holde rede på ikke-løste identer som så knyttes sammen når de ankommer.
  2. Hente endringer ut i logisk avhengighetsrekkefølge. Denne rekkefølgen er som følger:

Massivuthenting etter konvertering

Etter at én eller flere kommuner er konvertert til Matrikkelen, vil det være behov for uthenting via Endringsloggen. Her ser man for seg to scenarier:
  1. Eksternt system skal synkroniseres mot Matrikkelen. For systemer som allerede har deler av konverterte data, vil det kanskje være mest interessant å kun bruke endringer med kilde OpprettetUnderKonvertering og de med kilde Matrikkel.
  2. En kommune skal opprette en lokal kopi av Matrikkelen. En mulig fremgangsmåte vil være å hente alle endringer for kommunen etter type. De objekter som ikke er spesielt knyttet til den aktuelle kommunen, som for eksempel personer, vil være referert til gjenneom andre objekter i endringsloggen, f.eks. tinglyste eierforhold. Disse objektene kan hentes gjennom en egen operasjon i webservicen som henter objekter ut fra identer, hentMatrikkelObjekter.
For begge disse scenariene bør man velge en passelig batch-størrelse. Det finnes for øyeblikket lite empiri rundt fornuftige størrelser, men vi vil anta at en batch på 500 er et godt utgangspunkt. Begrensninger her er dokumentstørrelser, minnebruk på server, overføringtid etc.

Jevnlig oppdatering

Eksterne systemer kan jevnlig hente ut oppdateringer ved å ta vare på siste endringsnummer som ble mottatt og fortsette derfra. Uthenting gjøres gjerne i porsjoner, hvor maksimalt ønsket antall kan angis som parameter. Dette gjør at man kan tilpasse bolkene etter f.eks linje-, parser- eller lokal oppdateringskapasitet. Hvert uthentet segment vil angi første og siste endringsnummer. Ved påfølgende søk henter man derfor ut endringer etter siste endringsnummer i foregående bolk.

Innebygde optimaliseringer

Når det hentes ut et endringsloggsegment, vil webservicen optimalisere segmentet slik at det blir færrest mulig elementer i det returnerte xml-dokumentet. Optimaliseringreglene er formulert nedenfor. Generelt gjelder reglene for endringer for hvert objekt.

Nye tjenester for endring av subtype

Fra versjon 2.9 produksjonssettes nye tjenester for endring av subtype, hvor de nye objektene som sendes inn nå er en oppdatering av opprinnelig objekt, og de nye objektene beholder opprinnelig id-verdi. Dette påvirker også endringsloggen ved at tjenestene for endring av subtype nå genererer litt andre endringshendelsene enn det som ble gjort tidligere.

Tidligere var det generelt en identendring og oppdatering på selve objektet som ble endret, i tillegg til at alle tilknyttede objekter fikk en oppdatering og eventuelt en identendring. Nå skjer det fortsatt en identendring og oppdatering på selve objektet som endres, men til forskjell fra før vil ny og utgått identunikid være lik. Det skjer ikke lenger en oppdatering av alle tilknyttede objekter, kun på de objektene som kan endres på via tjenesten. På objekter som har referanse til det endrede objektet via sin ident registreres det identendringshendelse på. De nye tjenestene genererer altså færre og andre endringshendelser enn det som tidligere ble gjort.

Noen eksempler på hvilke endringshendelser tjenestene genererer:

Endre matrikkelenhetstype
Endring Gammel tjeneste Ny tjeneste
ForretningEndring Nyoppretting og oppdatering Nyoppretting
MatrikkelenhetsEndring Nyoppretting og oppdatering Nyoppretting og oppdatering
  Oppdatering av alle objekter som er knyttet til matrikkelenheten, eks vegadresse, matrikkeladresse, bruksenhet, grunnerver Identendring på alle objekter som refererer til matrikkelenheten i identen sin, eks: matrikkeladresse


Endre matrikkeladresse til vegadresse
Endring Gammel tjeneste Ny tjeneste
Matrikkeladresseendring Identendring Identendring
BruksenhetEndring Nyoppretting og oppdatering Identendring
VegadresseEndring Oppdatering av den nye vegadressen Oppdatering av den nye vegadressen


Tilbygg etableres som egen bygning
Endring Gammel tjeneste Ny tjeneste
BygningsendringEndring Identendring Identendring
BruksenhetEndring Identendring og oppdatering Identendring og oppdatering
BygningEndring Oppdatering Oppdatering
  Oppdatering av tilknyttede objekter, eks sefrakminne  

Gjør oppmerksom på at dette er kun eksempler, og at tjenestene kan generere flere eller færre endringshendelser en de som vises her.

Dokumentasjon av endringsloggens Web Service

Dokumentasjon for Web Service modeller

XML Schema for web tjenestene finnes i WSDL-dokumentene (se over).
I tillegg bør du lese tekstlig dokumentasjon av XML skjemaene.

Det er ikke egne UML diagrammer for endringsloggen, da datamodellen for endringsloggen er basert på den underliggende domenemodellen for matrikkelen.
UML diagrammer for domenemodellen finnes her, og detaljert tekstlig dokumentasjon finnes her.