Petter Reinholdtsen

Entries tagged "noark5".

Oppdatert Noark 5 Tjenestegrenesnitt versjon 1.0 for Noark 5.5.0
5th July 2019

Jeg er veldig glad for å kunne fortelle at i går ble ny versjon av API-spesifikasjonen for Noark 5 Tjenestegrensesnitt gitt ut. Det så lenge mørkt ut for sjansene for å få inn nødvendige korreksjoner i spesifikasjonsteksten innen rimelig tid, men takket være intens og god innsats fra Mona og Anne Sofie hos Arkivverket de siste ukene, så ble resultatet som ble gitt ut på USAs uavhengighetsdag mye bedre enn jeg fryktet.

Spesifikasjonen er tilgjengelig som markdown-filer i Arkivverkets github-prosjekt for dette, og de aller fleste av forslagene til forbedringer fra oss som holder på med Nikita-prosjektet kom med i denne nye og oppdaterte spesifikasjonsteksten. Det er fortsatt mye som gjenstår før den er entydig, klar og sikrer samvirke på tvers av leverandører, men utgangspunktet er veldig mye bedre enn forrige versjon fra 2016. Ta gjerne en titt.

Ellers må jeg jo si at det var hyggelig å se at min forrige bloggpost om tjenestegrensesnittet fikk en lenke fra Arkivverket Beta.

Som vanlig, hvis du bruker Bitcoin og ønsker å vise din støtte til det jeg driver med, setter jeg pris på om du sender Bitcoin-donasjoner til min adresse 15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b. Merk, betaling med bitcoin er ikke anonymt. :)

Tags: noark5, norsk, standard.
Nikita og Noark 5 tjenestegrensesnittet tilbyr ny måte å tenke arkivering
21st June 2019

av Thomas Sødring (OsloMet) og Petter Reinholdtsen (foreningen NUUG)

Nikita Noark 5-kjerne er et fri programvareprosjekt som tar i bruk Arkivverkets spesifikasjonen for Noark 5 Tjenestegrensesnitt og tilbyr et maskinlesbart grensesnitt (arkiv-API) til datasystemer som trenger å arkivere dokumenter og informasjon. I tillegg tilbyr Nikita et nettleserbasert brukergrensesnitt for brukere av arkivet. Dette brukergrensesnittet benytter det maskinlesbare grensesnittet. Noark 5 Tjenestegrensesnitt er en ny måte å tenke arkivering, med fokus på automatisering og maskinell behandling av arkivmateriale, i stedet for å fokusere på brukergrensesnitt. En kan tenke på tjenestegrensesnittet som arkivet uten brukergrensesnitt, der flere aktører kan koble til ulike brukergrensesnitt, tilpasset ulike behov.

Historisk sett gjorde Noark standarden en veldig bra jobb med overgangen fra papir til digital saksbehandling, men det har kommet til kort på andre områder. Den teknologiske utviklingen har brakt oss ditt at vi kan og skal forvente langt mer fra en arkivkjerne enn før, men det offentlig er ofte konservativ når det gjelder nytenking. For lengst skulle begreper som samvirke mellom datasystemer, metadata, prosess og tjenestegrensesnitt (API) vært dominerende når systemer kjøpes inn. Dessverre er det slik at ikke alle ønsker samvirke mellom datasystemer velkommen, og det kan være trygt å kjøpe «svarte bokser» der du slipper å ta stilling til hvordan man skal få flere systemer til å virke sammen. Men IT-arkitektur er et begrep arkivfolk også begynner å ta inn over seg.

Slike systemer for å organisere metadata bør ha nettbaserte tjenestegrensesnitt der brukergrensesnitt er tydelig adskilt fra bakenforliggende system. Det finnes mange rapporter som snakker om å bryte ned siloer i forvaltningen og standardiserte tjenestegrensesnitt er det viktigste virkemiddel mot datasiloer og legger til rette for økt samvirke mellom systemer. Et standardisert tjenestegrensesnitt er et viktig middel for å få systemer til å samhandle da det sikrer at ulike produsenters systemer kan snakke sammen på tvers. Samfunnet fungerer ikke uten standardisering. Vi har alle samme strømstyrke og kontakter i veggene og kjører alle på høyre side av veien i Norge. Det er i en slik sammenheng at prosjektet «Noark 5 Tjenestegrensesnitt» er veldig viktig. Hvis alle leverandører av arkivsystemer forholdt seg til et standardisert tjenestegrensesnitt kunne kostnadene for arkivering reduseres. Tenk deg at du er en kommune som ønsker et fagsystem integrert med arkivløsningen din. I dag må fagsystemleverandøren vite og tilpasse seg den spesifikke versjonen og varianten av arkivløsningen du har. Hvis vi antar at alle leverandører av arkivkjerner har solgt inn enten SOAP eller REST-grensesnitt til kunder de siste 10 årene og det kommer endret versjon av grensesnittet innimellom, så gir det veldig mange forskjellige tjenestegrensesnitt en fagsystemleverandør må forholde seg til. Med 12 leverandører og kvartalsvise oppdateringer kan det potensielt bli 96 ulike varianter hvert eneste år. Det sier seg selv at det blir dyrt. Men det blir faktisk verre. Hvis du senere ønsker å bytte ut arkivsystemet med et annet så er du avhengig å få alle integrasjonene dine laget på nytt. Dette kan gjøre at du velger å forbli hos en dårlig leverandør framfor å skaffe nytt system, fordi det blir for vanskelig og dyrt å bytte. Dermed etableres det «små» monopolsituasjoner som er vanskelig å bryte ut av. Dårlige valg i dag kan ha uante kostander på sikt. I Nikita-prosjektet har vi kun jobbet opp mot Noark 5 Tjenestegrensesnittet. Det har tatt en god del ressurser å sette seg inn i spesifikasjonen og ta den i bruk, spesielt på grunn av uklarheter i spesifikasjonen. Hvis vi måtte gjøre det samme for alle versjoner og varianter av de forskjellige tjenestegrensesnittene ville det blitt veldig tidkrevende og kostbart.

For deg som arkivar er digitalisering og systemer som skal virke sammen en del av den nye hverdagen. Du har kanskje blitt skånet for det ved å kjøpe svarte bokser, men du risikerer at du gjør deg selv en bjørnetjeneste. Det kan oppleves som kjedelig å fortelle kolleger at du skal sette deg inn i et tjenestegrensesnitt, men dette er faktisk veldig spennende. Tjenestegrensesnittet er på en måte blitt levende og det er spesielt et begrep du bør merke deg: OData. Å trekke inn deler av OData-standarden som en måte å filtrere entitetsøk i et arkivsystem var et nyttig trekk i prosjektet. Følgende eksempel er en OData-spørring det går an å sende inn til en standardisert arkivkjerne:

.../sakarkiv/journalpost?filter=contains(tittel, 'nabovarsel')

Spørringen over vil hente en liste av alle dine journalposter der tittelen til journalposten inneholder ordet 'nabovarsel'. Alle leverandører som implementerer tjenestegrensesnittet vil måtte tilby dette. Det betyr at hvis du lærer dette språket for et system, vil det være gjeldende for alle. Dette er egentlig en ny måte å søke i arkivdatabasen på og vil være svært nyttig, for eksempel kan søk i tjenestegrensesnittet antagelig brukes til å hente ut offentlig postjournal. I arkivverden pleier vi å like teknologier som er menneskelesbart, da vet vi det er enkelt og nyttig! OData er også viktig fordi det kan bli en ny måte å svare innsynsforespørsler på i tråd med offentlighetsloven § 9, der retten til å kreve innsyn i sammenstilling fra databaser er nedfelt. I dag ser vi forvaltningsorganer som avviser slike krav fordi det «ikke kan gjøres med enkle framgangsmåter». Bruken av OData i tjenestegrensesnittet, sammen med maskinlesbar markeringsformater kan være et viktig bidrag til å åpne arkivene i tråd med prinsippene om en åpen og transparent forvaltning.

Standardisering er viktig fordi det kan sikre samvirke. Men den effekten kommer kun hvis standardiseringen sikrer at alle forstår standarden på samme måte, dvs. at den er entydig og klar. En god måte å sikre en entydig og klar spesifikasjon er ved å kreve at det finnes minst to ulike implementasjoner som følger spesifikasjonen og som kan snakke sammen, det vil si at de snakker samme språk, slik IETF krever for alle sine standarder, før spesifikasjonen anses å være ferdig. Tilbakemelding fra miljøet forteller at både leverandører og kunder har et avslappet forhold til Noark 5 Tjenestegrensesnitt og det er så langt kun Evry som har visst offentlig at de har en implementasjon av tjenestegrensesnittet. Evry, HK Data og Fredrikstad kommune er igang med et pilotprosjekt på Noark 5 Tjenestegrensesnitt. For å redusere kostnadene for samvirkende datasystemer betraktelig, er det veldig viktig at vi kommer i en situasjon der alle leverandører har sine egne implementasjoner av tjenestegrensesnittet, og at disse oppfører seg likt og i tråd med det som er beskrevet i spesifikasjonen.

