Veileder i å modellere en produktspesifikasjon som utplukk fra SOSI fagområdestandarder

Versjon 2024-09-04

Veilederen beskriver ei enkel løype med 29 enkle etapper som skal sikre at modellen blir i henhold til standard. Hvis du opplever problemer med veilederen er det fint om du kan sende en tilbakemelding til
standardiseringssekretariatet@kartverket.no

Generell forberedelse

Trinn 1 Bestem klart hvilke objekttyper produktet skal inneholde

Trinn 1 Bestem klart hvilke formål produktet skal dekke, og hvilke objekttyper produktet skal inneholde

Lag en tydelig beskrivelse av hvilke brukstilfeller produktet skal tilfredsstille.
En vil da være i stand til å teste det ferdige produktet og avgjøre om produktet oppfyller formålene.
Beskrivelse av brukstilfeller er også godt grunnlag for å vurdere om dataene er egnet for gjenbruk i nye brukstilfeller.
Brukstilfellene bør listes opp i produktspesifikasjonens kapittel 3.8 Formål, og kan med fordel beskrives i detalj i eget vedlegg.

Trinn 2 Etabler innsikt i relevante fagområder og føringer

Trinn 2 Etabler fullstendig oversikt og innsikt i innholdet i alle fagområder i SOSI del 2 som er relevante for produktet, og de muligheter og føringer som Geodataloven gir gjennom Inspire-modellene.

Se hvilke nasjonale SOSI-fagområdestandarder som er tilgjengelige på
http://register.geonorge.no/standarder/sosi/del-2-generell-objektkatalog
eller søk med fritekstsøk på relevante termer gjennom webinnsyn i GeoNorge-portalen
http://objektkatalog.geonorge.no
Se også hvilke nasjonale SOSI-produktspesifikasjoner som er godkjent og publisert på
http://sosi.geonorge.no/Produktspesifikasjoner
Avklar også hvilke relevante internasjonalt harmoniserte spesifikasjoner som Geodataloven pålegger at vi skal realisere
http://inspire.ec.europa.eu/data-specifications
Få oversikt over innholdet i modellregisteret via en enkel oversiktsnettside
http://sosi.geonorge.no/sosi-modellregister/html

Trinn 3 Bestem hvilke generelle fellesegenskaper som skal benyttes

Fagområdene inneholder ikke fellesegenskaper så disse må hentes fra pakker under SOSI generelle konsepter/SOSI generelle typer. (SOSI_Fellesegenskaper og SOSI_Objekt). Følg relevante linker som i forrige punkt.

Innsamling til lokal prosjektmodell i EA

Trinn 4 Last inn kopier av fagområder

Trinn 4 Last inn siste versjon av kopier av alle relevante SOSI del 2 fagområder fra SOSI modellregisteret (subversion – SVN).

Det forutsettes her at Enterprise Architect har blitt konfigurert som beskrevet i dokumentet "Installasjon av nødvendig programvare for arbeid med SOSI-produktspesifikasjoner".

Før man begynner arbeidet med en UML-modell for en produktspesifikasjon må man oppdatere sine kopier av fagområdemodellene i SOSI del 2 slik at man har tilgang til de nyeste versjonene av alle objekttyper og kodelister.
Man kan først hente en relativt oppdatert versjon fra SVN-serveren ved å laste ned fila fra linken
http://sosi.geonorge.no/modellfiler/sosi_modellregister.qea

Dersom denne fila er hentet på et tidligere tidspunkt kan man oppdatere innholdet ved å høyreklikke på en pakke i Project Browseren og velge Package Control og Get All Latest.

Valg av subsett

Trinn 5 Lag en ny pakke for produktspesifikasjonen stereotypet «ApplicationSchema»

Trinn 5 Lag en ny pakke for produktspesifikasjonen stereotypet «ApplicationSchema» i SOSI-modellregister for å lagre produktspesifikasjonsmodellen

UML-modeller for produktspesifikasjoner skal lagres under mappen "SOSI Produktspesifikasjoner" og der igjen under de respektive partenes mapper.
Se eksempel nedenfor.

Dersom du starter arbeidet med en ny produktspesifikasjons-UML-modell skal du gå fram slik:

I tilfellet at det ikke finnes ei pakke med navnet på din etat/ditt institutt ta først kontakt med Kartverket som vil legge inn etaten. (mailto:standardiseringssekretariatet@kartverket.no).
Sjekk ut aktuell pakke under "SOSI Produktspesifikasjoner/DinEtat" (og eventuelt "/DittTema". Les mer om Check Out i installasjonsveiledningen).
Legg til en ny pakke som skal inneholde UML-modellen til den nye produktspesifikasjonen. Det gjør du ved å høyreklikke på pakka som du har sjekket ut under I. Så velger du Add a Package.
I den nå åpnede dialogboksen "New Package" velger du et navn for produktspesifikasjonen pluss hovedversjonsnummer. (eks. Havnetrafikk-5.2). Kryss av "Add to Version Control". Det er opsjonelt å krysse av "Automatically add new diagram". Du kan enten legge til et nytt diagram nå eller gjøre dette senere. Se punkt VIII for en kort beskrivelse.
Klikk OK og dialogboksen "Package Control Options" åpnes. Her må opsjonene "Control Package" og "For all packages, create placeholders for external references" krysses av. Velg "SOSI" under Version Control .

