Petter Reinholdtsen

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 frigjøringsdag 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. :)

Childs need to learn how to guard their privacy too. To help them, European Digital Rights (EDRi) created a colorful booklet providing information on several privacy related topics, and tips on how to protect ones privacy in the digital age.

The 24 page booklet titled Digital Defenders is available in several languages. Thanks to the valuable contributions from members of the Electronic Foundation Norway (EFN) and others, it is also available in Norwegian Bokmål. If you would like to have it available in your language too, contribute via Weblate and get in touch.

But a funny, well written and good looking PDF do not have much impact, unless it is read by the right audience. To increase the chance of kids reading it, I am currently assisting EFN in getting copies printed on paper to distribute on the street and in class rooms. Print the booklet was made possible thanks to a small et of great sponsors. Thank you very much to each and every one of them! I hope to have the printed booklet ready to hand out on Tuesday, when the Norwegian Unix Users Group is organizing its yearly barbecue for geeks and free software zealots in the Oslo area. If you are nearby, feel free to come by and check out the party and the booklet.

If the booklet prove to be a success, it would be great to get more sponsoring and distribute it to every kid in the country. :)

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

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.

Some years ago, in 2016, I wrote for the first time about the Ring peer to peer messaging system. It would provide messaging without any central server coordinating the system and without requiring all users to register a phone number or own a mobile phone. Back then, I could not get it to work, and put it aside until it had seen more development. A few days ago I decided to give it another try, and am happy to report that this time I am able to not only send and receive messages, but also place audio and video calls. But only if UDP is not blocked into your network.

The Ring system changed name earlier this year to Jami. I tried doing web search for 'ring' when I discovered it for the first time, and can only applaud this change as it is impossible to find something called Ring among the noise of other uses of that word. Now you can search for 'jami' and this client and the Jami system is the first hit at least on duckduckgo.

Jami will by default encrypt messages as well as audio and video calls, and try to send them directly between the communicating parties if possible. If this proves impossible (for example if both ends are behind NAT), it will use a central SIP TURN server maintained by the Jami project. Jami can also be a normal SIP client. If the SIP server is unencrypted, the audio and video calls will also be unencrypted. This is as far as I know the only case where Jami will do anything without encryption.

Jami is available for several platforms: Linux, Windows, MacOSX, Android, iOS, and Android TV. It is included in Debian already. Jami also work for those using F-Droid without any Google connections, while Signal do not. The protocol is described in the Ring project wiki. The system uses a distributed hash table (DHT) system (similar to BitTorrent) running over UDP. On one of the networks I use, I discovered Jami failed to work. I tracked this down to the fact that incoming UDP packages going to ports 1-49999 were blocked, and the DHT would pick a random port and end up in the low range most of the time. After talking to the developers, I solved this by enabling the dhtproxy in the settings, thus using TCP to talk to a central DHT proxy instead of peering directly with others. I've been told the developers are working on allowing DHT to use TCP to avoid this problem. I also ran into a problem when trying to talk to the version of Ring included in Debian Stable (Stretch). Apparently the protocol changed between beta2 and the current version, making these clients incompatible. Hopefully the protocol will not be made incompatible in the future.

It is worth noting that while looking at Jami and its features, I came across another communication platform I have not tested yet. The Tox protocol and family of Tox clients. It might become the topic of a future blog post.

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

The first book I published, Free Culture by Lawrence Lessig, is still selling a few copies. Not a lot, but enough to have contributed slightly over $500 to the Creative Commons Corporation so far. All the profit is sent there. Most books are still sold via Amazon (83 copies), with Ingram second (49) and Lulu (12) and Machette (7) as minor channels. Bying directly from Lulu bring the largest cut to Creative Commons. The English Edition sold 80 copies so far, the French 59 copies, and Norwegian only 8 copies. Nothing impressive, but nice to see the work we put down is still being appreciated. The ebook edition is available for free from Github.

It is fun to see the French edition being more popular than the English one.

If you would like to translate and publish the book in your native language, I would be happy to help make it happen. Please get in touch.

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.

A while back a college and friend from Debian and the Skolelinux / Debian Edu project approached me, asking if I knew someone that might be interested in helping out with a technology project he was running as a teacher at L'école franco-danoise - the Danish-French school and kindergarden. The kids were building robots, rovers. The story behind it is to build a rover for use on the dark side of the moon, and remote control it. As travel cost was a bit high for the final destination, and they wanted to test the concept first, he was looking for volunteers to host a rover for the kids to control in a foreign country. I ended up volunteering as a host, and last week the rover arrived. It took a while to arrive after it was built and shipped, because of customs confusion. Luckily we were able fix it quickly with help from my colleges at work.

This is what it looked like when the rover arrived. Note the cute eyes looking up on me from the wrapping

Once the robot arrived, we needed to track down batteries and figure out how to build custom firmware for it with the appropriate wifi settings. I asked a friend if I could get two 18650 batteries from his pile of Tesla batteries (he had them from the wrack of a crashed Tesla), so now the rover is running on Tesla batteries.

Building the rover firmware proved a bit harder, as the code did not work out of the box with the Arduino IDE package in Debian Buster. I suspect this is due to a unsolved license problem with arduino blocking Debian from upgrading to the latest version. In the end we gave up debugging why the IDE failed to find the required libraries, and ended up using the Arduino Makefile from the arduino-mk Debian package instead. Unfortunately the camera library is missing from the Arduino environment in Debian, so we disabled the camera support for the first firmware build, to get something up and running. With this reduced firmware, the robot could be controlled via the controller server, driving around and measuring distance using its internal acoustic sensor.

Next, With some help from my friend in Denmark, which checked in the camera library into the gitlab repository for me to use, we were able to build a new and more complete version of the firmware, and the robot is now up and running. This is what the "commander" web page look like after taking a measurement and a snapshot:

If you want to learn more about this project, you can check out the The Dark Side Challenge Hackaday web pages.

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

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:

• Roll out OData handling to all endpoints where applicable
• Changed the relation key for "ny-journalpost" to the official one.
• Better link generation on outgoing links.
• Tidy up code and make code and approaches more consistent throughout the codebase
• Update rels to be in compliance with updated version in the interface standard
• Avoid printing links on empty objects as they can't have links
• Small bug fixes and improvements
• Start moving generation of outgoing links to @Service layer so access control can be used when generating links
• Log exception that was being swallowed so it's traceable
• Fix name mapping problem
• Update templated printing so templated should only be printed if it is set true. Requires more work to roll out across entire application.
• Remove Record->DocumentObject as per domain model of n5v4
• Add ability to delete lists filtered with OData
• Return NO_CONTENT (204) on delete as per interface standard
• Introduce support for ConstraintViolationException exception
• Make Service classes extend NoarkService
• Make code base respect X-Forwarded-Host, X-Forwarded-Proto and X-Forwarded-Port
• Update CorrespondencePart* code to be more in line with Single Responsibility Principle
• Make package name follow directory structure
• Make sure Document number starts at 1, not 0
• Fix isues discovered by FindBugs
• Update from Date to ZonedDateTime
• Fix wrong tablename
• Introduce Service layer tests
• Improvements to CorrespondencePart
• Continued work on Class / Classificationsystem
• Fix feature where authors were stored as storageLocations
• Update HQL builder for OData
• Update OData search capability from webpage

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.

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.

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