Det er her fri programvare spiller en viktig rolle. Med en uklar standard blir det som en polsk riksdag, der ingenting fungerer. Nikita er en fri programvareimplementasjon av tjenestegrensesnitt og kan fungere som teknisk referanse slik at leverandører enklere kan se og forstå hvordan standarden skal tolkes. Vi har i Nikitaprosjektet erfart å ende opp med vidt forskjellige tolkninger når prosjektmedlemmene leser spesifikasjonsteksten, en effekt av en uklar spesifikasjon. Men Nikitaprosjektet har også utviklet et test-program som sjekker om et tjenestegrensesnitt er i samsvar med standarden, og prosjektet bruker det hele tiden for å sikre at endringer og forbedringer fungerer. Egenerklæringsskjemaenes dager kan være talte! Snart vil du selv kunne teste hver oppdatering av arkivsystemet med en uavhengig sjekk.

Fri programvare representerer en demokratisering av kunnskap der tolkning- og innlåsingsmakt flyttes fra leverandør til allmenheten. Med fri programvare har du en litt annerledes verdikjede, der selve produktet ikke holdes hemmelig for å tjene penger, slik en gjør med ufri programvare og skytjenester som ikke bruker fri programvare, men du kan tjene penger på andre deler av verdikjeden. Med fri programvare kan samfunnet betale for å videreutvikle nyttig fellesfunksjonalitet.

Nikita er en fri programvareimplementasjon av tjenestegrensesnittet og kan fungere som en referanseimplementasjon dersom det er ønskelig. Alle har lik tilgang til koden og det koster ingenting å ta den i bruk og utforske det. Nikitaprosjektet ønsker tjenestegrensesnittet velkommen og stiller veldig gjerne opp i diskusjoner om tolkning av tjenestegrensesnittet. Nikita er bygget på moderne programmeringsrammeverk og utviklet i full åpenhet. Men Nikita er ikke noe du kan kjøpe. Nikita er først og fremst et verktøy for forsking og utvikling laget for å fremme forskning på arkivfeltet. Systemer som virker sammen har alltid vært hovedfokus og vil være det fremover. Det brukes som undervisningsverktøy der studentene ved OsloMet lærer om administrativt oppsett, saksbehandling, uttrekk og samvirkende datasystemer. Det brukes også som forskningsobjekt der vi ser på import av dokumentsamlinger, bruk av blokkjede og andre nyskapende måter å tenke arkiv på. Det er dog helt greit om andre tar Nikita og pakker det for å selge det som produkt. Forvaltningsorganer med sterke drift- og utviklingsmiljøer kan også se på Nikita og utforske hva som er mulig. Dette kan de gjøre uten å måtte betale for bruksrettigheter eller tilgang til konsulenter. Men arkivering blir ikke gratis på grunn av Nikita. Det trengs fortsatt folk med kompetanse og tid til å ta i bruk Nikita.

Nikita har nylig kommet med en ny utgave, den sjette i rekken. Systemet er ikke ferdig, mest på grunn av at API-spesifikasjonen for Noark 5 Tjenestegrensesnitt ikke er ferdig, men allerede i dag kan en bruke Nikita som arkiv. Vi har laget eksempelsystem for å importere data fra deponi-XML og slik gjøre eksisterende arkivdata tilgjengelig via et API. Vi har også laget en testklient som importerer epost inn i arkivet med vedlegg der epostenes trådinformasjon brukes til å legge eposttråder i samme arkivmappe, og en annen testklient som henter epost ut av en arkivmappe på mbox-format slik at en vanlig epostklient kan brukes til å lese igjennom og svare på epostene i en arkivmappe. De som vil ta en titt på Nikita kan besøke https://nikita.oslomet.no og logge inn med brukernavn «admin@example.com» og passord «password». Dette gir tilgang til det forenklede brukergrensesnittet som brukes til undervisning. De som heller vil ta en titt under panseret kan besøke https://nikita.oslomet.no/browse.html og der se hvordan API-et fungerer mer i detalj. Innloggingsdetaljer her er det samme som for brukergrensesnittet.

Fremover er fokuset på forbedring av spesifikasjonen Noark 5 Tjenestegrensesnitt. De som skrev tjenestegrensesnittet gjorde et interessant og framtidsrettet grep, de skilte sak fra arkiv. Tjenestegrensesnittet består av flere "pakker", der noen er grunnleggende mens andre bygger på de grunnleggende pakkene. Pakkene som er beskrevet så langt heter «arkivstruktur», «sakarkiv», «administrasjon», «loggogsporing» og «moeter» (dessverre planlagt fjernet i første utgave). Etter hvert håper vi å utforske prosses- og metadatabeskrivelser til flere fagområder og bidra til at tjenestegrensesnittet kan legge til flere pakker som «byggarkiv», «barnevern», «personal», «barnehage», der arkivfaglig metadata- og dokumentasjonsbehov er kartlagt og standardisert.

Nikita utvikles av en liten prosjektgruppe, og vi er alltid interessert å bli flere. Hvis en åpen, fri og standardisert tilnærming til arkivering høres interessant ut, bli med oss på veien videre. Vi er tilstede på IRC-kanalen #nikita hos FreeNode (tilgjengelig via nettleser på https://webchat.freenode.net?channels=#nikita), og har en e-postliste nikita-noark@nuug.no hos NUUG (tilgjengelig for påmelding og arkiv på https://lists.nuug.no/mailman/listinfo/nikita-noark) der en kan følge med eller være med oss på den spennende veien videre. Spesifikasjonen for Noark 5 Tjenestegrensesnitt vedlikeholdes på github, https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/.

Som vanlig, hvis du bruker Bitcoin og ønsker å vise din støtte til det jeg driver med, setter jeg pris på om du sender Bitcoin-donasjoner til min adresse 15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b.

Tags: noark5, norsk, standard.
Official MIME type "text/vnd.sosi" for SOSI map data
4th June 2019

Just 15 days ago, I mentioned my submission to IANA to register an official MIME type for the SOSI vector map format. This morning, just an hour ago, I was notified that the MIME type "text/vnd.sosi" is registered for this format. In addition to this registration, my file(1) patch for a pattern matching rule for SOSI files has been accepted into the official source of that program (pending a new release), and I've been told by the team behind PRONOM that the SOSI format will be included in the next release of PRONOM, which they plan to release this summer around July.

I am very happy to see all of this fall into place, for use by the Noark 5 Tjenestegrensesnitt implementations.

As usual, if you use Bitcoin and want to show your support of my activities, please send Bitcoin donations to my address 15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b.

Tags: english, kart, noark5, standard.
Nikita version 0.4 released - free software archive API server
22nd May 2019

This morning, a new release of Nikita Noark 5 core project was announced on the project mailing list. The Nikita free software solution is an implementation of the Norwegian archive standard Noark 5 used by government offices in Norway. These were the changes in version 0.4 since version 0.3, see the email link above for links to a demo site:

If free and open standardized archiving API sound interesting to you, please contact us on IRC (#nikita on irc.freenode.net) or email (nikita-noark mailing list).

As usual, if you use Bitcoin and want to show your support of my activities, please send Bitcoin donations to my address 15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b.

Tags: english, noark5, nuug, offentlig innsyn, standard.
MIME type "text/vnd.sosi" for SOSI map data
20th May 2019

As part of my involvement in the work to standardise a REST based API for Noark 5, the Norwegian archiving standard, I spent some time the last few months to try to register a MIME type and PRONOM code for the SOSI file format. The background is that there is a set of formats approved for long term storage and archiving in Norway, and among these formats, SOSI is the only format missing a MIME type and PRONOM code.

What is SOSI, you might ask? To quote Wikipedia: SOSI is short for Samordnet Opplegg for Stedfestet Informasjon (literally "Coordinated Approach for Spatial Information", but more commonly expanded in English to Systematic Organization of Spatial Information). It is a text based file format for geo-spatial vector information used in Norway. Information about the SOSI format can be found in English from Wikipedia. The specification is available in Norwegian from the Norwegian mapping authority. The SOSI standard, which originated in the beginning of nineteen eighties, was the inspiration and formed the basis for the XML based Geography Markup Language.

I have so far written a pattern matching rule for the file(1) unix tool to recognize SOSI files, submitted a request to the PRONOM project to have a PRONOM ID assigned to the format (reference TNA1555078202S60), and today send a request to IANA to register the "text/vnd.sosi" MIME type for this format (referanse IANA #1143144). If all goes well, in a few months, anyone implementing the Noark 5 Tjenestegrensesnitt API spesification should be able to use an official MIME type and PRONOM code for SOSI files. In addition, anyone using SOSI files on Linux should be able to automatically recognise the format and web sites handing out SOSI files can begin providing a more specific MIME type. So far, SOSI files has been handed out from web sites using the "application/octet-stream" MIME type, which is just a nice way of stating "I do not know". Soon, we will know. :)

As usual, if you use Bitcoin and want to show your support of my activities, please send Bitcoin donations to my address 15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b.

Tags: english, kart, noark5, standard.
PlantUML for text based UML diagram modelling - nice free software
25th March 2019

As part of my involvement with the Nikita Noark 5 core project, I have been proposing improvements to the API specification created by The National Archives of Norway and helped migrating the text from a version control system unfriendly binary format (docx) to Markdown in git. Combined with the migration to a public git repository (on github), this has made it possible for anyone to suggest improvement to the text.

The specification is filled with UML diagrams. I believe the original diagrams were modelled using Sparx Systems Enterprise Architect, and exported as EMF files for import into docx. This approach make it very hard to track changes using a version control system. To improve the situation I have been looking for a good text based UML format with associated command line free software tools on Linux and Windows, to allow anyone to send in corrections to the UML diagrams in the specification. The tool must be text based to work with git, and command line to be able to run it automatically to generate the diagram images. Finally, it must be free software to allow anyone, even those that can not accept a non-free software license, to contribute.

I did not know much about free software UML modelling tools when I started. I have used dia and inkscape for simple modelling in the past, but neither are available on Windows, as far as I could tell. I came across a nice list of text mode uml tools, and tested out a few of the tools listed there. The PlantUML tool seemed most promising. After verifying that the packages is available in Debian and found its Java source under a GPL license on github, I set out to test if it could represent the diagrams we needed, ie the ones currently in the Noark 5 Tjenestegrensesnitt specification. I am happy to report that it could represent them, even thought it have a few warts here and there.

After a few days of modelling I completed the task this weekend. A temporary link to the complete set of diagrams (original and from PlantUML) is available in the github issue discussing the need for a text based UML format, but please note I lack a sensible tool to convert EMF files to PNGs, so the "original" rendering is not as good as the original was in the publised PDF.

Here is an example UML diagram, showing the core classes for keeping metadata about archived documents:

@startuml
skinparam classAttributeIconSize 0

!include media/uml-class-arkivskaper.iuml
!include media/uml-class-arkiv.iuml
!include media/uml-class-klassifikasjonssystem.iuml
!include media/uml-class-klasse.iuml
!include media/uml-class-arkivdel.iuml
!include media/uml-class-mappe.iuml
!include media/uml-class-merknad.iuml
!include media/uml-class-registrering.iuml
!include media/uml-class-basisregistrering.iuml
!include media/uml-class-dokumentbeskrivelse.iuml
!include media/uml-class-dokumentobjekt.iuml
!include media/uml-class-konvertering.iuml
!include media/uml-datatype-elektronisksignatur.iuml

Arkivstruktur.Arkivskaper "+arkivskaper 1..*" <-o "+arkiv 0..*" Arkivstruktur.Arkiv
Arkivstruktur.Arkiv o--> "+underarkiv 0..*" Arkivstruktur.Arkiv
Arkivstruktur.Arkiv "+arkiv 1" o--> "+arkivdel 0..*" Arkivstruktur.Arkivdel
Arkivstruktur.Klassifikasjonssystem "+klassifikasjonssystem [0..1]" <--o "+arkivdel 1..*" Arkivstruktur.Arkivdel
Arkivstruktur.Klassifikasjonssystem "+klassifikasjonssystem [0..1]" o--> "+klasse 0..*" Arkivstruktur.Klasse
Arkivstruktur.Arkivdel "+arkivdel 0..1" o--> "+mappe 0..*" Arkivstruktur.Mappe
Arkivstruktur.Arkivdel "+arkivdel 0..1" o--> "+registrering 0..*" Arkivstruktur.Registrering
Arkivstruktur.Klasse "+klasse 0..1" o--> "+mappe 0..*" Arkivstruktur.Mappe
Arkivstruktur.Klasse "+klasse 0..1" o--> "+registrering 0..*" Arkivstruktur.Registrering
Arkivstruktur.Mappe --> "+undermappe 0..*" Arkivstruktur.Mappe
Arkivstruktur.Mappe "+mappe 0..1" o--> "+registrering 0..*" Arkivstruktur.Registrering
Arkivstruktur.Merknad "+merknad 0..*" <--* Arkivstruktur.Mappe
Arkivstruktur.Merknad "+merknad 0..*" <--* Arkivstruktur.Dokumentbeskrivelse
Arkivstruktur.Basisregistrering -|> Arkivstruktur.Registrering
Arkivstruktur.Merknad "+merknad 0..*" <--* Arkivstruktur.Basisregistrering
Arkivstruktur.Registrering "+registrering 1..*" o--> "+dokumentbeskrivelse 0..*" Arkivstruktur.Dokumentbeskrivelse
Arkivstruktur.Dokumentbeskrivelse "+dokumentbeskrivelse 1" o-> "+dokumentobjekt 0..*" Arkivstruktur.Dokumentobjekt
Arkivstruktur.Dokumentobjekt *-> "+konvertering 0..*" Arkivstruktur.Konvertering
Arkivstruktur.ElektroniskSignatur -[hidden]-> Arkivstruktur.Dokumentobjekt
@enduml

The format is quite compact, with little redundant information. The text expresses entities and relations, and there is little layout related fluff. One can reuse content by using include files, allowing for consistent naming across several diagrams. The include files can be standalone PlantUML too. Here is the content of media/uml-class-arkivskaper.iuml:

@startuml
class Arkivstruktur.Arkivskaper  {
  +arkivskaperID : string
  +arkivskaperNavn : string
  +beskrivelse : string [0..1]
}
@enduml

This is what the complete diagram for the PlantUML notation above look like:

A cool feature of PlantUML is that the generated PNG files include the entire original source diagram as text. The source (with include statements expanded) can be extracted using for example exiftool. Another cool feature is that parts of the entities can be hidden after inclusion. This allow to use include files with all attributes listed, even for UML diagrams that should not list any attributes.

The diagram also show some of the warts. Some times the layout engine place text labels on top of each other, and some times it place the class boxes too close to each other, not leaving room for the labels on the relationship arrows. The former can be worked around by placing extra newlines in the labes (ie "\n"). I did not do it here to be able to demonstrate the issue. I have not found a good way around the latter, so I normally try to reduce the problem by changing from vertical to horizontal links to improve the layout.

All in all, I am quite happy with PlantUML, and very impressed with how quickly its lead developer responds to questions. So far I got an answer to my questions in a few hours when I send an email. I definitely recommend looking at PlantUML if you need to make UML diagrams. Note, PlantUML can draw a lot more than class relations. Check out the documention for a complete list. :)

As usual, if you use Bitcoin and want to show your support of my activities, please send Bitcoin donations to my address 15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b.

24th March 2019

Yesterday, a new release of Nikita Noark 5 core project was announced on the project mailing list. The free software solution is an implementation of the Norwegian archive standard Noark 5 used by government offices in Norway. These were the changes in version 0.3 since version 0.2.1 (from NEWS.md):

  • Improved ClassificationSystem and Class behaviour.
  • Tidied up known inconsistencies between domain model and hateaos links.
  • Added experimental code for blockchain integration.
  • Make token expiry time configurable at upstart from properties file.
  • Continued work on OData search syntax.
  • Started work on pagination for entities, partly implemented for Saksmappe.
  • Finalise ClassifiedCode Metadata entity.
  • Implement mechanism to check if authentication token is still valid. This allow the GUI to return a more sensible message to the user if the token is expired.
  • Reintroduce browse.html page to allow user to browse JSON API using hateoas links.
  • Fix bug in handling file/mappe sequence number. Year change was not properly handled.
  • Update application yml files to be in sync with current development.
  • Stop 'converting' everything to PDF using libreoffice. Only convert the file formats doc, ppt, xls, docx, pptx, xlsx, odt, odp and ods.
  • Continued code style fixing, making code more readable.
  • Minor bug fixes.

If free and open standardized archiving API sound interesting to you, please contact us on IRC (#nikita on irc.freenode.net) or email (nikita-noark mailing list).

As usual, if you use Bitcoin and want to show your support of my activities, please send Bitcoin donations to my address 15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b.

11th March 2019

Et virksomhetsarkiv for meg, er et arbeidsverktøy der en enkelt kan finne informasjonen en trenger når en trenger det, og der virksomhetens samlede kunnskap er tilgjengelig. Det må være greit å finne frem i, litt som en bibliotek. Men der et bibliotek gjerne tar vare på offentliggjort informasjon som er tilgjengelig flere steder, tar et arkiv vare på virksomhetsintern og til tider personlig informasjon som ofte kun er tilgjengelig fra et sted.

Jeg mistenker den eneste måten å sikre at arkivet inneholder den samlede kunnskapen i en virksomhet, er å bruke det som virksomhetens kunnskapslager. Det innebærer å automatisk kopiere (brev, epost, SMS-er etc) inn i arkivet når de sendes og mottas, og der filtrere vekk det en ikke vil ta vare på, og legge på metadata om det som er samlet inn for enkel gjenfinning. En slik bruk av arkivet innebærer at arkivet er en del av daglig virke, ikke at det er siste hvilested for informasjon ingen lenger har daglig bruk for. For å kunne være en del av det daglige virket må arkivet enkelt kunne integreres med andre systemer. I disse dager betyr det å tilby arkivet som en nett-tjeneste til hele virksomheten, tilgjengelig for både mennesker og datamaskiner. Det betyr i tur å både tilby nettsider og et maskinlesbart grensesnitt.

For noen år siden erkjente visjonære arkivarer fordelene med et standardisert maskinlesbart grensesnitt til organisasjonens arkiv. De gikk igang med å lage noe de kalte Noark 5 Tjenestegrensesnitt. Gjort riktig, så åpner slike maskinlesbare grensesnitt for samvirke på tvers av uavhengige programvaresystemer. Gjort feil, vil det blokkere for samvirke og bidra til leverandørinnlåsing. For å gjøre det riktig så må grensesnittet være klart og entydig beskrevet i en spesifikasjon som gjør at spesifikasjonen tolkes på samme måte uavhengig av hvem som leser den, og uavhengig av hvem som tar den i bruk.

For å oppnå klare og entydige beskrivelser i en spesifikasjon, som trengs for å kunne få en fri og åpen standard (se Digistan-definisjon), så trengs det en åpen og gjennomsiktig inngangsport med lav terskel, der de som forsøker å ta den i bruk enkelt kan få inn korreksjoner, etterlyse klargjøringer og rapportere uklarheter i spesifikasjonen. En trenger også automatiserte datasystemer som måler og sjekker at et gitt grensesnitt fungerer i tråd med spesifikasjonen.

For Noark 5 Tjenestegrensesnittet er det nå etablert en slik åpen og gjennomsiktig inngangsport på prosjekttjenesten github. Denne inngangsporten består først og fremst av en åpen portal som lar enhver se hva som er gjort av endringer i spesifikasjonsteksten over tid, men det hører også med et åpent "diskusjonsforum" der en kan komme med endringsforslag og forespørsler om klargjøringer. Alle registrerte brukere på github kan bidra med innspill til disse henvendelsene.

I samarbeide med Arkivverket har jeg fått opprettet et git-depot med spesifikasjonsteksten for tjenestegrensesnittet, der det er lagt inn historikk for endringer i teksten de siste årene, samt lagt inn endringsforslag og forespørsler om klargjøring av teksten. Bakgrunnen for at jeg bidro med dette er at jeg er involvert i Nikita-prosjektet, som lager en fri programvare-utgave av Noark 5 Tjenestegrensesnitt. Det er først når en forsøker å lage noe i tråd med en spesifikasjon at en oppdager hvor mange detaljer som må beskrives i spesifikasjonen for å sikre samhandling.

Spesifikasjonen vedlikeholdes i et rent tekstformat, for å ha et format egnet for versjonskontroll via versjontrollsystemet git. Dette gjør det både enkelt å se konkret hvilke endringer som er gjort når, samt gjør det praktisk mulig for enhver med github-konto å sende inn endringsforslag med formuleringer til spesifikasjonsteksten. Dette tekstformatet vises frem som nettsider på github, slik at en ikke trenger spesielle verktøy for å se på siste utgave av spesifikasjonen.

Fra dette rene tekstformatet kan det så avledes ulike formater, som HTML for websider, PDF for utskrift på papir og ePub for lesing med ebokleser. Avlednings-systemet (byggesystemet) bruker i dag verktøyene pandoc, latex, docbook-xsl og GNU make til transformasjonen. Tekstformatet som brukes dag er Markdown, men det vurderes å endre til formatet RST i fremtiden for bedre styring av utseende på PDF-utgaven.

Versjonskontrollsystemet git ble valgt da det er både fleksibelt, avansert og enkelt å ta i bruk. Github ble valgt (foran f.eks. Gitlab som vi bruker i Nikita), da Arkivverket allerede hadde tatt i bruk Github i andre sammenhenger.

Enkle endringer i teksten kan gjøres av priviligerte brukere direkte i nettsidene til Github, ved å finne aktuell fil som skal endres (f.eks. kapitler/03-konformitet.md), klikke på den lille bokstaven i høyre hjørne over teksten. Det kommer opp en nettside der en kan endre teksten slik en ønsker. Når en er fornøyd med endringen så må endringen "sjekkes inn" i historikken. Det gjøres ved å gi en kort beskrivelse av endringen (beskriv helst hvorfor endringen trengs, ikke hva som er endret), under overskriften "Commit changes". En kan og bør legge inn en lengre forklaring i det større skrivefeltet, før en velger om endringen skal sendes direkte til 'master'-grenen (dvs. autorativ utgave av spesifikasjonen) eller om en skal lage en ny gren for denne endringen og opprette en endringsforespørsel (aka "Pull Request"/PR). Når alt dette er gjort kan en velge "Commit changes" for å sende inn endringen. Hvis den er lagt inn i "master"-grenen så er den en offisiell del av spesifikasjonen med en gang. Hvis den derimot er en endringsforespørsel, så legges den inn i listen over forslag til endringer som venter på korrekturlesing og godkjenning.

Større endringer (for eksempel samtidig endringer i flere filer) gjøres enklest ved å hente ned en kopi av git-depoet lokalt og gjøre endringene der før endringsforslaget sendes inn. Denne prosessen er godt beskrivet i dokumentasjon fra github. Git-prosjektet som skal "klones" er https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/.

For å registrere nye utfordringer (issues) eller kommentere på eksisterende utfordringer benyttes nettsiden https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/issues. I skrivende stund er det 48 åpne og 11 avsluttede utfordringer. Et forslag til hva som bør være med når en beskriver en utfordring er tilgjengelig som utfordring #14.

For å bygge en PDF-utgave av spesifikasjonen så bruker jeg i dag en Debian GNU/Linux-maskin med en rekke programpakker installert. Når dette er på plass, så holder det å kjøre kommandoen 'make pdf html' på kommandolinjen, vente ca. 20 sekunder, før spesifikasjon.pdf og spesifikasjon.html ligger klar på disken. Verktøyene for bygging av PDF, HTML og ePub-utgave er også tilgjengelig på Windows og MacOSX.

Github bidrar med rammeverket. Men for at åpent vedlikehold av spesifikasjonen skal fungere, så trengs det folk som bidrar med sin tid og kunnskap. Arkivverket har sagt de skal bidra med innspill og godkjenne forslag til endringer, men det blir størst suksess hvis alle som bruker og lager systemer basert på Noark 5 Tjenestegrensesnitt bidrar med sin kunnskap og kommer med forslag til forebedringer. Jeg stiller. Blir du med?

Det er viktig å legge til rette for åpen diskusjon blant alle interesserte, som ikke krever at en må godta lange kontrakter med vilkår for deltagelse. Inntil Arkivverket dukker opp på IRC har vi laget en IRC-kanal der interesserte enkelt kan orientere seg og diskutere tjenestegrensesnittet. Alle er velkommen til å ta turen innom #nikita (f.eks. via irc.freenode.net) for å møte likesinnede.

Det holder dog ikke å ha en god spesifikasjon, hvis ikke de som tar den i bruk gjør en like god jobb. For å automatisk teste om et konkret tjenestegrensesnitt følger (min) forståelse av spesifikasjonsdokumentet, har jeg skrevet et program som kobler seg opp til et Noark 5v4 REST-tjeneste og tester alt den finner for å se om det er i henhold til min tolkning av spesifikasjonen. Dette verktøyet er tilgjengelig fra https://github.com/petterreinholdtsen/noark5-tester, og brukes daglig mens vi utvikler Nikita for å sikre at vi ikke introduserer nye feil. Hvis en skal sikre samvirke på tvers av ulike systemer er det helt essensielt å kunne raskt og automatisk sjekke at tjenestegrensesnittet oppfører seg som forventet. Jeg håper andre som lager sin utgave av tjenestegrensesnittet vi bruke dette verktøyet, slik at vi tidlig og raskt kan oppdage hvor vi har tolket spesifikasjonen ulikt, og dermed få et godt grunnlag for å gjøre spesifikasjonsteksten enda klarere og bedre.

Dagens beskrivelse av Noark 5 Tjenestegrensesnitt er et svært godt utgangspunkt for å gjøre virksomhetens arkiv til et dynamisk og sentralt arbeidsverktøy i organisasjonen. Blir du med å gjøre den enda bedre?

1st November 2018

As part of my involvement in the Nikita archive API project, I've been importing a fairly large lump of emails into a test instance of the archive to see how well this would go. I picked a subset of my notmuch email database, all public emails sent to me via @lists.debian.org, giving me a set of around 216 000 emails to import. In the process, I had a look at the various attachments included in these emails, to figure out what to do with attachments, and noticed that one of the most common attachment formats do not have an official MIME type registered with IANA/IETF. The output from diff, ie the input for patch, is on the top 10 list of formats included in these emails. At the moment people seem to use either text/x-patch or text/x-diff, but neither is officially registered. It would be better if one official MIME type were registered and used everywhere.

To try to get one official MIME type for these files, I've brought up the topic on the media-types mailing list. If you are interested in discussion which MIME type to use as the official for patch files, or involved in making software using a MIME type for patches, perhaps you would like to join the discussion?

As usual, if you use Bitcoin and want to show your support of my activities, please send Bitcoin donations to my address 15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b.

18th October 2018

This morning, the new release of the Nikita Noark 5 core project was announced on the project mailing list. The free software solution is an implementation of the Norwegian archive standard Noark 5 used by government offices in Norway. These were the changes in version 0.2 since version 0.1.1 (from NEWS.md):

  • Fix typos in REL names
  • Tidy up error message reporting
  • Fix issue where we used Integer.valueOf(), not Integer.getInteger()
  • Change some String handling to StringBuffer
  • Fix error reporting
  • Code tidy-up
  • Fix issue using static non-synchronized SimpleDateFormat to avoid race conditions
  • Fix problem where deserialisers were treating integers as strings
  • Update methods to make them null-safe
  • Fix many issues reported by coverity
  • Improve equals(), compareTo() and hash() in domain model
  • Improvements to the domain model for metadata classes
  • Fix CORS issues when downloading document
  • Implementation of case-handling with registryEntry and document upload
  • Better support in Javascript for OPTIONS
  • Adding concept description of mail integration
  • Improve setting of default values for GET on ny-journalpost
  • Better handling of required values during deserialisation
  • Changed tilknyttetDato (M620) from date to dateTime
  • Corrected some opprettetDato (M600) (de)serialisation errors.
  • Improve parse error reporting.
  • Started on OData search and filtering.
  • Added Contributor Covenant Code of Conduct to project.
  • Moved repository and project from Github to Gitlab.
  • Restructured repository, moved code into src/ and web/.
  • Updated code to use Spring Boot version 2.
  • Added support for OAuth2 authentication.
  • Fixed several bugs discovered by Coverity.
  • Corrected handling of date/datetime fields.
  • Improved error reporting when rejecting during deserializatoin.
  • Adjusted default values provided for ny-arkivdel, ny-mappe, ny-saksmappe, ny-journalpost and ny-dokumentbeskrivelse.
  • Several fixes for korrespondansepart*.
  • Updated web GUI:
    • Now handle both file upload and download.
    • Uses new OAuth2 authentication for login.
    • Forms now fetches default values from API using GET.
    • Added RFC 822 (email), TIFF and JPEG to list of possible file formats.

The changes and improvements are extensive. Running diffstat on the changes between git tab 0.1.1 and 0.2 show 1098 files changed, 108666 insertions(+), 54066 deletions(-).

If free and open standardized archiving API sound interesting to you, please contact us on IRC (#nikita on irc.freenode.net) or email (nikita-noark mailing list).

As usual, if you use Bitcoin and want to show your support of my activities, please send Bitcoin donations to my address 15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b.

8th October 2018

I have earlier covered the basics of trusted timestamping using the 'openssl ts' client. See blog post for 2014, 2016 and 2017 for those stories. But some times I want to integrate the timestamping in other code, and recently I needed to integrate it into Python. After searching a bit, I found the rfc3161 library which seemed like a good fit, but I soon discovered it only worked for python version 2, and I needed something that work with python version 3. Luckily I next came across the rfc3161ng library, a fork of the original rfc3161 library. Not only is it working with python 3, it have fixed a few of the bugs in the original library, and it has an active maintainer. I decided to wrap it up and make it available in Debian, and a few days ago it entered Debian unstable and testing.

Using the library is fairly straight forward. The only slightly problematic step is to fetch the required certificates to verify the timestamp. For some services it is straight forward, while for others I have not yet figured out how to do it. Here is a small standalone code example based on of the integration tests in the library code:

#!/usr/bin/python3

"""

Python 3 script demonstrating how to use the rfc3161ng module to
get trusted timestamps.

The license of this code is the same as the license of the rfc3161ng
library, ie MIT/BSD.

"""

import os
import pyasn1.codec.der
import rfc3161ng
import subprocess
import tempfile
import urllib.request

def store(f, data):
    f.write(data)
    f.flush()
    f.seek(0)

def fetch(url, f=None):
    response = urllib.request.urlopen(url)
    data = response.read()
    if f:
        store(f, data)
    return data

def main():
    with tempfile.NamedTemporaryFile() as cert_f,\
    	 tempfile.NamedTemporaryFile() as ca_f,\
    	 tempfile.NamedTemporaryFile() as msg_f,\
    	 tempfile.NamedTemporaryFile() as tsr_f:

        # First fetch certificates used by service
        certificate_data = fetch('https://freetsa.org/files/tsa.crt', cert_f)
        ca_data_data = fetch('https://freetsa.org/files/cacert.pem', ca_f)

        # Then timestamp the message
        timestamper = \
            rfc3161ng.RemoteTimestamper('http://freetsa.org/tsr',
                                        certificate=certificate_data)
        data = b"Python forever!\n"
        tsr = timestamper(data=data, return_tsr=True)

        # Finally, convert message and response to something 'openssl ts' can verify
        store(msg_f, data)
        store(tsr_f, pyasn1.codec.der.encoder.encode(tsr))
        args = ["openssl", "ts", "-verify",
                "-data", msg_f.name,
	        "-in", tsr_f.name,
		"-CAfile", ca_f.name,
                "-untrusted", cert_f.name]
        subprocess.check_call(args)

if '__main__' == __name__:
   main()

The code fetches the required certificates, store them as temporary files, timestamp a simple message, store the message and timestamp to disk and ask 'openssl ts' to verify the timestamp. A timestamp is around 1.5 kiB in size, and should be fairly easy to store for future use.

As usual, if you use Bitcoin and want to show your support of my activities, please send Bitcoin donations to my address 15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b.

10th June 2017

I am very happy to report that the Nikita Noark 5 core project tagged its second release today. The free software solution is an implementation of the Norwegian archive standard Noark 5 used by government offices in Norway. These were the changes in version 0.1.1 since version 0.1.0 (from NEWS.md):

  • Continued work on the angularjs GUI, including document upload.
  • Implemented correspondencepartPerson, correspondencepartUnit and correspondencepartInternal
  • Applied for coverity coverage and started submitting code on regualr basis.
  • Started fixing bugs reported by coverity
  • Corrected and completed HATEOAS links to make sure entire API is available via URLs in _links.
  • Corrected all relation URLs to use trailing slash.
  • Add initial support for storing data in ElasticSearch.
  • Now able to receive and store uploaded files in the archive.
  • Changed JSON output for object lists to have relations in _links.
  • Improve JSON output for empty object lists.
  • Now uses correct MIME type application/vnd.noark5-v4+json.
  • Added support for docker container images.
  • Added simple API browser implemented in JavaScript/Angular.
  • Started on archive client implemented in JavaScript/Angular.
  • Started on prototype to show the public mail journal.
  • Improved performance by disabling Sprint FileWatcher.
  • Added support for 'arkivskaper', 'saksmappe' and 'journalpost'.
  • Added support for some metadata codelists.
  • Added support for Cross-origin resource sharing (CORS).
  • Changed login method from Basic Auth to JSON Web Token (RFC 7519) style.
  • Added support for GET-ing ny-* URLs.
  • Added support for modifying entities using PUT and eTag.
  • Added support for returning XML output on request.
  • Removed support for English field and class names, limiting ourself to the official names.
  • ...

If this sound interesting to you, please contact us on IRC (#nikita on irc.freenode.net) or email (nikita-noark mailing list).

7th June 2017

This is a copy of an email I posted to the nikita-noark mailing list. Please follow up there if you would like to discuss this topic. The background is that we are making a free software archive system based on the Norwegian Noark 5 standard for government archives.

I've been wondering a bit lately how trusted timestamps could be stored in Noark 5. Trusted timestamps can be used to verify that some information (document/file/checksum/metadata) have not been changed since a specific time in the past. This is useful to verify the integrity of the documents in the archive.

Then it occured to me, perhaps the trusted timestamps could be stored as dokument variants (ie dokumentobjekt referered to from dokumentbeskrivelse) with the filename set to the hash it is stamping?

Given a "dokumentbeskrivelse" with an associated "dokumentobjekt", a new dokumentobjekt is associated with "dokumentbeskrivelse" with the same attributes as the stamped dokumentobjekt except these attributes:

  • format -> "RFC3161"
  • mimeType -> "application/timestamp-reply"
  • formatDetaljer -> "<source URL for timestamp service>"
  • filenavn -> "<sjekksum>.tsr"

This assume a service following IETF RFC 3161 is used, which specifiy the given MIME type for replies and the .tsr file ending for the content of such trusted timestamp. As far as I can tell from the Noark 5 specifications, it is OK to have several variants/renderings of a dokument attached to a given dokumentbeskrivelse objekt. It might be stretching it a bit to make some of these variants represent crypto-signatures useful for verifying the document integrity instead of representing the dokument itself.

Using the source of the service in formatDetaljer allow several timestamping services to be used. This is useful to spread the risk of key compromise over several organisations. It would only be a problem to trust the timestamps if all of the organisations are compromised.

The following oneliner on Linux can be used to generate the tsr file. $input is the path to the file to checksum, and $sha256 is the SHA-256 checksum of the file (ie the ".tsr" value mentioned above).

openssl ts -query -data "$inputfile" -cert -sha256 -no_nonce \
  | curl -s -H "Content-Type: application/timestamp-query" \
      --data-binary "@-" http://zeitstempel.dfn.de > $sha256.tsr

To verify the timestamp, you first need to download the public key of the trusted timestamp service, for example using this command:

wget -O ca-cert.txt \
  https://pki.pca.dfn.de/global-services-ca/pub/cacert/chain.txt

Note, the public key should be stored alongside the timestamps in the archive to make sure it is also available 100 years from now. It is probably a good idea to standardise how and were to store such public keys, to make it easier to find for those trying to verify documents 100 or 1000 years from now. :)

The verification itself is a simple openssl command:

openssl ts -verify -data $inputfile -in $sha256.tsr \
  -CAfile ca-cert.txt -text

Is there any reason this approach would not work? Is it somehow against the Noark 5 specification?

27th April 2017

I disse dager, med frist 1. mai, har Riksarkivaren ute en høring på sin forskrift. Som en kan se er det ikke mye tid igjen før fristen som går ut på søndag. Denne forskriften er det som lister opp hvilke formater det er greit å arkivere i Noark 5-løsninger i Norge.

Jeg fant høringsdokumentene hos Norsk Arkivråd etter å ha blitt tipset på epostlisten til fri programvareprosjektet Nikita Noark5-Core, som lager et Noark 5 Tjenestegresesnitt. Jeg er involvert i Nikita-prosjektet og takket være min interesse for tjenestegrensesnittsprosjektet har jeg lest en god del Noark 5-relaterte dokumenter, og til min overraskelse oppdaget at standard epost ikke er på listen over godkjente formater som kan arkiveres. Høringen med frist søndag er en glimrende mulighet til å forsøke å gjøre noe med det. Jeg holder på med egen høringsuttalelse, og lurer på om andre er interessert i å støtte forslaget om å tillate arkivering av epost som epost i arkivet.

Er du igang med å skrive egen høringsuttalelse allerede? I så fall kan du jo vurdere å ta med en formulering om epost-lagring. Jeg tror ikke det trengs så mye. Her et kort forslag til tekst:

Viser til høring sendt ut 2017-02-17 (Riksarkivarens referanse 2016/9840 HELHJO), og tillater oss å sende inn noen innspill om revisjon av Forskrift om utfyllende tekniske og arkivfaglige bestemmelser om behandling av offentlige arkiver (Riksarkivarens forskrift).

Svært mye av vår kommuikasjon foregår i dag på e-post.  Vi foreslår derfor at Internett-e-post, slik det er beskrevet i IETF RFC 5322, https://tools.ietf.org/html/rfc5322. bør inn som godkjent dokumentformat.  Vi foreslår at forskriftens oversikt over godkjente dokumentformater ved innlevering i § 5-16 endres til å ta med Internett-e-post.

Som del av arbeidet med tjenestegrensesnitt har vi testet hvordan epost kan lagres i en Noark 5-struktur, og holder på å skrive et forslag om hvordan dette kan gjøres som vil bli sendt over til arkivverket så snart det er ferdig. De som er interesserte kan følge fremdriften på web.

Oppdatering 2017-04-28: I dag ble høringuttalelsen jeg skrev sendt inn av foreningen NUUG.

19th March 2017

The Nikita Noark 5 core project is implementing the Norwegian standard for keeping an electronic archive of government documents. The Noark 5 standard document the requirement for data systems used by the archives in the Norwegian government, and the Noark 5 web interface specification document a REST web service for storing, searching and retrieving documents and metadata in such archive. I've been involved in the project since a few weeks before Christmas, when the Norwegian Unix User Group announced it supported the project. I believe this is an important project, and hope it can make it possible for the government archives in the future to use free software to keep the archives we citizens depend on. But as I do not hold such archive myself, personally my first use case is to store and analyse public mail journal metadata published from the government. I find it useful to have a clear use case in mind when developing, to make sure the system scratches one of my itches.

If you would like to help make sure there is a free software alternatives for the archives, please join our IRC channel (#nikita on irc.freenode.net) and the project mailing list.

When I got involved, the web service could store metadata about documents. But a few weeks ago, a new milestone was reached when it became possible to store full text documents too. Yesterday, I completed an implementation of a command line tool archive-pdf to upload a PDF file to the archive using this API. The tool is very simple at the moment, and find existing fonds, series and files while asking the user to select which one to use if more than one exist. Once a file is identified, the PDF is associated with the file and uploaded, using the title extracted from the PDF itself. The process is fairly similar to visiting the archive, opening a cabinet, locating a file and storing a piece of paper in the archive. Here is a test run directly after populating the database with test data using our API tester:

~/src//noark5-tester$ ./archive-pdf mangelmelding/mangler.pdf
using arkiv: Title of the test fonds created 2017-03-18T23:49:32.103446
using arkivdel: Title of the test series created 2017-03-18T23:49:32.103446

 0 - Title of the test case file created 2017-03-18T23:49:32.103446
 1 - Title of the test file created 2017-03-18T23:49:32.103446
Select which mappe you want (or search term): 0
Uploading mangelmelding/mangler.pdf
  PDF title: Mangler i spesifikasjonsdokumentet for NOARK 5 Tjenestegrensesnitt
  File 2017/1: Title of the test case file created 2017-03-18T23:49:32.103446
~/src//noark5-tester$

You can see here how the fonds (arkiv) and serie (arkivdel) only had one option, while the user need to choose which file (mappe) to use among the two created by the API tester. The archive-pdf tool can be found in the git repository for the API tester.

In the project, I have been mostly working on the API tester so far, while getting to know the code base. The API tester currently use the HATEOAS links to traverse the entire exposed service API and verify that the exposed operations and objects match the specification, as well as trying to create objects holding metadata and uploading a simple XML file to store. The tester has proved very useful for finding flaws in our implementation, as well as flaws in the reference site and the specification.

The test document I uploaded is a summary of all the specification defects we have collected so far while implementing the web service. There are several unclear and conflicting parts of the specification, and we have started writing down the questions we get from implementing it. We use a format inspired by how The Austin Group collect defect reports for the POSIX standard with their instructions for the MANTIS defect tracker system, in lack of an official way to structure defect reports for Noark 5 (our first submitted defect report was a request for a procedure for submitting defect reports :).

The Nikita project is implemented using Java and Spring, and is fairly easy to get up and running using Docker containers for those that want to test the current code base. The API tester is implemented in Python.

29th January 2015

En ting jeg har lurt på når det gjelder offentlige postjournaler, er hvor stor andel av det som ligger i de interne databasene kommer ikke med i postjournalen. Dette er det mulig å finne ut basert på det som ligger i postjournalen. For å forstå hva jeg mener, trengs det litt bakgrunnsinformasjon. I henhold til NOARK-standarden for norske offentlige arkiv skal enhver sak ha et årstall og et løpenummer, og ethvert dokument i saken skal gis et dokument-løpenummer. Det vil si at en ender opp med dokument-ID som ser ut som ÅÅÅÅ/SAKNR-DOKNR, f.eks. 2014/2-1 eller 2014/12312-14. Mange oppgir kun tosifret årstall, men prinsippet er det samme. Så vidt jeg vet skal saksnummer og dokumentnummer tildeles løpende og i stigende rekkefølge. Gitt en instans med følgende dokument-ID i postjournalen, så kan en regne ut hvor mye som ikke finnes i journalen:

  • 2014/2-1
  • 2014/5-1
  • 2014/5-3

Her ser en at saksnummer 2 og 5 finnes i postjournalen, mens nummerene 1, 3 og 4 mangler. En ser også at i sak 2014/5 mangler dokument 2. Ved hjelp av denne informasjonen har jeg regnet ut hvor stor andel av saksnummer og dokumentløpenummer som ikke har dukket opp i Offentlig Elektronisk Postjournal (OEP). For saksnummer har jeg tatt utgangspunkt i at en ikke trenger å starte på 1, og dermed regnet med området fra laveste til høyeste saksnummer og talt antall unike saksnummer som forekommer i OEP. I dette tilfellet betyr de at 2 av 4 saksnummer er ubrukte (50%). For dokumentløpenummer har jeg tilsvarende tatt utgangspunkt i laveste og høyeste kjente dokumentløpenummer, for å handtere databaser der jeg mangler komplett postjournal. For sak 2014/5 her betyr det at 1 av 3 dokumenter mangler (33%).

Det er flere årsaker til at det kan bli hull i nummerseriene. Feilføring der et dokument tildeles et nytt saksnummer ved en feil, og deretter flyttes inn i riktig sak vil gi et ubrukt saksnummer, da saksnummer skal tildeles i stigende rekkefølge og en ikke får opprette nye saker innimellom gamle saker. Tilsvarende kan skje med dokument-løpenummer. Det er jo heller ikke sikkert at et saksnummer i OEP er det samme som løpenummeret som brukes som saksnummeret i instansens interne datasystem. Kanskje snakker vi om ulike ontologier der en delmengde av interne saksnummer tilsvarer saksnummer i OEP. Hvis like nummer også tildeles andre ting enn saker som skal til OEP vil en tilsvarende få «hull» i saksnumrene i postjournalen.

Jeg er litt usikker på hva denne statistikken egentlig viser, og heller ikke sikker på om det er reelt sett mangler i OEP (som kanskje kunne anses å være kritikkverdig), bare er resultatet av hendelige uhell i nummertildelingen eller resultat av ulik ontologi i OEP og instansens datasystem. Men jeg syntes tallene og variasjonen var så interessant at jeg hadde lyst til å dele dem med mine lesere. Jeg har sortert listen på prosent upubliserte saksnummer for 2014.

SaksnummerDokumentnummerInstans
201420132014
%Upubl. saksnr.Totalt %Upubl. saksnrTotalt %Upubl. dok.nr.Totalt
0.6 8 1282 0.2 2 861 0.0 0 6105Vox, nasjonalt fagorgan for kompetansepolitikk
0.9 91 9863 2.7 313 11703 0.0 0 24029Direktoratet for byggkvalitet
1.0 161 15663 3.3 558 17045 0.0 0 41954Justervesenet
1.1 325 28515 1.2 357 29621 0.0 0 66871Arkivverket
1.8 28 1568 1.0 17 1722 0.0 0 9259Statistisk sentralbyrå
1.8 92 506675.43144 4169 0.0 0 17056Arbeids- og sosialdepartementet
2.2 32 1470 2.4 36 1471 0.0 0 9757Norsk Filminstitutt
2.3 34 1478 2.9 41 1425 0.0 0 4522Datatilsynet
2.7 49 1795 2.8 34 1199 0.0 0 5824Direktoratet for mineralforvaltning med Bergmesteren for Svalbard
3.1 134 4326 2.8 144 5119 0.0 0 12223Brønnøysundregistrene
3.1 201 6571 6.1 603 9870 0.0 0 22390Statens kartverk
3.2 228 7092 2.0 143 7032 0.1 14 24491Lotteri- og stiftelsestilsynet
3.6 32 891 4.9 37 753 0.0 0 3055Statens innkrevingssentral
3.81016 26466 2.5 716 28727 0.0 0 86951Husbanken
3.9 52 132614.4 180 1247 0.0 0 4922Sysselmannen på Svalbard
4.0 248 6250 4.6 332 7159 0.0 0 22063Post- og teletilsynet
4.1 102 2488 2.7 62 2291 0.0 0 9707Forbrukerombudet
4.8 51 106012.6 132 1046 0.0 0 3616Statens strålevern
5.2 924 17781 6.31184 18665 0.0 0 59772Fiskeridirektoratet
5.5 254 4638 6.1 315 5168 0.0 0 15470Barne-, likestillings- og inkluderingsdepartementet
6.0 80 1336 3.7 48 1314 0.0 0 2691Medietilsynet
6.1 91 1486 5.0 83 1651 0.2 17 7473Petroleumstilsynet
6.2 248 399773.73459 4693 0.0 0 10963Klima- og miljødepartementet
7.0 190 270010.2 207 2033 0.0 1 14299Samferdselsdepartementet
7.1 35 492 4.5 41 909 0.0 0 2960Konkurransetilsynet
7.1 482 6800 6.4 532 8259 0.0 0 28684Justis- og beredskapsdepartementet
7.2 87 1204 4.2 50 1199 0.0 3 7428Oljedirektoratet
7.2 106 1478 6.3 129 2045 0.0 2 4987Statens jernbanetilsyn
7.2 131 1813 8.5 124 1452 0.0 2 8758Statsministerens kontor
7.3 816 11218 6.1 655 10665 0.0 0 47160Norges forskningsråd
7.81150 14712 6.7 746 11202 0.0 0 33794Miljødirektoratet
7.9 411 5216 8.3 446 5365 0.0 0 16441Helse- og omsorgsdepartementet
8.3 376 4514 8.2 457 5548 0.0 3 20840Luftfartstilsynet
8.5 185 2181 9.8 175 1780 0.0 0 7669Landbruks- og matdepartementet
8.6 10 116 0.8 1 127 0.0 0 318Statens institutt for rusmiddelforskning
9.0 597 6648 9.7 705 7236 0.0 3 35663Utdanningsdirektoratet
9.01139 12632 8.21100 13344 0.0 2 36987Finanstilsynet
9.1 540 594913.4 769 5743 0.0 0 13908Finansdepartementet
9.2 256 2787 6.5 203 3147 0.0 0 9487Riksantikvaren - Direktoratet for kulturminneforvaltning
9.31596 17209 2.5 463 18438 0.0 0 53119Statens legemiddelverk
9.7 299 308510.7 329 3072 0.1 6 7579Forsvarsdepartementet
10.1 167 1650 4.5 65 1445 0.0 0 11157Statens helsetilsyn
10.9 59 542 7.7 44 569 0.0 0 1283Statens arbeidsmiljøinstitutt
11.3 46 40796.12591 2695 0.0 0 1489Landbruksdirektoratet Alta
11.4 675 593313.6 613 4492 0.0 0 24598Kystverket
11.6 739 638312.2 748 6121 0.0 1 18605Kunnskapsdepartementet
11.9 641 5398 9.3 432 4655 0.0 0 14438Kulturdepartementet
11.9 934 7835 0.0 0 0 0.0 0 33448Kommunal- og moderniseringsdepartementet
12.1 588 486012.2 522 4294 0.0 0 14173Politidirektoratet
12.11444 1189346.05212 11331 0.0 0 51438Helsedirektoratet
12.6 220 174517.5 112 640 0.1 3 4184Språkrådet
12.7 211 1664 9.7 226 2318 0.0 0 9151Direktoratet for utviklingssamarbeid
13.9 321 230915.1 329 2185 0.0 0 6307Olje- og energidepartementet
14.3 429 299612.5 303 2432 0.0 0 7560Nasjonalt folkehelseinstitutt
14.41408 9785 0.0 0 0 0.0 0 38923Nærings- og fiskeridepartementet
14.7 143 973 7.7 83 1084 0.0 0 4130Utlendingsnemnda
15.8 173 109738.8 621 1602 0.0 0 7557Direktoratet for forvaltning og IKT
16.71345 8069 8.6 703 8219 0.0 0 20834Norges vassdrags- og energidirektorat
17.5 61 34817.2 67 389 0.0 0 7732Senter for internasjonalisering av utdanning
18.93737 19734 4.4 606 13752 0.0 0 49938Direktoratet for samfunnssikkerhet og beredskap
19.11392 726919.11263 6601 0.0 0 19869Fylkesmannen i Troms
20.4 768 375815.7 471 3008 0.1 9 11280Integrerings- og mangfoldsdirektoratet
21.0 995 473717.8 978 5508 0.0 0 11260Fylkesmannen i Sogn og Fjordane
21.6 16 7497.32626 2698 0.0 0 155Statens reindriftsforvaltning
22.1 96 43517.6 81 459 0.2 3 1943Norges geologiske undersøkelse
22.3 27 12110.6 15 141 0.1 1 779Kunst i offentlige rom
22.41939 865921.81992 9120 0.0 1 17738Fylkesmannen i Nordland
22.5 52 23114.7 32 217 0.0 0 896Fredskorpset
22.52017 895795.540498 42425 0.0 0 14223Statens landbruksforvaltning
22.9 116 50715.2 81 532 0.0 0 2069Nasjonalbiblioteket
25.5 211 82920.8 205 987 0.0 0 3867Direktoratet for økonomistyring
26.1 6 23 9.7 3 31 0.0 0 106Kompetansesenter for distriktsutvikling
26.6 187 70228.5 248 871 0.0 1 3154Nasjonalt organ for kvalitet i utdanningen
27.1 90 33213.2 41 311 0.0 0 2400Norsk Akkreditering
28.3 562 198620.0 518 2586 0.0 0 6267Statens lånekasse for utdanning
28.8 443 153841.0 688 1679 0.0 0 5556Havforskningsinstituttet
29.81473 494424.81047 4230 0.0 0 9850Utlendingsdirektoratet
29.81563 524931.01421 4588 0.0 0 15660Fylkesmannen i Finnmark
30.8 314 102158.4 941 1610 0.3 13 3979Direktoratet for nødkommunikasjon
31.4 463 147537.0 280 757 0.1 7 4797Domstoladministrasjonen
31.84708 1478525.22236 8879 0.0 2 39313Utenriksdepartementet
36.1 526 145676.61364 1781 0.0 0 4472Departementenes sikkerhets- og serviceorganisasjon
36.7 447 121763.81503 2355 1.8 92 5121Garantiinstituttet for eksportkreditt
38.23341 874434.73096 8927 0.0 3 15180Fylkesmannen i Oppland
39.36267 1594737.76262 16606 0.1 15 29707Fylkesmannen i Hordaland
39.62122 536541.32242 5428 0.0 0 12680Fylkesmannen i Telemark
40.83137 769837.03059 8272 0.0 5 13848Fylkesmannen i Nord-Trøndelag
42.11528 362719.2 529 2750 0.0 1 13524Statsbygg
42.42844 670042.42913 6863 0.0 0 12090Fylkesmannen i Vest-Agder
42.9 6 1488.92398 2698 0.0 0 23Reindriftsforvaltningen
43.33310 764542.63369 7908 0.0 0 15739Fylkesmannen i Vestfold
43.43433 790540.83508 8594 0.0 0 12921Fylkesmannen i Møre og Romsdal
43.45540 1277340.15429 13534 0.0 0 22389Fylkesmannen i Rogaland
43.62334 535039.52314 5861 0.0 0 9997Fylkesmannen i Aust-Agder
43.72656 607923.1 890 3853 0.1 21 18064Forsvarsbygg
48.94276 874748.04189 8734 0.0 0 16281Fylkesmannen i Buskerud
50.95106 1002445.74584 10022 0.0 0 15340Fylkesmannen i Sør-Trøndelag
51.44477 870345.84240 9253 0.0 5 12067Fylkesmannen i Hedmark
51.5 210 40836.8 656 1785 0.0 0 658Departementenes servicesenter
52.74663 885246.64110 8824 0.0 0 13869Fylkesmannen i Østfold
59.714852 2486756.614366 25404 0.0 0 38706Fylkesmannen i Oslo og Akershus
61.144900 7349595.140365 42462 0.0 11 63747Landbruksdirektoratet Oslo
63.86812110680218.57592 41093 0.0 0144950Arbeidstilsynet
69.811022515796270.8105811149449 0.0 14106772Statens vegvesen Region øst
72.216772 2321595.216409 17238 0.0 0 16705Norsk kulturråd
78.612413115795677.6115949149462 0.0 0 77689Statens vegvesen Region sør
80.755587 6889671.936121 50269 0.0 0 42152Sjøfartsdirektoratet
81.012800615795680.1119743149456 0.0 8 74195Statens vegvesen Region vest
87.213779815796287.6130971149449 0.0 9 50814Statens vegvesen Region midt
88.012239 1390286.119158 22244 0.0 0 5492Barne-, ungdoms- og familiedirektoratet
90.814345315795690.6135441149453 0.0 0 39961Statens vegvesen Region nord
93.85865 625099.37093 7140 0.0 0 984Nasjonal kommunikasjonsmyndighet
95.34655 488394.33819 4049 0.1 1 967Landinfo
96.215193515787096.0143497149452 0.0 0 19555Statens vegvesen Vegdirektoratet
97.510079910337396.9119802123636 0.0 0 7605Toll- og avgiftsdirektoratet
97.724104 2466698.223640 24062 0.2 5 2108Kriminalomsorgsdirektoratet
98.360845 6192298.358575 59605 0.0 0 2837Statens pensjonskasse
99.599066199587399.4953094958529 0.0 0 18246Skattedirektoratet

Det kunne vært interessant å se hva som skjedde hvis en ba om innsyn i en dokument-ID som ikke finnes i OEP... :) Det hadde også vært interessant å få vite hva årsaken til at noen saksnummer ikke dukker opp i OEP der det er få og mange. Jeg mistenker jo at årsaken ikke er den samme hos Skattedirektoratet og hos Landinfo, selv om andelen upubliserte nummer er ganske lik.

7th March 2014

For noen uker siden ble NXCs fri programvarelisenserte NOARK5-løsning presentert hos NUUG (video på youtube foreløbig), og det fikk meg til å titte litt mer på NOARK5, standarden for arkivhåndtering i det offentlige Norge. Jeg lurer på om denne kjernen kan være nyttig i et par av mine prosjekter, og for ett av dem er det mest aktuelt å lagre epost. Jeg klarte ikke finne noen anbefaling om hvordan RFC 822-formattert epost (aka Internett-epost) burde lagres i NOARK5, selv om jeg vet at noen arkiver tar PDF-utskrift av eposten med sitt epostprogram og så arkiverer PDF-en (eller enda værre, tar papirutskrift og lagrer bildet av eposten som PDF i arkivet).

Det er ikke så mange formater som er akseptert av riksarkivet til langtidsoppbevaring av offentlige arkiver, og PDF og XML er de mest aktuelle i så måte. Det slo meg at det måtte da finnes en eller annen egnet XML-representasjon og at det kanskje var enighet om hvilken som burde brukes, så jeg tok mot til meg og spurte SAMDOK, en gruppe tilknyttet arkivverket som ser ut til å jobbe med NOARK-samhandling, om de hadde noen anbefalinger:

Hei.

Usikker på om dette er riktig forum å ta opp mitt spørsmål, men jeg lurer på om det er definert en anbefaling om hvordan RFC 822-formatterte epost (aka vanlig Internet-epost) bør lages håndteres i NOARK5, slik at en bevarer all informasjon i eposten (f.eks. Received-linjer). Finnes det en anbefalt XML-mapping ala den som beskrives på <URL: https://www.informit.com/articles/article.aspx?p=32074 >? Mitt mål er at det skal være mulig å lagre eposten i en NOARK5-kjerne og kunne få ut en identisk formattert kopi av opprinnelig epost ved behov.

Postmottaker hos SAMDOK mente spørsmålet heller burde stilles direkte til riksarkivet, og jeg fikk i dag svar derfra formulert av seniorrådgiver Geir Ivar Tungesvik:

Riksarkivet har ingen anbefalinger når det gjelder konvertering fra e-post til XML. Det står arkivskaper fritt å eventuelt definere/bruke eget format. Inklusive da - som det spørres om - et format der det er mulig å re-etablere e-post format ut fra XML-en. XML (e-post) dokumenter må være referert i arkivstrukturen, og det må vedlegges et gyldig XML skjema (.xsd) for XML-filene. Arkivskaper står altså fritt til å gjøre hva de vil, bare det dokumenteres og det kan dannes et utrekk ved avlevering til depot.

De obligatoriske kravene i Noark 5 standarden må altså oppfylles - etter dialog med Riksarkivet i forbindelse med godkjenning. For offentlige arkiv er det særlig viktig med filene loependeJournal.xml og offentligJournal.xml. Private arkiv som vil forholde seg til Noark 5 standarden er selvsagt frie til å bruke det som er relevant for dem av obligatoriske krav.

Det ser dermed ut for meg som om det er et lite behov for å standardisere XML-lagring av RFC-822-formatterte meldinger. Noen som vet om god spesifikasjon i så måte? I tillegg til den omtalt over, har jeg kommet over flere aktuelle beskrivelser (søk på "rfc 822 xml", så finner du aktuelle alternativer).

Finnes det andre og bedre spesifikasjoner for slik lagring? Send meg en epost hvis du har innspill.

RSS Feed

Created by Chronicle v4.6