Nå må riktig sti velges der xml-filen skal lagres. Klikk på (…) symbolet bak XMI Filename. Nå havner du i arbeidsmappen som du anga under konfigurasjonen av SVN-tilgang. Gå til "SOSI Del 3" og mappen med navnet til din etat/ditt institutt (her eksempelvis "Statens kartverk"). Klikk Save og OK.
Så kommer det to dialogbokser. På den første er det mest naturlig at du krysser av "Keep checked out" slik at du kan begynne å jobbe med UML-modellen.

På den andre kan du skrive en kort kommentar i forbindelse med at en ny pakke har blitt lagt til.
Pakka som du har lagt til skal ha stereotype «ApplicationSchema». Høyreklikk på pakka, velg Properties og på "Stereotype …". I den følgende dialogboksen velg først navn på profil: "SOSI UML profil 5.0", deretter hak av i dialogboksen på ApplicationSchema. Klikk så OK, og OK på Properties.
Har du under punkt III ikke valgt at det skal gjøres automatisk, må du nå legge til et nytt diagram. Høyreklikk på pakka, så velger du Add Diagram. I den følgende dialogboksen velger du et navn for diagrammet og Class under "Diagram Types". Det er anbefalt å navne slik: "Hoveddiagram Havnetrafikk". Bekreft valget ved å klikke OK.

Lag om nødvendig egne diagram for kodelister og datatyper på samme vis. Egne diagram for dokumentasjon av realisering av objekttypene, og for realisering av SOSI_Fellesegenskaper og SOSI_Objekt kan også lages.
Husk å sjekke inn etatspakka der applikasjonsskjemaet ligger under. Er arbeidet med UML-modellen (foreløpig) avsluttet så husk å lagre den oppdaterte applikasjonsskjemapakka tilbake til serveren ved å sjekke inn. Høyreklikk på pakka og velg Package control/Check in, og beskriv kort dine siste endringer.

Trinn 6 Merk, og lag kopier av hver relevant pakke i fagområdet.

Trinn 6 Merk, og lag kopier av hver relevant fagområdepakke til din egen applikasjonsskjemapakke

Merk og kopier med Full Structure for Duplication, og lim inn kopiene. Alle lenker mellom modellelementene i pakka blir da beholdt. Det er spesielt viktig å lage kopier av disse pakkene da modellelementene i disse kopiene får tildelt nye interne id-er i EA. Derved unngår man å forveksle id-er i egen produktspesifikasjonspakke med eksisterende fagområde-id-er.

Lim inn kopien i applikasjonsskjemapakka.

Repeter å lage egne kopier for alle pakker med aktuelt innhold.

Trinn 7 Flytt alle ønskede objekttyper, datatyper og kodelister opp i den nye pakka.

Trinn 7 Flytt ønskede objekttyper, datatyper og kodelister opp i den nye applikasjonsskjemapakka.

Dra og slipp alle aktuelle klasser eller underpakker du trenger fra kopien av sin opprinnelige fagområdepakke direkte inn i applikasjonsskjemapakka.

Det resterende innholdet i kopiene av fagområdepakkene skal til slutt slettes, slik at en står igjen med kun modellelementer som er relevante for produktet. Lagre gjerne først de resterende elementene i en egen pakke lokalt, i tilfelle det viser seg at en må ha med flere modellelementer.

Trinn 8 Dra alle klassene inn i et klassediagram, eventuelt i egne diagram.

Trinn 8 Dra alle klassene ut i et klassediagram kalt Hoveddiagram Nnn,

eventuelt i egne diagram for kodelister og datatyper.

Vis alle objekttypene ved å dra disse inn i valgte diagrammer, som "Simpel Link".

Plasser objekttypene i diagrammene slik at det blir lett å få oversikt over helheten i modellen.

Gjenta samme prosess for alle aktuelle datatyper og kodelister.

Trinn 9 Fjern «topo»-assosiasjoner og lag tilsvarende restriksjoner. Lag lovlige navn på koder. Fjern unødvendige assosiasjoner, egenskaper og koder fra klassene.

Trinn 9 Fjern «topo»-assosiasjoner og lag tilsvarende restriksjoner.

Lag lovlige navn på koder.
Fjern unødvendige assosiasjonsroller, egenskaper og koder fra de valgte klassene.

De spesielle nasjonale assosiasjonene merket med stereotypen «topo» er ikke videreført i SOSI 5.0. Disse skal derfor fjernes og tilsvarende informasjon overføres til restriksjoner. Dette gjøres enten manuelt ved å skrive inn restriksjonen og så høyreklikke på assosiasjonen og velge "Delete connector"

Dette kan gjøres helautomatisk ved å høyreklikke på applikasjonsskjemapakka og velge Scripts/endreTopoAssosiasjonTilRestriksjon og trykke Ok.

Dersom en ønsker å beskrive ytterligere begrensninger i bruk av modellen angis da dette som en eller flere restriksjoner med selvforklarende navn, og beskrevet i både klart språk og i Object constraint language (OCL).

