blog/archive/2019/03/03.rss

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <rss version='2.0' xmlns:lj='http://www.livejournal.org/rss/lj/1.0/'>
   3         <channel>
   4                 <title>Petter Reinholdtsen - Entries from March 2019</title>
   5                 <description>Entries from March 2019</description>
   6                 <link>http://people.skolelinux.org/pere/blog/</link>
   7
   8
   9         <item>
  10                 <title>Release 0.3 of free software archive API system Nikita announced</title>
  11                 <link>http://people.skolelinux.org/pere/blog/Release_0_3_of_free_software_archive_API_system_Nikita_announced.html</link>
  12                 <guid isPermaLink="true">http://people.skolelinux.org/pere/blog/Release_0_3_of_free_software_archive_API_system_Nikita_announced.html</guid>
  13                 <pubDate>Sun, 24 Mar 2019 14:30:00 +0100</pubDate>
  14                 <description>&lt;p&gt;Yesterday,  a new release of
  15 &lt;a href=&quot;https://gitlab.com/OsloMet-ABI/nikita-noark5-core/&quot;&gt;Nikita
  16 Noark 5 core project&lt;/a&gt; was
  17 &lt;a href=&quot;https://lists.nuug.no/pipermail/nikita-noark/2019-March/000451.html&quot;&gt;announced
  18 on the project mailing list&lt;/a&gt;.  The free software solution is an
  19 implementation of the Norwegian archive standard Noark 5 used by
  20 government offices in Norway.  These were the changes in version 0.3
  21 since version 0.2.1 (from NEWS.md):&lt;/p&gt;
  22
  23 &lt;ul&gt;
  24   &lt;li&gt;Improved ClassificationSystem and Class behaviour.&lt;/li&gt;
  25   &lt;li&gt;Tidied up known inconsistencies between domain model and hateaos links.&lt;/li&gt;
  26   &lt;li&gt;Added experimental code for blockchain integration.  &lt;/li&gt;
  27   &lt;li&gt;Make token expiry time configurable at upstart from properties file.&lt;/li&gt;
  28   &lt;li&gt;Continued work on OData search syntax.&lt;/li&gt;
  29   &lt;li&gt;Started work on pagination for entities, partly implemented for Saksmappe.&lt;/li&gt;
  30   &lt;li&gt;Finalise ClassifiedCode Metadata entity.&lt;/li&gt;
  31   &lt;li&gt;Implement mechanism to check if authentication token is still
  32    valid.  This allow the GUI to return a more sensible message to the
  33    user if the token is expired.&lt;/li&gt;
  34   &lt;li&gt;Reintroduce browse.html page to allow user to browse JSON API using
  35    hateoas links.&lt;/li&gt;
  36   &lt;li&gt;Fix bug in handling file/mappe sequence number.  Year change was
  37    not properly handled.&lt;/li&gt;
  38   &lt;li&gt;Update application yml files to be in sync with current development.&lt;/li&gt;
  39   &lt;li&gt;Stop &#39;converting&#39; everything to PDF using libreoffice.  Only
  40    convert the file formats doc, ppt, xls, docx, pptx, xlsx, odt, odp
  41    and ods.&lt;/li&gt;
  42   &lt;li&gt;Continued code style fixing, making code more readable.&lt;/li&gt;
  43   &lt;li&gt;Minor bug fixes.&lt;/li&gt;
  44
  45 &lt;/ul&gt;
  46
  47 &lt;p&gt;If free and open standardized archiving API sound interesting to
  48 you, please contact us on IRC
  49 (&lt;a href=&quot;irc://irc.freenode.net/%23nikita&quot;&gt;#nikita on
  50 irc.freenode.net&lt;/a&gt;) or email
  51 (&lt;a href=&quot;https://lists.nuug.no/mailman/listinfo/nikita-noark&quot;&gt;nikita-noark
  52 mailing list&lt;/a&gt;).&lt;/p&gt;
  53
  54 &lt;p&gt;As usual, if you use Bitcoin and want to show your support of my
  55 activities, please send Bitcoin donations to my address
  56 &lt;b&gt;&lt;a href=&quot;bitcoin:15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b&quot;&gt;15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b&lt;/a&gt;&lt;/b&gt;.&lt;/p&gt;
  57 </description>
  58         </item>
  59
  60         <item>
  61                 <title>Åpen og gjennomsiktig vedlikehold av spesifikasjonen for Noark 5 Tjenestegrensesnitt</title>
  62                 <link>http://people.skolelinux.org/pere/blog/_pen_og_gjennomsiktig_vedlikehold_av_spesifikasjonen_for_Noark_5_Tjenestegrensesnitt.html</link>
  63                 <guid isPermaLink="true">http://people.skolelinux.org/pere/blog/_pen_og_gjennomsiktig_vedlikehold_av_spesifikasjonen_for_Noark_5_Tjenestegrensesnitt.html</guid>
  64                 <pubDate>Mon, 11 Mar 2019 16:00:00 +0100</pubDate>
  65                 <description>&lt;p&gt;Et virksomhetsarkiv for meg, er et arbeidsverktøy der en enkelt kan
  66 finne informasjonen en trenger når en trenger det, og der
  67 virksomhetens samlede kunnskap er tilgjengelig. Det må være greit å
  68 finne frem i, litt som en bibliotek. Men der et bibliotek gjerne tar
  69 vare på offentliggjort informasjon som er tilgjengelig flere steder,
  70 tar et arkiv vare på virksomhetsintern og til tider personlig
  71 informasjon som ofte kun er tilgjengelig fra et sted.&lt;/p&gt;
  72
  73 &lt;p&gt;Jeg mistenker den eneste måten å sikre at arkivet inneholder den
  74 samlede kunnskapen i en virksomhet, er å bruke det som virksomhetens
  75 kunnskapslager. Det innebærer å automatisk kopiere (brev, epost,
  76 SMS-er etc) inn i arkivet når de sendes og mottas, og der filtrere
  77 vekk det en ikke vil ta vare på, og legge på metadata om det som er
  78 samlet inn for enkel gjenfinning. En slik bruk av arkivet innebærer at
  79 arkivet er en del av daglig virke, ikke at det er siste hvilested for
  80 informasjon ingen lenger har daglig bruk for. For å kunne være en del
  81 av det daglige virket må arkivet enkelt kunne integreres med andre
  82 systemer.  I disse dager betyr det å tilby arkivet som en
  83 nett-tjeneste til hele virksomheten, tilgjengelig for både mennesker
  84 og datamaskiner.  Det betyr i tur å både tilby nettsider og et
  85 maskinlesbart grensesnitt.&lt;/p&gt;
  86
  87 &lt;p&gt;For noen år siden erkjente visjonære arkivarer fordelene med et
  88 standardisert maskinlesbart grensesnitt til organisasjonens arkiv.  De
  89 gikk igang med å lage noe de kalte
  90 &lt;a href=&quot;https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/&quot;&gt;Noark
  91 5 Tjenestegrensesnitt&lt;/a&gt;.  Gjort riktig, så åpner slike maskinlesbare
  92 grensesnitt for samvirke på tvers av uavhengige programvaresystemer.
  93 Gjort feil, vil det blokkere for samvirke og bidra til
  94 leverandørinnlåsing.  For å gjøre det riktig så må grensesnittet være
  95 klart og entydig beskrevet i en spesifikasjon som gjør at
  96 spesifikasjonen tolkes på samme måte uavhengig av hvem som leser den,
  97 og uavhengig av hvem som tar den i bruk.&lt;/p&gt;
  98
  99 &lt;p&gt;For å oppnå klare og entydige beskrivelser i en spesifikasjon, som
 100 trengs for å kunne få en fri og åpen standard (se
 101 &lt;a href=&quot;http://people.skolelinux.org/pere/blog/Fri_og__pen_standard__slik_Digistan_ser_det.html&quot;&gt;Digistan-definisjon&lt;/a&gt;),
 102 så trengs det en åpen og gjennomsiktig inngangsport med lav terskel,
 103 der de som forsøker å ta den i bruk enkelt kan få inn korreksjoner,
 104 etterlyse klargjøringer og rapportere uklarheter i spesifikasjonen.
 105 En trenger også automatiserte datasystemer som måler og sjekker at et
 106 gitt grensesnitt fungerer i tråd med spesifikasjonen.&lt;/p&gt;
 107
 108 &lt;p&gt;For Noark 5 Tjenestegrensesnittet er det nå etablert en slik åpen
 109 og gjennomsiktig inngangsport på prosjekttjenesten github.  Denne
 110 inngangsporten består først og fremst av en åpen portal som lar enhver
 111 se hva som er gjort av endringer i spesifikasjonsteksten over tid, men
 112 det hører også med et åpent &amp;quot;diskusjonsforum&amp;quot; der en kan
 113 komme med endringsforslag og forespørsler om klargjøringer.  Alle
 114 registrerte brukere på github kan bidra med innspill til disse
 115 henvendelsene.&lt;/p&gt;
 116
 117 &lt;p&gt;I samarbeide med Arkivverket har jeg fått opprettet et git-depot
 118 med spesifikasjonsteksten for tjenestegrensesnittet, der det er lagt
 119 inn historikk for endringer i teksten de siste årene, samt lagt inn
 120 endringsforslag og forespørsler om klargjøring av teksten.  Bakgrunnen
 121 for at jeg bidro med dette er at jeg er involvert i
 122 &lt;a href=&quot;https://gitlab.com/OsloMet-ABI/nikita-noark5-core&quot;&gt;Nikita-prosjektet&lt;/a&gt;,
 123 som lager en fri programvare-utgave av Noark 5 Tjenestegrensesnitt.
 124 Det er først når en forsøker å lage noe i tråd med en spesifikasjon at
 125 en oppdager hvor mange detaljer som må beskrives i spesifikasjonen for
 126 å sikre samhandling.&lt;/p&gt;
 127
 128 &lt;p&gt;Spesifikasjonen vedlikeholdes i et rent tekstformat, for å ha et
 129 format egnet for versjonskontroll via versjontrollsystemet git.  Dette
 130 gjør det både enkelt å se konkret hvilke endringer som er gjort når,
 131 samt gjør det praktisk mulig for enhver med github-konto å sende inn
 132 endringsforslag med formuleringer til spesifikasjonsteksten.  Dette
 133 tekstformatet vises frem som nettsider på github, slik at en ikke
 134 trenger spesielle verktøy for å se på siste utgave av
 135 spesifikasjonen.&lt;/p&gt;
 136
 137 &lt;p&gt;Fra dette rene tekstformatet kan det så avledes ulike formater, som
 138 HTML for websider, PDF for utskrift på papir og ePub for lesing med
 139 ebokleser.  Avlednings-systemet (byggesystemet) bruker i dag
 140 verktøyene pandoc, latex, docbook-xsl og GNU make til
 141 transformasjonen.  Tekstformatet som brukes dag er
 142 &lt;a href=&quot;https://www.markdownguide.org/&quot;&gt;Markdown&lt;/a&gt;, men det vurderes
 143 å
 144 &lt;a href=&quot;https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/issues/9&quot;&gt;endre
 145 til formatet RST&lt;/a&gt; i fremtiden for bedre styring av utseende på
 146 PDF-utgaven.&lt;/p&gt;
 147
 148 &lt;p&gt;Versjonskontrollsystemet git ble valgt da det er både fleksibelt,
 149 avansert og enkelt å ta i bruk. Github ble valgt (foran f.eks. Gitlab
 150 som vi bruker i Nikita), da Arkivverket allerede hadde tatt i bruk
 151 Github i andre sammenhenger.&lt;/p&gt;
 152
 153 &lt;p&gt;Enkle endringer i teksten kan gjøres av priviligerte brukere
 154 direkte i nettsidene til Github, ved å finne aktuell fil som skal
 155 endres (f.eks. kapitler/03-konformitet.md), klikke på den lille
 156 bokstaven i høyre hjørne over teksten. Det kommer opp en nettside der
 157 en kan endre teksten slik en ønsker. Når en er fornøyd med endringen
 158 så må endringen &amp;quot;sjekkes inn&amp;quot; i historikken. Det gjøres ved
 159 å gi en kort beskrivelse av endringen (beskriv helst hvorfor endringen
 160 trengs, ikke hva som er endret), under overskriften &amp;quot;Commit
 161 changes&amp;quot;. En kan og bør legge inn en lengre forklaring i det
 162 større skrivefeltet, før en velger om endringen skal sendes direkte
 163 til &#39;master&#39;-grenen (dvs. autorativ utgave av spesifikasjonen) eller
 164 om en skal lage en ny gren for denne endringen og opprette en
 165 endringsforespørsel (aka &amp;quot;Pull Request&amp;quot;/PR). Når alt dette
 166 er gjort kan en velge &amp;quot;Commit changes&amp;quot; for å sende inn
 167 endringen. Hvis den er lagt inn i &amp;quot;master&amp;quot;-grenen så er den
 168 en offisiell del av spesifikasjonen med en gang.  Hvis den derimot er
 169 en endringsforespørsel, så legges den inn i
 170 &lt;a href=&quot;https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/pulls&quot;&gt;listen
 171 over forslag til endringer&lt;/a&gt; som venter på korrekturlesing og
 172 godkjenning.&lt;/p&gt;
 173
 174 &lt;p&gt;Større endringer (for eksempel samtidig endringer i flere filer)
 175 gjøres enklest ved å hente ned en kopi av git-depoet lokalt og gjøre
 176 endringene der før endringsforslaget sendes inn. Denne prosessen er
 177 godt beskrivet i dokumentasjon fra github.  Git-prosjektet som skal
 178 &amp;quot;klones&amp;quot; er
 179 &lt;a href=&quot;https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/&quot;&gt;https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/&lt;/a&gt;.&lt;/p&gt;
 180
 181 &lt;p&gt;For å registrere nye utfordringer (issues) eller kommentere på
 182 eksisterende utfordringer benyttes nettsiden
 183 &lt;a href=&quot;https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/issues&quot;&gt;https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/issues&lt;/a&gt;.
 184 I skrivende stund er det 48 åpne og 11 avsluttede utfordringer.  Et
 185 forslag til hva som bør være med når en beskriver en utfordring er
 186 tilgjengelig som utfordring
 187 &lt;a href=&quot;https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/issues/14&quot;&gt;#14&lt;/a&gt;.&lt;/p&gt;
 188
 189 &lt;p&gt;For å bygge en PDF-utgave av spesifikasjonen så bruker jeg i dag en
 190 Debian GNU/Linux-maskin med en rekke programpakker installert.  Når
 191 dette er på plass, så holder det å kjøre kommandoen &#39;make pdf html&#39; på
 192 kommandolinjen, vente ca. 20 sekunder, før spesifikasjon.pdf og
 193 spesifikasjon.html ligger klar på disken. Verktøyene for bygging av
 194 PDF, HTML og ePub-utgave er også tilgjengelig på Windows og
 195 MacOSX.&lt;/p&gt;
 196
 197 &lt;p&gt;Github bidrar med rammeverket.  Men for at åpent vedlikehold av
 198 spesifikasjonen skal fungere, så trengs det folk som bidrar med sin
 199 tid og kunnskap.  Arkivverket har sagt de skal bidra med innspill og
 200 godkjenne forslag til endringer, men det blir størst suksess hvis alle
 201 som bruker og lager systemer basert på Noark 5 Tjenestegrensesnitt
 202 bidrar med sin kunnskap og kommer med forslag til forebedringer.  Jeg
 203 stiller.  Blir du med?&lt;/p&gt;
 204
 205 &lt;p&gt;Det er viktig å legge til rette for åpen diskusjon blant alle
 206 interesserte, som ikke krever at en må godta lange kontrakter med
 207 vilkår for deltagelse. Inntil Arkivverket dukker opp på IRC har vi
 208 laget en IRC-kanal der interesserte enkelt kan orientere seg og
 209 diskutere tjenestegrensesnittet. Alle er velkommen til å ta turen
 210 innom
 211 &lt;a href=&quot;https://webchat.freenode.net/?channels=nikita&quot;&gt;#nikita&lt;/a&gt;
 212 (f.eks. via irc.freenode.net) for å møte likesinnede.&lt;/p&gt;
 213
 214 &lt;p&gt;Det holder dog ikke å ha en god spesifikasjon, hvis ikke de som tar
 215 den i bruk gjør en like god jobb. For å automatisk teste om et konkret
 216 tjenestegrensesnitt følger (min) forståelse av
 217 spesifikasjonsdokumentet, har jeg skrevet et program som kobler seg
 218 opp til et Noark 5v4 REST-tjeneste og tester alt den finner for å se
 219 om det er i henhold til min tolkning av spesifikasjonen.  Dette
 220 verktøyet er tilgjengelig fra
 221 &lt;a href=&quot;https://github.com/petterreinholdtsen/noark5-tester&quot;&gt;https://github.com/petterreinholdtsen/noark5-tester&lt;/a&gt;,
 222 og brukes daglig mens vi utvikler Nikita for å sikre at vi ikke
 223 introduserer nye feil.  Hvis en skal sikre samvirke på tvers av ulike
 224 systemer er det helt essensielt å kunne raskt og automatisk sjekke at
 225 tjenestegrensesnittet oppfører seg som forventet.  Jeg håper andre som
 226 lager sin utgave av tjenestegrensesnittet vi bruke dette verktøyet,
 227 slik at vi tidlig og raskt kan oppdage hvor vi har tolket
 228 spesifikasjonen ulikt, og dermed få et godt grunnlag for å gjøre
 229 spesifikasjonsteksten enda klarere og bedre.&lt;/p&gt;
 230
 231 &lt;p&gt;Dagens beskrivelse av Noark 5 Tjenestegrensesnitt er et svært godt
 232 utgangspunkt for å gjøre virksomhetens arkiv til et dynamisk og
 233 sentralt arbeidsverktøy i organisasjonen.  Blir du med å gjøre den
 234 enda bedre?&lt;/p&gt;
 235 </description>
 236         </item>
 237
 238         </channel>
 239 </rss>