Mange kodelister hadde tidligere meningsløse tallkoder som initialverdi. Disse initialverdiene kan nå flyttes til en tagged value "SOSI_verdi". Dette gjøres helautomatisk ved å høyreklikke på ei kodeliste i prosjektbrowseren, og velge Scripts/flyttInitialverdiPåKodelistekoderTilSOSITag og trykke Ok.

Dersom kodene er vanlige typenavn kan en lage NCName helautomatisk ved å høyreklikke på ei kodeliste, og velge Scripts/lagLovligeNCNavnPåKodelistekoder og trykke Ok. De gamle navnene flyttes til en tagged value "SOSI_presentasjonsnavn".

Endrede koder må alltid verifiseres etter automatisk endring. Dersom kodene er egennavn eller forkortelser bør de endres manuelt.

Egenskaper og roller som er opsjonelle ([0..1] og [0..*]) i fagområdet og er unødvendige i produktet kan fjernes fra klassene. Koder som ikke er relevante i produktet kan også fjernes. Velg klassen og så dens egenskaper, eller velg egenskapen direkte (velg kassen, og så klikk på egenskapen i diagrammet, høyreklikk og velg "Delete Selected From Model"):

Velg "Delete" på alle de unødvendige og opsjonelle egenskapene etter tur.

Trinn 10 Stram eventuelt inn på multiplisitetskravene på de resterende elementene.

Trinn 10 Stram eventuelt inn på multiplisitetskravene på de resterende egenskapene som alltid skal finnes og kunne være søkbare.

I fagområdene er de fleste egenskapene opsjonelle, men i et produkt bør en bestemme seg for å kreve verdier på flest mulig av egenskapen for alle objekter, slik at en bruker kan søke på disse verdiene og stole på at de ikke mangler noen steder. Da skal multiplisiteten på egenskapen endres fra [0..1] til eksakt antall [1..1]. (Påkrevede egenskaper vises uten [1..1], påkrevde roller vises med 1 eller 1..*.) Utfyllende føringer for hvordan man kan stramme inn kan finnes på: kartverket.no/globalassets/standard/retningslinjer-og-veiledere/retningslinjer-forholdet-objektkatalog-og-produktspesifikasjoner_2.0.pdf

Geometrityper med navn Punkt, Kurve eller Flate kan gjerne spesifiseres mer presist ved å endre disse til spesifikke iso-geometrityper. De enkleste av disse er GM_Point, GM_Curve og GM_Surface.

Trinn 11 Lag supertype som subsett av SOSI_Fellesegenskaper eller SOSI_Objekt og ta med ønskede fellesegenskaper.

Trinn 11 Lag supertype(r) som subsett av SOSI_Fellesegenskaper eller SOSI_Objekt, og ta med påkrevde og ønskede fellesegenskaper.

Lagre en kopi av pakka SOSI_Fellesegenskaper i SOSI Generelle typer 5.0 i klippebordet og lim kopien inn i din applikasjonsskjemapakke på samme måte som tidligere nevnt i punkt 7.

Flytt alle aktuelle klasser, datatyper og kodelister fra kopien av pakka SOSI-Fellesegenskaper opp til egen applikasjonsskjemapakke. Lag så en eller flere kopier av objekttypene SOSI_Fellesegenskaper og SOSI_Objekt med nye forståelige navn i applikasjonsskjemapakka. (Eks. Fellesegenskaper og FellesegenskaperKurver.)

Det aller enkleste er å ta med kun klassen SOSI_Fellesegenskaper og datatypen Identifikasjon. Dette sikrer at en oppfyller viktige krav i geodataloven. Hvis det er behov for flere fellesegenskaper kan SOSI_Objekt og andre klasser kopieres inn, og en utelater alle uønskede fellesegenskaper fra disse på samme måte som i punkt 9, og strammer inn opsjonaliteten på samme måte som i punkt 10.

Trinn 12 Legg inn at alle objekttyper arver fellesegenskaper.

Trinn 12 Legg inn at alle objekttyper arver definerte fellesegenskaper.

Velg verktøy for generalisering og trykk musepekeren ned på subtypen, dra over supertypen og slipp.

Korrekt angivelse av arv fra Fellesegenskaper skal da se slik ut:

Nye elementer

Trinn 13 Legg inn nye objekttyper og egenskaper som ikke finnes i fagområdene.

Trinn 13 Legg inn nye nødvendige objekttyper, assosiasjoner og egenskaper som ikke finnes i fagområdene fra før.

Følg beskrivelsene i SOSI del 1 Regler for UML-modellering versjon 5.1, og i tilsvarende ISO standarder for applikasjonsskjema og for bruk av UML. Benytt enklest mulig UML-modellelement til å beskrive det du har behov for. Her vises et lite sett av UML-modellelementer som det anbefales å benytte:

For å sikre at alle stereotyper og tagged values er i henhold til standardene bør SOSI-UML-profil 5.1 installeres og alltid benyttes når nye klasser skal lages. Eksisterende klasser med stereotype uten UML-profil eller fra eldre UML-profiler bør bytte til stereotype fra nyeste UML-profil. Ved bytte av UML-profiler må vi sikre at alle verdiene i tagged values videreføres. Nye modellelementer kan lages ved bruk av en standard UML-profil og ved bruk av ulike skript for innlegging av tagged values. Eksempel på innlegging av en helt ny egenskap som ikke finnes fra før til en eksisterende objekttype i fagområdet. Velg egenskaper, og velg "New Attribute", og fyll ut merkede felt for egenskapsnavn, datatype, synlighet og multiplisitet, legg inn definisjon, velg til slutt Close.

Enkle måter å lage helt nye elementer på er beskrevet i følgende seks trinn. Velg nytt diagramverktøy av typen SOSI UML profil 5.1, du får da en ny verktøykasse tilgjengelig.

Trinn 13.1 Ny applikasjonsskjemapakke med korrekt stereotype lages ved å velge verktøy fra verktøykassa under SOSI UML profil 5.1.

og klikke i et pakkediagram og skrive inn pakkenavnet.

Alle modellelementer skal ha en forståelig definisjon, også applikasjonsskjemapakker.

Trinn 13.2 Lag nye objekttyper, datatyper og kodelister ved å dra fra verktøykassa inn i et diagram. Fyll så ut den nye elementenes navn og definisjon (i Notes-feltet). Ny objekttype lages ved å velge FeatureType fra verktøykassa under SOSI UML profil 5.1 og klikke i et diagram.

Trinn 13.3 Lag nye egenskaper ved å velge objekttypen og klikke på Details/Attributes.

Legg inn egenskapens navn, datatype og at egenskapen er synlig (Public).

Skriv også inn den nye egenskapens definisjon i notefeltet, og sett ønsket multiplisitet.

Trinn 13.4 Lag ny assosiasjon ved å velge fra Class Relationships i standard verktøykassa og dra denne fra en objekttype til en annen.

Dobbeltklikk på assosiasjonen, velg SourceRole eller TargetRole (der endeklassen er den korrekte) og og skriv inn den nye rollens navn og definisjon, sett navigerbarhetspil og velg multiplisitet. Trykk så på OK

Trinn 13.5 Lag nye kodelister ved å dra ifra verktøykassa SOSI UML profil 5.1. Skriv inn kodelistens navn og definisjon og trykk OK.

Trinn 13.6 Lag nye kodeverdier ved å klikke på kodelisteklassen og velge Details → Attributes og skrive inn kodene. Husk at kodenes navn skal være NCName uten blanke og skilletegn. Typen skal være tom, <none> eller <undefined>. Alle koder skal ha forståelig definisjon. Trykk Close når ferdig.

Dersom kodelista eksisterer som en eksternt forvaltet fil eller et eksternt forvaltet register kan man la være å legge inn koder og heller angi http-URI til fila eller registeret. Dette gjøres ved å legge inn en gyldig http-URI i en tagged value codeList, og legge inn verdien true i en tagged value asDictionary.

Egenskaper som bruker denne kodelista som datatype bør i tillegg ha den samme http-URI-en i en egen tagged value defaultCodeSpace. Da vil denne http-URI-en kunne komme med i GML-Applikasjonsskjema ved bruk av encodingregel sosi under generering.

lage helt ny egenskapssti til ekstern kodeliste

I noen modelleringsvertøy eies tagged values av stereotypen finnes), og når en endrer eller fjerner slike stereotyper så fjernes tilhørende tagged values og alle inntastede verdier blir borte! En må derfor huske å deaktivere slike verktøy (som "MDG teknologi for SOSI") før en fjerner eller endrer på stereotyper. Dette gjelder særlig produktspesifikasjoner der nye egenskaper, koder og roller er laget fra grunnen av med den gamle verktøykassa "SOSI" i "MDG for SOSI". Alle modellene som hentes fra SOSI fagområder har unngått dette problemet.

Trinn 14 Legg inn påkrevede plattformuavhengige tagged values.

Trinn 14 Legg inn plattformuavhengige tagged values.

Applikasjonsskjemapakka skal ha noen få tagged values som er felles for alle plattformer. Disse kan legges in manuelt med standard EA menyer. Under vises eksempel med manuelt utfylte verdier.

Når en velger realiseringsformat og kjører skript for automatisk realisering (SOSI-format eller GML-format) vil de plattformuavhengige tagged values som mangler også legges inn automatisk sammen med alle de plattformspesifikke tagged values. I så fall kan denne innleggingen gjerne utsettes til punktene 22. og 25.

Kobling tilbake til fagområde

Trinn 15 Dokumenter i diagram hvordan objekttypene er realisert, og hva som er nytt.

Trinn 15 Dokumenter i diagram hvor objekttypene er realisert fra, hva som er tatt med og hva som er nytt.

Lag gjerne et eget eller flere klassediagram for dette, og gi det et navn slik som Realisering objekttyper eller Realisering havner. Dra alle produktets objekttyper og datatyper inn som linker i diagrammet for realisering. Finn den opprinnelige fagområdestandarden i prosjektbrowseren. dra så de objekttypene fra fagområdepakkene de er realisert ifra i SOSI del 2 inn rett over sin tilsvarende klasse.

Legg inn realiseringsforhold fra standard EA verktøkasse. Dette vil dokumentere hvilket subsett som er tatt med, og hvilke innstramminger og tillegg som er utført slik at fagområdestandardene kan forbedres ved neste revisjon.

Trinn 16 Dokumenter i diagram realisering av fellesegenskaper fra SOSI_Objekt.

Trinn 16 Dokumenter i et diagram realiseringen av fellesegenskaper fra SOSI_Fellesegenskaper og SOSI_Objekt.

En kan som vist i punkt 15 legge inn realiseringer til klasser i SOSI del 1 i et realiseringsdiagram og vise hvilke fellesegenskaper som er realisert.

Sluttbehandling

Trinn 17 Sjekk og re-etabler alle koblinger til korrekt datatype. Kjør modellvalidering.

Trinn 17 Re-etabler alle koblinger til korrekte datatyper og kjør validering.

Sjekk at alle objekttyper og datatyper er kopiert inn i applikasjonsskjemapakka. Alle klasser som benyttes skal finnes i denne pakka, med unntak av basistyper: (Integer, Real, Boolean, CharacterString, Date og DateTime, LanguageString, URI, Vector, Record,…) og geometrityper: (Flate, Kurve, Punkt, Sverm samt alle lovlige iso-geometrityper som GM_Point, GM_Curve, GM_Surface, GM_Solid og GM_Multi- og GM_Composite- varianter, GM_Object,…). Merk at UML-datatyper som int og string ikke er akseptable, og at "undefined" benyttes på kodelistekoder. Kontroll av at alle egenskaper er oppkoblet kan utføres helautomatisk ved å høyreklikke på pakka og velge Scripts/listDatatyperUtenOppkobling.

Oppkobling til datatyper innenfor egen applikasjonsskjemapakke der egenskapens datatypenavn tilsvarer en egendefinert datatypeklasse innenfor pakka kan utføres helautomatisk ved å høyreklikke på pakka og velge Scripts/kobleOppDatatyperFraSammeApplikasjonsskjema og trykke Ok.

kobleoppdatatyperfrasammeapplikasjonsskjema

Egenskaper med opplagte skrivefeil i datatype må selvfølgelig rettes manuelt. Objektegenskapenes datatyper skal kun peke til klasser i den samme pakka. Hvis man ser at det fortsatt pekes til nødvendige klasser i en annen pakke kan man først hente inn de manglende klassene, som beskrevet i punkt 6, og så gjenta dette punktet. Dersom produktspesifikasjonen har kopier av SOSI_Fellesegenskaper eller SOSI_Objekt kan det være ønskelig å fjerne alle kopier av realiseringsassosiasjonene som peker ut ifra disse klassene. Dette kan gjøres automatisk ved å velge klassen med fellesegenskaper i prosjektbrowseren og kjøre skript: Scripts/slettUtoverrettaRealiseringerFraKlasse Når alle eksterne avhengigheter er løst opp skal man til slutt fjerne alle de innkopierte pakkene som inneholder restene av ubrukte fagområdeobjekttyper og lignende. Validering av om modellelementene er akseptable konseptuelt utføres automatisk ved å laste ned og kjøre Addin SOSI-Model-Validation eller kjøre en gammel versjon ved å høyreklikke på applikasjonsskjemapakka i prosjektbrowseren og kjøre skript: Scripts/SOSI model validation.

Lagring av modellen

Trinn 18 Lagre den nye applikasjonsskjemapakka til et egnet register, som i SOSI-modellregisteret under SOSI-produktspesifikasjoner.

Trinn 18 Lagre den nye ferdige applikasjonsskjemapakka til SOSI modellregister under hoveddelen som heter SOSI Produktspesifikasjoner.

Det forutsettes her at du enten har fulgt konfigurasjonsanvisning i kapittel 5 slik at pakka allerede har blitt lagt til i SOSI modellregisteret på SVN-serveren, eller at du kan gjøre dette nå. Er arbeidet med UML-modellen (foreløpig) avsluttet husk å sende den oppdaterte modellen til serveren ved å sjekke inn pakka. Dersom du ønsker å vise klart og tydelig at pakka er uferdig kan pakkenavnet midlertidig endres med et forklarende tillegg som likner på "Havnetrafikk-5.0Utkast2016-03-23".

Høyreklikk på applikasjonsskjemapakka, velg så Package Control og Check In. Se eksempel nedenfor.

Husk å alltid skrive en kort og forståelig kommentar om hvilke endringene som er gjort inn i "Add Comment"-dialogboksen.

Har applikasjonsskjemapakka blitt sjekket inn riktig vil det være nøkkelsymbol foran pakkenavnet.

Husk også å sjekke inn din etats/ditt institutts pakke på samme måten i tilfellet du har sjekket den ut tidligere.

Dokumentere modellen

Trinn 19 Generer tekstlig dokumentasjon til produktspesifikasjonsdokumentet.

Trinn 19 Generer tekstlig dokumentasjon via tilrettelagt rapportmal.

Tip	Hvis du bruker AsciiDoc løypa, se Veileder for bruk av AsciiDoc til SOSI standarder og produktspesifikasjoner.

Dokumentasjonsmalen er lagret i fila SOSI_modellregister_JET40.eap. Den kan også lastes ned fra kartverket.no. Beskrivelse av hvordan disse filene er laget ligger i installasjonsveiledningen. Generer word-dokument ved å høyreklikke på applikasjonsskjemapakka i prosjektbrowseren og velge "Documentation → Generate Documentation":

Velg fra lista Template: SOSI dokumentasjonsmal 2020 1.0 og Format: DOCX, og angi filnavn for resultat, trykk så Generate.

Trinn 20 Klipp andre aktuelle rapporter inn i produktspesifikasjonsdokumentet.

Trinn 20 Klipp alle aktuelle rapporter inn i produktspesifikasjonsdokumentet.

Lim inn hele den genererte fila som informasjonsmodell under kapittel 5 i produktspesifikasjonen. Lesbarheten av produktspesifikasjonen vil forbedres vesentlig dersom en i siste iterasjonsrunde redigerer kapittel 5 i dokumentet manuelt og legger inn informative figurer og bilder som forklarer modellelementene ytterligere. Kvalitetssikring av produktspesifikasjonsdokumentet bør avtalefestes. Dette kan avtales med Kartverket ved epost til post@norgedigitalt.no merket SOSI-produktspesifikasjon.

Melde inn mangler i fagområdene

Trinn 21 Meld inn til standardiseringssekretariatet behov om elementer som manglet i fagområdene, for oppdatering av fagområdestandardene i SOSI del 2.

Trinn 21 Meld inn til standardiseringssekretariatet om behov om nye objekttyper eller modellelementer som mangler i fagområdene, for bedre å kunne oppdatere SOSI generell objektaktalog.

Dersom det ble behov for å legge inn nye objekttyper eller andre nye modellelementer i en eksisterende objekttype, eller dersom feil ble oppdaget må det startes en etterprosess med å tilbakeføre disse endringene til standardene for de generelle fagområdene i SOSI del 2. Dette meldes til mailto:standardiseringssekretariatet@kartverket.no

Generere SOSI-realisering og SOSI-kontrollfiler

Trinn 22 Legg inn innhold i tagged values for bl.a. SOSI_kortnavn og SOSI_navn.

Trinn 22 Kontroller at tagged values for alle SOSI_navn og SOSI_lengde er lagt inn.

Skriptet Scripts/realiserbarSOSIformat50 går gjennom alle aktuelle modellelementer og sjekker at den finner alle påkrevde tagged values for realisering i SOSI-format versjon 5.0. Mange eldre fagområdestandarder har allerede slike tagged values for SOSI-format. Taggenes innhold må inspiseres og eventuelt korrigeres manuelt.

Manglende tagged values kan legges inn helautomatisk ved å høyreklikke på applikasjonsskjemapakka og velge Scripts/leggInnSOSIformat50Tagger og trykke Ok. Disse taggenes verdier må manuelt sjekkes og eventuelt rettes etterpå. Eksisterende tagged values blir ikke berørt. Merk at fagområdemodellene kan inneholde mange flere, og til dels komplekse tagged values laget for eldre SOSI-format-støtte. Disse kan ignoreres.

Trinn 23 Generer SOSI-Kontrollfiler for validering av data.

Trinn 23 Generer SOSI-Kontrollfiler.

Viktige tagged values som må være satt for applikasjonsskjemapakka er: * Verdien av tagged value "SOSI_kortnavn" brukes bl.a. som filnavn ulike steder (eks Planomriss-48) og skal derfor ikke inneholde blanke eller skilletegn. * Verdien av tagged value "SOSI_versjon" skal angi hviken hovedversjon formatrealiseringen bygger på (eks. 4.5 eller 5.0). * Verdien av tagged value "SOSI_modellstatus" skal angi om modellen er komplett og godkjent (gyldig), eller ikke (utkast). For SOSI-format versjon 5.0 kan man høyreklikke på applikasjonsskjemapakka og velge Scripts/listSOSIKontrollfiler. Skriptet spør deretter om bekreftelse på kortnavnet og viser meldinger i systemvinduet når den angitte katalogstrukturen er laget. For generering av SOSI-format versjon 4.x kan man høyreklikke på applikasjonsskjemapakka og velge Extensions/SOSI/definisjonsfiler for SOSI-Kontroll.

Dersom en får denne meldingen om at modellen ikke er gyldig så trykk da ubekymret og ufortrødent på Yes for å fortsette. (Testen der er ikke korrekt.)

Det kan ha kommet andre inn meldinger i systemloggvinduet nederst. Disse kan indikere at modellvalideringen på slutten av punkt 17 bør kjøres pånytt. Det vil komme opp en egen katalog der definisjonsfilene er lagret.

Innholdet i den genererte katalogen kan benyttes direkte i SOSI-Kontroll til å teste mot reelle SOSI-formaterte data. Oppdages det feil på dette stadiet kan det eventuelt være nyttig å gå tilbake til modellen og forbedre og tilpasse denne til å beskrive de tilgjengelige datakilder. For å få produktet inn i distribusjon av det offisielle settet med SOSI-Kontrollfiler må en lagre den ferdige applikasjonsskjemapakka tilbake i SOSI modellregister, og melde ifra i epost til Kartverkets post@norgedigitalt.no merket SOSI-Kontroll om at datafiler skal kunne valideres mot dette produktets applikasjonsskjema. Filene vil da genereres og testes, og publiseres til alle brukere av SOSI-kontroll.

Trinn 24 Generer SOSI-syntaks og klipp den inn i produktspesifikasjonsdokumentet.

Trinn 24 Generer SOSI-formatbeskrivelse og legg denne inn i produktspesifikasjonsdokumentet.

For modeller etter versjon 5.0 kan man høyreklikke på applikasjonsskjemapakka og velge "Generate Documentation": Velg Template: SOSI-formatbeskrivelse og Format: RTF-format, og angi filnavn for resultat, trykk så Generate. TBD For modeller etter versjon 4.x kan man høyreklikke på applikasjonsskjemapakka og velge Extensions/SOSI/SOSI-formatrealisering.

Etter en tid vil det komme opp melding om at et dokument er produsert.

Merk og kopier alt innhold i det produserte dokumentet, og lim det inn i produktspesifikasjonsdokumentet under kapittel 11 eller i et eget vedlegg for SOSI-formatrealisering. Se etter felter som inneholder FIX og om alt ellers er komplett.

Generere GML-realisering

Trinn 25 Legg inn nødvendige GML-skjema-metadata som tagged values på pakka.

Trinn 25 Legg inn nødvendige GML-skjema-metadata som tagged values på applikasjonsskjemapakka.

Skriptet Scripts/realiserbarGML50 går gjennom alle aktuelle modellelementer i applikasjonsskjemapakka og sjekker at det finner alle tagged values som er påkrevde for realisering i GML (SOSI-GML versjon 5.0). Navn på navnerom, versjonsnummer og skjemafil må bestemmes og ligge som tagged values i EA. Disse tagged values kan legges inn helautomatisk med forslag til verdier ved å høyreklikke på applikasjonsskjemapakka og velge Scripts/leggInnGMLformatTagger.

UML og GML benytter utf-8, og er derfor mulig å bruke de norske tegnene æøå i navnerom og skjemafiler, og unngå unødig translitterering og misforståelser. Dersom man har andre verktøy som ikke støtter utf-8 bør disse verktøyene oppgraderes til nyere versjoner, eller byttes ut med verktøy som støtter utf-8.

Verdien av tagged value "targetNamespace" skal inneholde navnet på navnerommet. Disse ender vanligvis med et versjonsnummer (eks. /5.0). http://skjema.geonorge.no/SOSI/produktspesifikasjon/Havnetrafikk/5.0

Verdien av tagged value "version" skal inneholde detaljert versjonsinformasjon. Merk at dette detaljerte versjonsnummeret (eks. "5.0.0beta5") kun vil ligge inne i skjemafila. Det bør likevel henge logisk tett sammen med hovedversjonsnavnet som er siste ledd i navneromsnavnet (/5.0).

Verdien av tagged value "xmlns" er en lokal forkortelse for navnerommet i GML-applikasjonsskjemaet, og alle bør benytte "app".

Verdien av tagged value "xsdDocument" skal inneholde filnavnet på skjemafila.

Verdien av tagged value "xsdEncodingRule" skal være "sosi50" for modeller etter 5.0-regler, eller "sosi" for eldre modeller. Dette regelsettet inneholder en nasjonal utvidelse av standardencodingen (som angis med "iso19136_2007").

Navnet på navnerommet skal også benyttes som sti til skjemaplasseringen, så skjemafila skal ligge tilgjengelig der, for eksempel: http://skjema.geonorge.no/SOSI/produktspesifikasjon/Havnetrafikk/5.0/ Havnetrafikk-5.0.xsd og eventuelle eksternt forvaltede kodelister skal ligge tilgjengelig på samme sted, for eksempel: http://skjema.geonorge.no/SOSI/produktspesifikasjon/Havnetrafikk/5.0/Sjørestriksjon.xml

Dersom eksternt forvaltede kodelister skal benyttes i GML så må disse kodelistene merkes spesielt i modellen, med en tagged value "asDictionary" med verdien "true" og en tagged value "codeList" med verdi som er stien til der den autoritative kodelista skal ligge. (codeSpace) Dette bør også dokumenteres eksplisitt i produktspesifikasjonsdokumentet. Det er vanlig å angi full sti pluss kodelistenavnet, men ikke angi filtype (.gml for GML eller .rdf for SKOS). Eksempel på fragment fra ei GML-datafil med kode fra en gml:Dictionary:

Trinn 26 Generer GML-applikasjonsskjema med ShapeChange i Enterprise Architect.

Trinn 26 Generer GML-applikasjonsskjema med ShapeChange via plugginn i Enterprise Architect.

Kjøring av ShapeChange mot den fulle fila SOSI_modellregister_JET40.eap vil kunne ta flere timer fordi ShapeChange leser gjennom alle pakkene i prosjektfila selv om de ikke er valgt. Det er kun ShapeChange som har dette problemet, de andre verktøyene bør alle kjøres direkte mot pakker i modellregisteret. Før GML-skjemaet genereres, anbefales det derfor innstendig å kopiere hele applikasjonsskjemapakka til ei ny, tom EA-prosjektfil. Hensikten med det er å redusere tiden ShapeChange bruker for å generere GML-skjema. Samtidig vil eventuelle feilmeldinger under genereringsprosessen kun gjelde den valgte applikasjonsskjemapakka vi er interessert i og ikke eventuelle andre pakker som befinner seg i samme EA-prosjekt. Merk at dersom samiske tegn forekommer i elementnavn så må en eap-startfil være oppdatert for å kunne handtere dette, se beskrivelsen under første punkt i sosi.geonorge.no/SVNFAQ. For å kopiere pakka skal du høyreklikke på applikasjonsskjemapakka, velg Copy/Paste – Copy to Clipboard – Full Structure for Duplication, åpne så et nytt EA-prosjekt (File  New Project). I det nye prosjektet høyreklikker du i på Model i Project Browser og velger (Copy/Paste -) Paste Package from Clipboard. Generer GML-applikasjonsskjema ved å høyreklikke på applikasjonsskjemapakka og velge: Extensions/ShapeChange/Transform…

Sørg for å hake av for generering av eksterne kodelister dersom slike finnes i modellen. Kontroller at pakkeinformasjonen er korrekt og trykk på Transform.

Feilmeldinger vil bli dokumentert i verktøydokumentasjonen under generering. Etter generering kan loggen gjennomgåes for å finne evt. gjenværende feil i modellen. Loggen etter generering ligger i log.xml og log.html, og disse kan finnes på samme katalogen som der modellfila ligger. GML-applikasjonsskjemafila legges vanligvis på en underkatalog \XSD\INPUT og eksterne kodelister som gml:Dictionary legges på en annen underkatalog \CL\INPUT.

Kodelistefiler kan også genereres enkeltvis ved å velge en enkelt kodeliste og kjøre Script/listSKOSfraKodeliste og Script/listGMLDICTfraKodeliste. Genererte filer vil da lages på samme sted som .eap-fila ligger.

Trinn 27 Lag og valider eksempel på GML-datasett som følger produktspesifikasjonen.

Trinn 27 Legg inn et eksempel på gyldige GML data i produktspesifikasjonen.

Det anbefales at et pedagogisk eksempeldatasett lages og valideres mot skjemaet, og til slutt legges inn under kapittel 11. GML-realisering i produktspesifikasjonsdokumentet, eller også i eget vedlegg. Slike dataeksempler bør lages tidlig i modelleringen da disse ofte vil initiere forbedringer i modellen.

Kjør Script/listGMLExample og kopier resultatet i vinduet System Output til en editor som støtter utf-8.

Trinn 28 Legg inn GML-applikasjonsskjema på angitt skjemaplassering.

Trinn 28 Legg inn GML applikasjonsskjema på angitt skjemalokalisering.

For publisering kan GML-applikasjonsskjemaet sendes til: mailto:standardiseringssekretariatet@kartverket.no En versjon som er uferdig og åpen for videreutvikling kan legges på: http://skjema.dev.geonorge.no/SOSI/produktspesifikasjon/ eller i en angitt periode for åpen test mot reelle datasett legges den på: http://skjema.test.geonorge.no/SOSI/produktspesifikasjon/ for å bli endelig publisert som gyldig og autoritativt GML-applikasjonsskjema på: http://skjema.geonorge.no/SOSI/produktspesifikasjon/.

Skjemaplassering kan også benyttes til publisering av eksempeldata, disse skal da navnes og legges slik: http://skjema.geonorge.no/SOSI/produktspesifikasjon/Havnetrafikk/5.0/eksempel/Oslo.gml Skjemaene kan brukes direkte til konfigurering av WFS-tjenester og til oppsett av PostGIS databaser og lignende. Kvalitetssikring av GML-datasett og WFS-tjenester som følger produktets GML-applikasjonsskjema bør avtalefestes. Dette kan avtales med Kartverket ved å sende en epost til post@norgedigitalt.no merket WFS-tjeneste.

Trinn 29 Legg inn URI og URL til GML-applikasjonsskjema i produktspesifikasjonen.

Trinn 29 Legg inn varig http-URI og tilsvarende URL til GML-applikasjonsskjema i produktspesifikasjonen.

Dette legges inn i produktspesifikasjonsdokumentet under kapittel 11:

http-URI for navnerom: http://skjema.geonorge.no/SOSI/produktspesifikasjon/Havnetrafikk/5.0

URL til GML-applikasjonsskjema: http://skjema.geonorge.no/SOSI/produktspesifikasjon/Havnetrafikk/5.0/Havnetrafikk-5.0.xsd

URL til kodeliste: http://skjema.geonorge.no/SOSI/produktspesifikasjon/Havnetrafikk/5.0/Politidistrikt.skos.rdf

URL til GML-eksempeldatasett: http://skjema.geonorge.no/SOSI/produktspesifikasjon/Havnetrafikk/5.0/eksempel