Oppkobling skjer mot en hoved-URL og er den eneste ressursen klienten trenger å vite for å starte interaksjon. Resten av endepunkter oppdages av klienten via relasjonsnøkler som beskriver hva ressursen kan brukes til.

Request

GET https://n5.example.com/api

Accept: application/vnd.noark5+json

Response

Content-Type: application/vnd.noark5+json

{
    "_links": {
        "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/": {
            "href": "https://n5.example.com/api/arkivstruktur"
        },
        "https://rel.arkivverket.no/noark5/v5/api/sakarkiv/": {
            "href": "https://n5.example.com/api/sakarkiv"
        },
        "https://rel.arkivverket.no/noark5/v5/api/admin/system/": {
            "href": "https://n5.example.com/api/admin/system/",
        }
    }
}

Eksempelet viser at denne arkivkjernen støtter arkivstruktur (https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/) og sakarkiv (https://rel.arkivverket.no/noark5/v5/api/sakarkiv/). Ved å følge href til disse relasjonsnøkler vil tilgjengelige ressurser innen disse områder annonseres på samme måte.

Resultatkoder

href kan være hva som helst og trenger ikke følge noe fast mønster for oppbygning av url. Mens rel (relasjonsnøkkelen) har faste verdier som beskriver hva ressursen kan brukes til. Denne kan klienten også åpne for å vise beskrivelse, eksempel på bruk, statuskoder og annet som er relevant for denne relasjonsnøkkelen.

Relasjonsnøkler på rotnivå

Relasjonsnøkler under de forskjellige konformitetsnivå listes ut i kapittel 7 sammen med beskrivelse av klasser.

Spesielle relasjonsnøkler

Ressurser bør kun gjøres tilgjengelig i API når pålogget bruker har tilgang til disse. Hvis en bruker ikke har tilgang til å avslutte en mappe så bør ikke relasjonsnøkkel for dette annonseres i API for å gjøre det lettere å navigere til aktuelle funksjoner.

En kan identifisere hvilken entitet en oppføring har ved å først identifisere «self»-relasjonsnøkkelen i «_links»-listen, deretter identifisere hvilken annen oppføring som har samme href som "self"-relasjonsnøkkelen. Relasjonsnøkkelen til oppføringen som har samme href som «self» representerer entitetsrelasjonsnøkkelen til «self». Dette kan se slik ut:

{ "results": [
  { ...
    "_links": {
      "self": {
        "href": "https://n5.example.com/api/sakarkiv/saksmappe/2624ed49-dc39-47d5-8966-52f9fdc75868/"
      },
      "https://rel.arkivverket.no/noark5/v5/api/sakarkiv/saksmappe/": {
        "href": "https://n5.example.com/api/sakarkiv/saksmappe/2624ed49-dc39-47d5-8966-52f9fdc75868/"
      },
      ...
    }
  } ]
}

Når en tar GET mot href for relasjonsnøkkelen https://rel.arkivverket.no/noark5/v5/api/admin/system/, så får en informasjon om API-tjenersystemet. Responsen inneholder følgende felter:

Responsen kan for eksempel se slik ut:

{
  "leverandoer": "Hoffleverandøren",
  "produkt": "Arkivsystemet Noark 5 kjerne",
  "versjon": "0.1",
  "versjonsdato": "2019-03-22",
  "protokollversjon": "1.0 Beta"
}

Det kan være en sikkerhetsmessig fordel å unngå å fortelle potensielle angripere hvilken versjon som kjører på maskinen. Det kan derfor være lurt å kun gjøre dette endepunktet tilgjengelig for innloggede brukere.

For filter skal syntaks fra oData standarden (http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html) benyttes. De ressurser som støtter filter skal annonserer dette under _links med templated=true og parametre som kan brukes til dette i href. Feltet «templated» er valgfritt og verdien skal antas å være «false» hvis det ikke finnes. Typiske parametre er $filter, $top, $skip og $orderby. Alle lister med data bør støtte søk og filtrering. Ressurslisten i _links er alfabetisk sortert på «rel»-feltet i henhold til ASCII-verdi.

{
    "_links": {
        "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/arkiv/": {
            "href": "https://n5.example.com/api/arkivstruktur/arkiv{?$filter&$orderby&$top&$skip&$search}",
            "templated": true
        },
        "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/ny-arkivskaper/": {
            "href": "https://n5.example.com/api/arkivstruktur/ny-arkivskaper"
        },

Figur 1 annonsering av templated link for søk etter arkiv

Filter parametre som skal støttes er:

Nivå på filter

{ "results" : [
    { "mappeID": "1234/2017",
      "tittel": "testmappe 1",
      ...
    },
    { "mappeID": "1235/2017",
      "tittel": "testmappe 2",
      ...
    }
  ],
  "count" : 3,
  "_links" : {
    "next": {
      "href": "https://n5.example.com/noark5v4/api/arkivstruktur/mappe/?top=2&skip=2"
    },
    ...
  ]
}

{
  "count": 0,
  "_links" : {
    "self": {
      "href": "https://n5.example.com/api/arkivstruktur/arkiv/"
    },
    "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/arkiv/": {
      "href": "https://n5.example.com/api/arkivstruktur/arkiv/"
    }
  }
}

Nye objekter opprettes fra andre objekter vha. ressurslenker. Slike ressurslenker, f.eks. .../ny-mappe, vises for de underobjekttypene som er aktuelle iht. datamodellen og tilgjengelige med den aktuelle brukerens rettigheter. GET-forespørsler kan benyttes for å få returnert en gyldig og delvis utfylt objektstruktur. POST-forespørsel oppretter nytt objekt. Opprettet objekt vil tilhøre objektet det opprettes fra.

For mappe og klasse som kan ha undermapper og underklasser så vil det være ressurslenkene .../ny-mappe og .../ny-klasse som benyttes for å opprette undermapper og underklasser. Disse blir så tilgjengelige for uthenting med GET-forespørsel til .../undermappe og .../underklasse.

For eksempel kan en opprette mapper på arkivdel, og da vil _links under en arkivdel inneholde relasjonsnøkkelen rel="https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/ny-mappe/" om bruker har lov til å opprette mapper på denne arkivdelen. Den aktuelle ressurslenke kan være https://n5.example.com/api/arkivstruktur/Arkivdel/12345/ny-mappe . Denne kan brukes til både GET og POST forespørsel.

GET-forespørselen forhånds utfyller en lovlig objektstruktur og gir relasjonslenker til aktuelle kodelister. En slik forespørsel oppretter ikke noe objekt og returverdien refererer ikke heller til et objekt i databasen, og er derfor uten «self»-relasjon. Strukturen (uten "_links" og felt med verdi «null») kan brukes som utgangspunkt for en POST når et nytt objekt skal opprettes.

Attributter som henter verdier fra kodelister fylles inn med enten kun kode-verdien fra kodelisten eller både kode og kodenavn. Kodelisteverdiene kopieres fra kodelisten inn i instansen når attributt settes første gang eller endres, slik at fremtidige endringer i kodelister ikke påvirker verdier i eksisterende instanser.

Kun kodelisteverdier der «inaktiv»-attributten ikke er satt til «true» skal brukes på nye instanser eller ved endring av kodelisteverdi på eksisterende instanser.

Ved registrering av objektet så skal kjernen fylle ut systemID, opprettetAv og opprettetDato. OpprettetAv skal være personnavn, referanseOpprettetAv skal være en systemID. NB! Denne systemID-en kan være en entydig identifikator av brukeren i fagsystemet, slik at personen ikke nødvendigvis må være bruker i arkivkjernen. opprettetDato er datoen (eller dataTime) enheten er opprettet i fagsystemet.

{
    "mappetype": {
        "kode": "BYGG",
        "kodenavn": "Byggesak"
    },
    "tittel": "angi tittel på mappe",
    "dokumentmedium": {
        "kode": "E",
        "kodenavn": "Elektronisk arkiv"
    },
    "_links": {
        "https://rel.arkivverket.no/noark5/v5/api/metadata/dokumentmedium/": {
            "href": "https://n5.example.com/api/kodelister/Dokumentmedium{?$filter&$orderby&$top&$skip}",
            "templated": true
        },
        "https://rel.arkivverket.no/noark5/v5/api/metadata/mappetype/": {
            "href": "https://n5.example.com/api/kodelister/Mapetype{?$filter&$orderby&$top&$skip}",
            "templated": true
        }
    }
}

Klienten sender en POST forespørsel med en lovlig objektstruktur til gitt url. Responsen gir statuskode 201 Created om objektet ble opprettet korrekt og komplett objekt samt location header for lese eller endre url.

POST til https://n5.example.com/api/arkivstruktur/Arkivdel/12345/ny-mappe

Content-Type: application/vnd.noark5+json

{
    "mappetype": {
        "kode": "BYGG",
        "kodenavn": "Byggesak"
    },
    "tittel", "Testvegen 32, ny enebolig",
    "dokumentmedium": {
        "kode": "E",
        "kodenavn": "Elektronisk arkiv"
    }
}

Resultat

201 Opprettet

Location →

https://n5.example.com/api/arkivstruktur/Mappe/a043d07b-9641-44ad-85d8-056730bc89c8

{
    "mappeID": "123456/2016",
    "mappetype": {
        "kode": "BYGG",
        "kodenavn": "Byggesak"
    },
    "tittel", "Testvegen 32, ny enebolig",
    "dokumentmedium": {
        "kode": "E",
        "kodenavn": "Elektronisk arkiv"
    },
    "systemID": "515c45b5-e903-4320-a085-2a98813878ba",
    "opprettetDato": "2016-04-03T15:45:28.4985538+02:00",
    "opprettetAv": "pålogget bruker",
    "referanseOpprettetAv": "4ff78c87-6e41-40cb-bc6b-edff1ce685b9",
    "_links": {
        "self": {
            "href": "https://n5.example.com/api/arkivstruktur/Mappe/515c45b5-e903-4320-a085-2a98813878ba"
        },
        "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/mappe/": {
            "href": "https://n5.example.com/api/arkivstruktur/Mappe/515c45b5-e903-4320-a085-2a98813878ba",
        },
        "https://rel.arkivverket.no/noark5/v5/api/sakarkiv/utvid-til-saksmappe/": {
            "href": "https://n5.example.com/api/arkivstruktur/Mappe/515c45b5-e903-4320-a085-2a98813878ba/utvid-til-saksmappe",
        },

Figur 2 respons fra opprett mappe (eksempel avkortet for liste over links)

Heleide objekter(komposisjoner) kan opprettes sammen med hovedobjektet og inngår i dens lovlige objektstruktur. For eksempel merknad på en mappe kan registreres sammen med registreringen av mappe.

Ved å bruke GET på for eksempel ny-mappe (https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/ny-mappe/) så kan arkivkjerne pre-utfylle og foreslå vanlige data for et objekt basert på pålogget bruker samt annonsere hvor diverse lovlige koder kan hentes fra slik som mappetype og dokumentmedium.

{
    "mappetype": {
        "kode": "BYGG",
        "kodenavn": "Byggesak"
    },
    "tittel": "angi tittel på mappe",
    "dokumentmedium": {
        "kode": "E",
        "kodenavn": "Elektronisk arkiv"
    },
    "_links": {
        "https://rel.arkivverket.no/noark5/v5/api/metadata/dokumentmedium/": {
            "href": "https://n5.example.com/api/kodelister/Dokumentmedium{?$filter&$orderby&$top&$skip}",
            "templated": true
        },
        "https://rel.arkivverket.no/noark5/v5/api/metadata/mappetype/": {
            "href": "https://n5.example.com/api/kodelister/Mapetype{?$filter&$orderby&$top&$skip}",
            "templated": true
        }
    }
}

Alle ressurser kan med sin relasjonslenke rel="self" og ressurslenke (href) benytte denne til oppdatering.

For oppdatering sender klienten enten en PUT forespørsel med alle data for en lovlig objektstruktur, eller en PATCH-forespørsel med de enkeltattributtene som skal endres. For PUT må alle egenskaper være med, med unntak av underobjekter som har en mange relasjon (0..* eller 1..*) i oppdatering av et objekt. Underobjekter må oppdateres separat med sine resurslenker.

For å hindre at data blir oppdatert samtidig av forskjellige brukere og overskrevet med gamle data så må kjernen sjekke innkomne objekt og lagret objekt. ETag (https://en.wikipedia.org/wiki/HTTP_ETag) skal benyttes for å støtte «optimistic concurrency control». Om det oppstår konflikt så kan resultatkode 409 benyttes. Da må klient hente opp ny versjon fra arkivkjerne og gjøre fletting av data mellom server og klient. For å redusere risikoen for konflikt bør derfor klienten alltid hente en fersk utgave av objektet med en GET-forespørsel og deretter oppdatere objektet med en PUT-forespørsel.

PUT til https://n5.example.com/api/arkivstruktur/Mappe/a043d07b-9641-44ad-85d8-056730bc89c8

Content-Type: application/vnd.noark5+json

{
    "mappeID": "123456/2016",
    "mappetype": {
        "kode": "BYGG",
        "kodenavn": "Byggesak"
    },
    "tittel", "Testvegen 32, ny enebolig",
    "dokumentmedium": {
        "kode": "E",
        "kodenavn": "Elektronisk arkiv"
    },
    "systemID": "515c45b5-e903-4320-a085-2a98813878ba",
    "opprettetDato": "2016-04-03T15:45:28.4985538+02:00",
    "opprettetAv": "pålogget bruker",
    "referanseOpprettetAv": "4ff78c87-6e41-40cb-bc6b-edff1ce685b9",
    "gradering": {
        "graderingskode": {
            "kode": "B"
        },
        "graderingsdato": "2016-05-03T16:05:48.4966742+02:00"
    }
}

Resultat

200 OK

Location →

https://n5.example.com/api/arkivstruktur/Mappe/a043d07b-9641-44ad-85d8-056730bc89c8

{
    "mappeID": "123456/2016",
    "mappetype": {
        "kode": "BYGG",
        "kodenavn": "Byggesak"
    },
    "tittel", "Testvegen 32, ny enebolig",
    "dokumentmedium": {
        "kode": "E",
        "kodenavn": "Elektronisk arkiv"
    },
    "gradering": {
        "graderingskode": {
            "kode": "B"
        },
        "graderingsdato": "2016-05-03T16:05:48.4966742+02:00"
    },
    "systemID": "515c45b5-e903-4320-a085-2a98813878ba",
    "oppdatertDato": "2016-05-03T16:10:01.9386215+02:00",
    "opprettetDato": "2016-04-03T15:45:28.4985538+02:00",
    "opprettetAv": "pålogget bruker",
    "oppdatertAv": "pålogget bruker",
    "referanseOppdatertAv": "8f58d80c-9b5c-4ddf-af5a-764f08a7661e",
    "referanseOpprettetAv": "4ff78c87-6e41-40cb-bc6b-edff1ce685b9",
    "_links": {
        "self": {
            "href": "https://n5.example.com/api/arkivstruktur/Mappe/515c45b5-e903-4320-a085-2a98813878ba"
        },
        "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/mappe/": {
            "href": "https://n5.example.com/api/arkivstruktur/Mappe/515c45b5-e903-4320-a085-2a98813878ba"
        },
        "https://rel.arkivverket.no/noark5/v5/api/sakarkiv/utvid-til-saksmappe/": {
            "href": "https://n5.example.com/api/arkivstruktur/Mappe/515c45b5-e903-4320-a085-2a98813878ba/utvid-til-saksmappe"
        },

Figur 3 respons fra oppdatering av mappe med graderingsinformasjon (eksempel avkortet ved links liste)

Endring av instanser med PATCH gjøres slik det er beskrevet i IETF RFC 7396 (JSON Merge Patch). Kun de attributtene som skal endres i en instans sendes over, med Content-Type satt til «application/merge-patch+json». Dette sikrer at en API-klient kan gjøre endringer i instanser uten å måtte forstå hele JSON-strukturen, og uten å risikere å endre på andre felter enn ønsket.

API-klienter kan også endre på relasjoner i _links ved hjelp av PATCH.

Her er et eksempel som endrer Mappe-instansen som ble returnert for PUT gjengitt over:

PATCH til https://n5.example.com/api/arkivstruktur/Mappe/a043d07b-9641-44ad-85d8-056730bc89c8

Content-Type: application/merge-patch+json

{
    "tittel", "Testvegen 33, ny enebolig",
    "gradering": {
        "graderingskode": {
            "kode": "F"
        }
    }
}

Resultat

200 OK

Location →

https://n5.example.com/api/arkivstruktur/Mappe/a043d07b-9641-44ad-85d8-056730bc89c8

{
    "mappeID": "123456/2016",
    "mappetype": {
        "kode": "BYGG",
        "kodenavn": "Byggesak"
    },
    "tittel", "Testvegen 33, ny enebolig",
    "dokumentmedium": {
        "kode": "E",
        "kodenavn": "Elektronisk arkiv"
    },
    "gradering": {
        "graderingskode": {
            "kode": "F"
        },
        "graderingsdato": "2016-05-03T16:05:48.4966742+02:00"
    },
    "systemID": "515c45b5-e903-4320-a085-2a98813878ba",
    "oppdatertDato": "2016-05-03T16:10:01.9386215+02:00",
    "opprettetDato": "2016-04-03T15:45:28.4985538+02:00",
    "opprettetAv": "pålogget bruker",
    "oppdatertAv": "pålogget bruker",
    "referanseOppdatertAv": "8f58d80c-9b5c-4ddf-af5a-764f08a7661e",
    "referanseOpprettetAv": "4ff78c87-6e41-40cb-bc6b-edff1ce685b9",
    "_links": {
        "self": {
            "href": "https://n5.example.com/api/arkivstruktur/Mappe/515c45b5-e903-4320-a085-2a98813878ba"
        },
        "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/mappe/": {
            "href": "https://n5.example.com/api/arkivstruktur/Mappe/515c45b5-e903-4320-a085-2a98813878ba"
        },
    ...
    }
}

Slik kan en flytter en dokumentbeskrivelse fra en registrering til en annen:

PATCH til https://n5.example.com/api/arkivstruktur/Dokumentbeskrivelse/1fa94a89-3550-470b-a220-92dd4d709044

{
    "_links": {
        "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/registrering/": {
            "href": "https://n5.example.com/api/arkivstruktur/registrering/cf8e1d0d-e94d-4d07-b5ed-46ba2df0465e/dokumentbeskrivelse/"
         }
    }
}

Hvis en ikke ønsker å opprette en instans med riktig entitet direkte ved å bruke ny-xx-metodene, men ønsker å utvide en entitet fra en basisentitet til en underentitet uten å endre systemID, så kan en bruke *utvid-til-xx-metodene. Dette gjelder for eksempel Mappe og Saksmappe.

Ved uthenting av en mappe vil du få følgende relasjon tilbake:

"https://rel.arkivverket.no/noark5/v5/api/sakarkiv/utvid-til-saksmappe/": {
    "href": "https://n5.example.com/api/sakarkiv/Saksmappe/1/utvid-til-saksmappe"
}

Ved å kjøre PUT-forespørsel på angitt href med tilhørende felter som er påkrevd for saksmappe så skal objektet utvides til å bli en saksmappe.

PUThttps://n5.example.com/api/sakarkiv/Saksmappe/1/utvid-til-saksmappe

Content-Type: application/vnd.noark5+json

{
    "saksansvarlig": "Arne",
    "saksdato": "2017-12-08T00:00:00",
    "saksstatus": {
        "kode": "R",
    "kodenavn": "Opprettet av saksbehandler"
    }
}

Respons skal være den nye saksmappen. Merk at self nå peker på saksmappe og ikke mappe.

{
    "saksdato": "2017-12-08T00:00:00",
    "saksansvarlig": "Henning",
    "saksstatus": {
        "kode": "R",
        "kodenavn": "Opprettet av saksbehandler"
    },
    "mappeID": "1/2014",
    "tittel": "klok testmappe 1",
    "offentligTittel": "Dette er en offentlig tittel ****",
    "gradering": {
        "graderingskode": {
            "kode": "B"
        },
        "graderingsdato": "2017-12-08T15:32:10.739027+01:00",
        "_links": {}
    },
    /// Resten av objektet utelatt
    "_links": {
        "self": {
            "href": "https://n5.example.com/api/sakarkiv/saksmappe/1"
        },

Resultatkode 400 leveres dersom id til eksisterende mappe er ugyldig eller det mangler påkrevde felter.

Noen entiteter kan ha samme type entitet under seg, og slik danne et rekursivt hierarki av instanser. Det gjelder Arkiv, Klasse og Mappe, og entiteter som arver fra disse (som Saksmappe).

Da det ikke er i tråd med HATEOAS-prinsippene å la samme relasjonsnøkkel peke til flere ulike href-er, så må dette håndteres litt annerledes enn relasjoner mellom entiteter av ulik type. Listen over under-instanser til en gitt instans kan hentes ut ved å følge href for relasjonsnøkkelen https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/underxx/, der xx er navnet på entitet. Eksempler på slike relasjonsnøkler https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/underklasse/ og https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/undermappe/.

Av samme grunn er det ikke mulig å la foreldrerelasjonen gjenbruke entitetens relasjonsnøkkel. En kan der finne foreldreinstans ved å følge href for relasjonsnøkkelen https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/overxx/. Eksempler på slike relasjonsnøkler https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/overklasse/ og https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/overmappe/.

Kun relasjoner som eksisterer skal vises i relasjonslisten. JSON-listen over relasjoner for en klasseinstans midt i et slikt hierarki kan for eksempel se slik ut:

"_links": {
  "self": {
    "href": "https://n5.example.com/api/arkivstruktur/klasse/7b3989b0-53d7-11e9-bd4e-17d6c4d53856/"
  },
  "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/klasse/": {
    "href": "https://n5.example.com/api/arkivstruktur/klasse/7b3989b0-53d7-11e9-bd4e-17d6c4d53856/"
  },
  "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/overklasse/": {
    "href": "https://n5.example.com/api/arkivstruktur/klasse/6787ba68-53d7-11e9-a583-8f084aaf5d19/"
  },
  "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/underklasse/": {
    "href": "https://n5.example.com/api/arkivstruktur/klasse/?$filter=overklasse eq 7b3989b0-53d7-11e9-bd4e-17d6c4d53856"
  },
  ...
}

Merk at konkrete href-verdier ikke er standardisert, det er valgfritt hvordan en implementerer oppslag i foreldre- og undermapper.

Overxx-relasjonen er kun tilstede når instansen er midt i og nederst i hierarkiet, og underxx-relasjonen er kun til stede når instansen er øverst og midt i hierarkiet.

Relasjoner kan angis ved tildelte attributter eller via plassering på gitt url. For eksempel ny mappe knyttes til arkivdel ved at url til ny mappe også inneholder hvilken arkivdel denne skal opprettes på. Egne attributter kan for eksempel være referanseForeldremappe for å lage undermapper.

Mer generelt kan klienter benytte href for rel="self" for aktuelle objekter sammen med $ref parameter for å slette, endre eller opprette referanser mellom objekter.

Når en oppdaterer en toveis relasjon mellom to instanser med relasjonsnavn på begge sider, så blir relasjonen også synlig på den andre siden av relasjonen. For eksempel hvis en legger inn en lenke fra en Arkivdel A til forrige Arkivdel B ved hjelp av «forrigearkivdel»-relasjonsnøkkelen, så blir det automatisk en lenke til neste Arkivdel A i Arkivdel B synlig med «nestearkivdel»-relasjonsnøkkel.

For å opprette ny referanse

Her opprettes ny referanse mellom registrering og dokumentbeskrivelse.

POST https://n5.example.com/api/arkivstruktur/registrering/cf8e1d0d-e94d-4d07-b5ed-46ba2df0465e/dokumentbeskrivelse/$ref?$id=https://n5.example.com/api/arkivstruktur/Dokumentbeskrivelse/1fa94a89-3550-470b-a220-92dd4d709044

Resultatkode 204 – NoContent

For å oppdatere/flytte referanse

Her flyttes mappen fra en arkivdel til en annen.

PUT https://n5.example.com/api/arkivstruktur/mappe/cf8e1d0d-e94d-4d07-b5ed-46ba2df0465e/arkivdel/$ref

Body:

https://n5.example.com/api/arkivstruktur/arkivdel/092e497a-a528-4121-8f22-fbc78fa6c930

Resultatkode 204 – NoContent

For å slette referanser fra en liste

Ved sletting av referanser i en liste skal $id-parameteren benyttes. Her slettes referansen til dokumentbeskrivelse fra registrering.

DELETE https://n5.example.com/api/arkivstruktur/registrering/cf8e1d0d-e94d-4d07-b5ed-46ba2df0465e/dokumentbeskrivelse/$ref?$id=https://n5.example.com/api/arkivstruktur/Dokumentbeskrivelse/092e497a-a528-4121-8f22-fbc78fa6c930

Resultatkode 204 – NoContent

For å slette en enkelt-referanse

Ved sletting av en enkelt-referanse så skal ikke $id-parameteren benyttes. Her slettes referansen til registrering fra dokumentbeskrivelse.

DELETE https://n5.example.com/api/arkivstruktur/dokumentbeskrivelse/092e497a-a528-4121-8f22-fbc78fa6c930/registrering/$ref

Resultatkode 204 – NoContent

I Noark 5 er kassasjon beskrevet i et eget kapittel, mens sletting er omtalt i ulike krav spredt utover i ulike kapitler i standarden.

Et viktig krav i Noark 5 er at arkiverte elektroniske dokumenter ikke skal kunne slettes. Et arkivert dokument (Journalstatus på Journalpost og Dokumentstatus på Dokumentbeskrivelse) har følgende kjente verdier:

Journalført (J), Ferdigstilt fra saksbehandler (F), Godkjent av leder (G), Ekspedert (E), Utgår (U), Midlertidig registrering av innkommet dokument (M), Saksbehandler har registrert innkommet dokument (hovedsaklig e-post) (S) og Reservert dokument (ikke ferdigstilt) (R).

Dokumenter med status R (Reservert dokument) kan slettes. Dokumenter med status M (Midlertidig) kan benyttes ulikt i forskjellige organ / systemer, så disse kan eksempelvis ikke slettes om de er overført fra et fagsystem hvor de har status F og er satt opp til å få status M i Noark-systemet.

For dokumenter som ikke er knyttet til Journalpost, må man se på verdier knyttet til Dokumentbeskrivelse og Dokumentstatus når man vurderer om et dokument kan slettes.

Når det foreligger behov for autorisert kassasjon sender klienten en DELETE forespørsel på aktuell ressurs (URL). Alle ressurslenker med relasjonsnøkkel "self" kan potensielt slettes om autorisert bruker har nødvendige rettigheter. Respons har statuskode 204 hvis ressursen ble slettet.

Klienten sender en DELETE forespørsel på aktuell ressurs(url). Alle ressurslenker med rel="self" kan potensielt slettes om bruker har nødvendige rettigheter. Respons gir statuskode 204 om ressursen er korrekt slettet.

{
    "tittel": "Arkivdel byggesak",
    "beskrivelse": "Lorem ipsum",
    "arkivdelstatus": {
        "kode": "",
        "kodenavn": ""
    },
    "dokumentmedium": {
        "kode": "",
        "kodenavn": ""
    },
    "avsluttetAv": "",
    "referanseAvsluttetAv": "",
    "referanseForloeper": "",
    "referanseArvtaker": "",
    "kassasjon": {
        "kassasjonsvedtak": {
            "kode": "",
            "kodenavn": ""
        },
        "kassasjonshjemmel": "",
        "bevaringstid": "",
        "kassasjonsdato": "0001-01-01T00:00:00"
    },
    "utfoertKassasjon": {
        "kassertDato": "0001-01-01T00:00:00"
        "kassertAv": "",
        "referanseKassertAv": ""
    },
    "sletting": {
        "slettingstype": {
            "kode": "SA",
            "kodenavn": "Sletting av hele innholdet i arkivdelen"
        },
        "slettedato": "2016-05-02T14:23:27.4065323+02:00",
        "slettetAv": "pålogget bruker"
    },
    "skjerming": {
        "tilgangsrestrisjon": {
            "kode": "",
            "kodenavn": ""
        },
        "skjermingshjemmel": "",
        "skjermingsdokument": {
            "kode": "",
            "kodenavn": ""
        },
        "skjermingsvarighet": ""
    },
    "gradering": {
        "graderingskode": {
            "kode": "",
            "kodenavn": ""
        },
        "graderingsdato": "0001-01-01T00:00:00",

Innholdstyper(Content-Type) som skal brukes:

Datoformat skal være angitt i tråd med definisjonen i Noark 5 krav 5.12.7 (datoer uten klokkeslett) og 5.12.8 (datoer med klokkeslett), det vil si definisjonen for date og dateTime i XML Schema 1.0 tilgjengelig fra https://www.w3.org/TR/xmlschema11-2/. Det skal alltid være tidssone-informasjon knyttet til date og dateTime-verdier.

Tjenestegrensesnittet skal bruke UTF-8 tegnsett som beskrevet i IETF RFC 3629 i alle REST-forespørsler.

Ved navigering til dokumentobjekt så kan selve filen også åpnes ved å følge referanseDokumentfil eller href til relasjonsnøkkel https://rel.arkivverket.no/noark5/v4/arkivstruktur/fil/.

GET https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785

{
    "systemID": "a895c8ed-c15a-43f6-86de-86a626433785",
    "versjonsnummer": "1",
    "variantformat": {
        "kode": "A",
        "kodenavn": "Arkivformat"
    },
    "format": {
        "kode": "fmt/95",
        "kodenavn": "PDF/A - ISO 19005-1:2005"
    },
    "referanseDokumentfil": "https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785/referanseFil",
    "_links": {
        "self": {
            "href": "https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785"
        },
        "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/dokumentobjekt/": {
            "href": "https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785"
        },
        "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/fil/": {
            "href": "https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785/referanseFil"
        }
    }
}

Formatverdier (her «fmt/95») hentes fra kodelisten Format, se kapittel 7.

GET https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785/referanseFil

Returnerer med Content-type=filens MIME-type, for eksempel «application/pdf», og filen streames til klient. Hodefeltet Content-type settes til filens MIME-type hentet fra dokumentobjekt-entiteten. Merk, GET-forespørselen bør ikke inneholde HTTPs Accept-hodefelt, alternativt bør akseptere enhver MIME-type. HTTP-hodefeltet Accept brukes til å gi beskjed hvilket helst format som ønskes lastet ned, og klienten har ikke noe valg av format og bør derfor ikke forsøke å styre valg av format. Hvis Accept-hodefeltet er satt, og ikke inneholder enten «/» eller er stemmer med verdien i mimeType-feltet til tilhørende dokumentobjekt, så returneres resultatkoden 406, ikke resultatkode 200.

Overføre små filer

For å overføre en ny fil brukes POST til href til rel="https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/fil/" med headere for content-type og content-length. Når overføringen er fullført og filopplastingen vellykket, så returneres statuskode 201.

Et dokumentobjekt opprettes før opplasting. Hvis noen av feltene «format», «mimeType», «filnavn», «sjekksum», «sjekksumAlgoritme» og «filstoerrelse» er fylt inn ved opprettelsen skal tjeneren verifisere at verdiene i de angitte feltene stemmer når den komplette filen er lastet opp. Tjeneren sjekker ved opplasting for felt som er forhåndsutfylt også at mimeType er identisk med Content-Type, filstoerrelse er identisk med Content-Length (for komplett POST) eller X-Upload-Content-Length (for overføring i bolker med PUT) og at sjekksum stemmer overens med den overførte filen. Hvis tjeneren etter opplasting ser at noen av verdiene avledet fra opplastet fil ikke stemmer overens med verdiene i dokumentobjekt-entiteten, så returneres statuskode 400 Bad Request. Hvis den opplastede filen har et format tjeneren ikke kjenner igjen, så settes formatkoden til 'av/0'. Når filopplasting er fullført setter tjeneren de feltene i dokumentobjekt som ikke var satt ved oppretting av dokumentobjekt-entiteten, det vil si utleder «format», «mimeType», «filnavn», «sjekksum», og «filstoerrelse» basert på filens innhold samt, samt gir «sjekksumAlgoritme» aktuell verdi.

POST https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785/referanseFil
Content-Type: application/pdf
Content-Length: 111111

Pdf data

Respons: 201 Created

Overføre store filer

For store filer (over 150MB) så kan filen overføres i bolker. Prosessen for å overføre store filer er inspirert av APIet til Google Drive, https://developers.google.com/drive/v3/web/resumable-upload . For hver bolk returneres statuskode 200, unntatt den siste når overføringen er fullført der det returneres statuskode 201.

For å starte en opplastingssesjon:

Det er ikke mulig å overskrive filen tilhørende en eksisterende dokumentobjekt-entitet med en POST eller en PUT-forespørsel. Hvis en fil må erstattes etter fullført opplasting så skal dokumentobjekt-entieten slettes og en ny POST/PUT utføres mot href til rel=https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/fil/.

Når en filopplasting er vellykket, så returneres tilhørende dokumentobjekt som respons på avsluttende 200 OK / 201 Created.

Dersom det skjer en feil under opplasting eller lagringsprosessen skal tjeneren returnere 422 Unprocessable Entity som svar. Det er da klientens ansvar å slette relaterte dokumentbeskrivelse- og dokumentobjekt-entiteter ved hjelp av DELETE på entitetenes self-relasjon.

Komplett eksempel

Opprett sesjon:

POST https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785/referanseFil
Content-Length: 0
X-Upload-Content-Type: image/jpeg
X-Upload-Content-Length: 2000000

Respons: 200 OK

Location: https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785/referanseFil?filsesjon=abc1234567

Last opp første del:

PUT https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785/referanseFil?filsesjon=abc1234567
Content-Length: 524288
Content-Type: image/jpeg
Content-Range: bytes 0-524287/2000000

Respons: 200 OK

Location: https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785/referanseFil?filsesjon=abc1234567
Range: bytes 0-524287

Last opp siste del:

PUT https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785/referanseFil?filsesjon=abc1234567
Content-Length: 427136
Content-Type: image/jpeg
Content-Range: bytes 1572864-2000000/2000000

Respons: 201 Created

{
    "systemID": "e37be679-f87b-4485-a680-4c3e3c529bdf",
    "versjonsnummer": "1",
    "variantformat": {
        "kode": "A",
        "kodenavn": "Arkivformat"
    },
    "format": {
        "kode": "RA-JPEG",
        "kodenavn": "JPEG (ISO 10918-1:1994)"
    },
    "filnavn": "portrait.jpeg",
    "filstoerrelse": 2000000,
    "mimeType": "image/jpeg",
    "sjekksum": "40cbd5b88175e268ef3a1c286ad7d46ff69c22787d368e8635cae7edca4b5625",
    "sjekksumAlgoritme": "SHA-256",
    "referanseDokumentfil": "https://n5.example.com/api/arkivstruktur/Dokumentobjekt/e37be679-f87b-4485-a680-4c3e3c529bdf/referanseFil",
    "_links": {
        "self": {
            "href": "https://n5.example.com/api/arkivstruktur/Dokumentobjekt/e37be679-f87b-4485-a680-4c3e3c529bdf"
        },
        "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/dokumentobjekt/": {
            "href": "https://n5.example.com/api/arkivstruktur/Dokumentobjekt/e37be679-f87b-4485-a680-4c3e3c529bdf"
        },
        "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/fil/": {
            "href": "https://n5.example.com/api/arkivstruktur/Dokumentobjekt/e37be679-f87b-4485-a680-4c3e3c529bdf/referanseFil"
        }
    }
}

Type: Class

Arver: Arkivenhet

Arkiv er det øverste nivået i arkivstrukturen. De fleste brukere vil bare ha behov for å opprette ett arkiv i sin Noark 5-løsning. Men det skal være mulig å opprette flere arkiver. Det kan være aktuelt dersom flere organer deler samme løsning. Det kan også være aktuelt dersom en hel etat deler samme løsning. Her kan da f.eks. hovedkontoret og hvert distriktskontor settes opp med hvert sitt arkiv. Men ved elektronisk arkivering er det heller ikke noe i veien for at hele etaten deler samme arkiv, selv om de enkelte avdelinger er spredt over et stort geografisk område.

Arkiv er obligatorisk i et arkivuttrekk. Toppnivået skal bare ha én forekomst, men kan ha ett eller flere undernivåer, se om underarkiv nedenfor. Et arkiv skal inneholde en eller flere arkivdeler. Dersom arkivet består av underarkiver, skal arkivdel være knyttet til det laveste nivået av disse.

Type: Class

Arver: Arkivenhet

Et arkiv skal kunne deles opp i arkivdeler for å gruppere arkivet etter overordnede kriterier. De viktigste kriteriene for oppdeling i arkivdeler er:

Arkivdel er obligatorisk i et arkivuttrekk, og skal forekomme én eller flere ganger i et arkiv. Dersom arkivet er delt opp i underarkiver, skal arkivdel bare kunne knyttes til det laveste arkivnivået. Dersom det dreier seg om et sakarkiv, skal arkivdelen inneholde et primært klassifikasjonssystem. Arkivdelen kan i tillegg inneholde et eller flere sekundære klassifikasjonssystemer. I et fagsystem uten klassifikasjon, skal arkivdelen inneholde én eller flere mapper. I et fagsystem uten klassifikasjon og mapper, skal arkivdelen inneholde én eller flere registreringer.

Arkivdeler kan brukes til å skille ut dokumenter som skal kasseres etter andre regler enn resten av dokumentene i mappen (f.eks. alle inngående dokumenter) eller registreringen (f.eks. alle vedlegg). Slike regler kan da knyttes til en egen arkivdel. Se mer om dette i Noark 5 v5.0 kapittel 6.1 Bevaring og kassasjon, om kassasjon av dokumenttyper. Det samme gjelder dokumenter som skal skjermes etter andre regler enn resten av dokumentene i mappen eller registreringen. Se mer under Noark 5 v5.0 kapittel 2.8.1 Skjerming.

Dessuten kan det være tilfeller hvor noen dokumenter i en mappe eller registrering er arkivert på papir, mens resten av dokumentene er elektroniske. En egen arkivdel skiller da ut disse dokumentene.

Arkivdeler som brukes til å angi andre kassasjonsvedtak, skjermingsregler og dokumentmedium enn de som gjelder for resten av innholdet i arkivet, vil være "tomme" – dvs. de har ikke egne barn. Mapper, registreringer og dokumentbeskrivelse som har referanse til slike arkivdeler, skal arve metadata fra disse. Disse mappene, registreringene og dokumentbeskrivelsene vil indirekte også tilhøre arkivdelen som er utgangspunktet for den hierarkiske arkivstrukturen, men arv herfra blir overstyrt.

Hvis pakken Sakarkiv er tilgjengelig, så skal følgende relasjonsnøkkel også være tilgjengelig via Arkivdel-instanser.

Merk at underliggende lister med Saksmappe og andre underentiteter er tilgjengelig via relasjonsnøkkel https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/mappe/, dermed er det ikke egne relasjonsnøkler for å hente ut lister med de spesifikke under-entitetene.

Type: Class

Arver:

En arkivenhet (se Noark 5 v5.0 krav 2.2.2) skal kunne identifiseres entydig innenfor det arkivskapende organet. I et arkivuttrekk skal denne identifikasjonen hete systemID, og være entydig på tvers av alle uttrekk som organet produserer, dermed også på tvers av alle systemer organet benytter. Også arkivenheter som dupliseres i et arkivuttrekk, skal identifiseres entydig, slik at identiske arkivenheter har ulik systemID.

Type: Class

Arver: Arkivenhet

Tradisjonelt har et arkiv blitt definert etter organisasjon. Ett organ skaper ett arkiv, dvs. organet er arkivskaperen. Men elektronisk informasjonsteknologi har ført til at det blir stadig vanligere at flere arkivskapere sammen skaper ett arkiv. Arkivet vil da være definert etter funksjon, ikke organisasjon.

I en Noark 5-løsning skal det altså være mulig å knytte en eller flere arkivskapere til ett arkiv. Informasjon om arkivskapere er obligatorisk i arkivuttrekk.

Type: Class

Arver: Arkivenhet

En registrering inneholder alle metadata fra registrering og basisregistrering i Noark 5 versjon 4, samt andre metadata som er obligatoriske i alle typer arkivsystemer. En registrering kan være utgangspunkt for andre registreringstyper for spesialiserte fagsystemer.

Hvis en ønsker å opprette en forenklet registrering uten tittel (kalt registrering i Noark 5 versjon 4), så skal tittel-attributten settes til «[forenklet registrering]». En kan også bruke Arkivnotat. Instanser av registrering med denne tittelen og der ingen andre attributter enn de fra Arkivenhet og arkivertAv, arkivertDato, gradering, kassasjon, referanseArkivdel, referanseArkivertAv og skjerming (det forenklede attributtsett) er i bruk, kan deponeres og avleveres som registrering i deponi-XML. Denne tittelverdien skal kun brukes for instanser som kun har det forenklede attributtsett. Hvis flere attributter er brukt, så må en benytte basisregistrering i slik XML ved avlevering som Noark 5 versjon 4.

Hvis pakken Sakarkiv er tilgjengelig, så skal følgende relasjonsnøkler også være tilgjengelig via Registrering-instanser som har en Saksmappe som foreldre.

Type: Class

Arver: Arkivenhet

Et dokument er et informasjonsobjekt som kan behandles som en enhet. For å understreke at det dreier seg om en enhet, kan vi bruke begrepet enkeltdokument. En registrering som dokumenterer en transaksjon, vil vanligvis bestå av bare ett enkeltdokument. Dokumentbeskrivelsen inneholder altså metadata for enkeltdokumenter.

Type: Class

Arver: Arkivenhet

Dokumentobjekt er det laveste metadatanivået i arkivstrukturen. Et dokumentobjekt skal referere til én og kun en dokumentfil. Dokumentfila inneholder selve dokumentet. Dersom dokumentet er arkivert i flere versjoner, må vi ha et dokumentobjekt og en dokumentfil for hver versjon. Hver versjon av dokumentet kan dessuten arkiveres i flere forskjellige formater, og da må det i tillegg opprettes egne dokumentobjekter og dokumentfiler for hvert format. I noen tilfeller kan det også være aktuelt å lage varianter av enkelte dokumenter. Den mest vanlige varianten vil være et "sladdet" dokument hvor taushetsbelagt informasjon er fjernet slik at varianten kan være offentlig tilgjengelig. Dokumentobjektet inneholder mer tekniske metadata enn de andre arkivenhetene, bl.a. sjekksummen til bytesekvensen som representerer dokumentet.

Ved avlevering i tråd med XML-skjema for Noark 5 versjon 4 og versjon 5 så droppes følgende felt arvet fra Arkivenhet: «endretDato», «endretAv», «referanseEndretAv» og «referanseOpprettetAv». Disse ikke har korresponderende felt i avleveringsformatet.

Type: Class «dataType»

Arver:

Type: Class «dataType»

Arver:

Type: Class «dataType»

Arver:

Metadata for gradering skal grupperes inn i metadata for mappe, registrering og dokumentbeskrivelse. Gradering er valgfritt, og kan forekomme en gang

Type: Class «dataType»

Arver:

Kassasjon vil si at elektroniske dokumenter fjernes fra arkivstrukturen. Dersom dokumentet ikke er tilknyttet andre registreringer, innebærer en kassasjon også at dokumentet slettes helt fra Noark 5-løsningen. Kassasjon av fysiske dokumenter vil si at de plukkes ut fra stedet de oppbevares, og makuleres eller destrueres på en betryggende måte.

Inneholder vedtak om kassasjon. Kassasjonsvedtak bestemmer hvilket arkivmateriale som skal fjernes fra arkivet og tilintetgjøres. (Se Noark 5 v5.0 eget kapittel: 6.1 Bevaring og kassasjon)

Metadata for bevaring og kassasjon skal grupperes inn i metadata for arkivdel, klasse, mappe, registrering og dokumentbeskrivelse. Funksjonalitet for kassasjon er obligatorisk i alle Noark 5-løsninger, men det kan gis dispensasjon til fagsystemløsninger hvor kassasjon er uaktuelt.

Overordnede kassasjonsbestemmelser kan settes på arkiv- og klassenivå, og skal da arves nedover i arkivstrukturen til mappe, registrering og dokumentbeskrivelse. Verdiene som arves skal kunne overstyres. Ved deponering/avlevering er det bare kassasjonsvedtak som innebærer kassasjon som skal være med. Det skal altså ikke knyttes opplysninger om kassasjon til arkivenheter hvor alle tilordnede dokumenter skal bevares. Kassasjon kan altså være knyttet en gang til arkivdel, klasse, mappe, registrering og dokumentbeskrivelse.

Type: Class

Arver: Arkivenhet

Et klassifikasjonssystem er bygd opp av klasser. Ved funksjonsbasert (emnebasert) klassifikasjon vil klassene vanligvis inngå i et hierarki, hvor tre eller fire nivåer er det vanlige. I den konseptuelle modellen er undernivåene kalt underklasser, og fremkommer som en egenrelasjon i Klasse.

ISO 15489 anbefaler at klassene beskriver organets funksjoner og aktiviteter (forretningsprosesser). Øverste nivå vil da typisk beskrive hovedfunksjonene, nivå to kan beskrive underfunksjoner og nivå tre prosessene (dvs. aktiviteter som stadig gjentas).

Klassene skal ha en egen identifikasjon som er unik innenfor klassifikasjonssystemet. Dette tilsvarer det som er kalt ordningsverdi eller arkivkode i Noark-4. Identifikasjoner fra overordnede klasser skal arves nedover i hierarkiet, slik at det er lett å si hvilket nivå en befinner seg på.

Hvis pakken Sakarkiv er tilgjengelig, så skal følgende relasjonsnøkler også være tilgjengelig via Klasse-instanser.

Type: Class

Arver: Arkivenhet

Moderne arkivteori legger vekt på at klassifikasjonssystemet skal være funksjonsbasert. Alle virksomheter utøver et bestemt antall funksjoner. Disse er ofte stabile over tid, men funksjoner kan overføres fra en virksomhet til en annen. Et eksempel på en slik overføring er når saksområder flytter fra et departement til et annet, noe som ofte skjer i forbindelse med et regjeringsskifte. En virksomhet vil vanligvis bare ha et fåtall hovedfunksjoner, men disse er det naturlig å dele opp i underfunksjoner.

Funksjoner/underfunksjoner deles inn i aktiviteter. I motsetning til en funksjon, har en aktivitet en begynnelse og en slutt. En aktivitet har også deltakere, og den fører til et resultat. Dersom en aktivitet stadig gjentar seg, tilhører den en prosess. Alle arkivdokumenter som produseres når en aktivitet utføres, skal normalt tilhøre samme (saks)mappe.

Type: Class «dataType»

Arver:

Type: Class

Arver:

Alle arkivdokumenter som skal avleveres må være i arkivformat. Konvertering til arkivformat skal foretas senest ved avslutning av mappe (jf. Noark 5 v5.0 krav 2.7.1). Systemet skal logge alle konverteringer, og informasjon om dette skal tas med ved deponering/avlevering.

Type: Class

Arver:

Korrespondansepart er obligatorisk, og skal forekomme en eller flere ganger i en journalpost. Ved inngående dokumenter er det obligatorisk å registrere avsender(e), ved utgående dokumenter mottaker(e). Ved organinterne dokumenter som skal følges opp, må både avsender(e) og mottaker(e) registreres.

Type: Class

Arver: Korrespondansepart

Type: Class

Arver: Korrespondansepart

Type: Class

Arver: Korrespondansepart

Type: Class

Arver: Arkivenhet

Dette er en referanse på tvers av hierarkiet i arkivstrukturen. Referansen kan gå fra en mappe til en annen mappe, fra en registrering til en annen registrering, fra en mappe til en registrering og fra en registrering til en mappe. Det kan også refereres fra en klasse til en annen klasse.

Kryssreferanse er valgfritt, og kan knyttes en eller flere ganger til klasse, mappe og registrering. Referansen går en vei, dvs. den kan kun være en referanse til en arkivenhet. I og med at kryssreferanser knyttes til Mappe og Registrering, vil det si at Referanser også knyttes til alle utvidelsene (spesialiseringer) under disse (Saksmappe og Journalpost).

Ved avlevering i tråd med XML-skjema for Noark 5 versjon 5.0 så droppes samtlige felt arvet fra Arkivenhet, da disse ikke har korresponderende felt i dette avleveringsformatet.

Kryssreferanser opprettes med en POST-forespørsel og bruker ODATA $ref tilnærmingen. Hvis det er mulig å lage en kryssreferanse fra en arkivenhet vil relasjonsnøkkelen https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/ny-kryssreferanse/ være en del av _links. En klient kan sende en GET forespørsel til href-en assosiert med relasjonsnøkkelen https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/ny-kryssreferanse/ og skal da få tilbake en URL der klienten trenger bare å legge til self-URLen til arkivenheten det ønskes en kryssreferanse til.

Avlevering av relasjonene i Kryssreferanse gjøres som M210, M212 og M219.

Eksempelet under viser hvordan en klient kan opprette en kryssreferanse mellom en mappe identifisert med systemID (051b40e3-a0fe-4c02-acec-828d60c3a4ea) og en klasse identifisert med systemID (42ba4ead-75f5-4a7d-93f9-a9d66471adce).

Klienten sender en GET forespørsel til https://n5.example.com/api/arkivstruktur/mappe/051b40e3-a0fe-4c02-acec-828d60c3a4ea/ny-kryssreferanse/ og får tilbake en URL

{
    "url" : "https://n5.example.com/api/arkivstruktur/mappe/051b40e3-a0fe-4c02-acec-828d60c3a4ea/ny-kryssreferanse/$ref?$id="
}

Klienten skal da legge til URL-adressen til det interne objektet kryssreferansen skal peke til.

POST https://n5.example.com/api/arkivstruktur/mappe/051b40e3-a0fe-4c02-acec-828d60c3a4ea/ny-kryssreferanse/$ref?$id=https://n5.example.com/api/arkivstruktur/klasse/42ba4ead-75f5-4a7d-93f9-a9d66471adce

Dersom opprettelse av kryssreferanse var vellykket returneres det en HTTP status 201 med følgende nyttelast:

{
  "systemID": "852989ee-293d-41fe-b46a-fa3cdf607d74",
  "opprettetDato": "2019-06-30T22:11:35.797+02:00",
  "opprettetAv": "bruker@n5.example.com",
  "endretDato": "2019-06-30T22:11:35.797+02:00",
  "endretAv": "bruker@n5.example.com",
  "_links": {
      "self": {
        "href": "https://n5.example.com/api/arkivstruktur/kryssreferanse/852989ee-293d-41fe-b46a-fa3cdf607d74/"
      },
      "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/kryssreferanse/": {
        "href": "https://n5.example.com/api/arkivstruktur/kryssreferanse/852989ee-293d-41fe-b46a-fa3cdf607d74/"
      },
      "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/klasse/": {
        "href": "https://n5.example.com/api/arkivstruktur/klasse/e66a8e49-d966-496d-a5ca-ad440001e9e1/"
      }
  }
}

Opprettelse av kryssreferansen over gjenspeiles i nyttelasten når du henter mappen som har kryssreferansen. Dette vises i eksempelet under:

{
  "systemID": "3c6caa91-af70-4bd8-9b0b-87601112d927",
  "mappeID": "2019/1",
  "tittel": "Søknad om barnehageplass til Marit Maritsen",
  "offentligTittel": "Søknad om barnehageplass til ***** *****",
  "dokumentmedium": "Elektronisk arkiv",
  "opprettetDato": "2019-06-30T22:11:35.797+02:00",
  "opprettetAv": "bruker@n5.example.com",
  "endretDato": "2019-06-30T22:11:35.797+02:00",
  "endretAv": "bruker@n5.example.com",
  "kryssreferanser": [
     {
       "systemID": "852989ee-293d-41fe-b46a-fa3cdf607d74",
       "opprettetDato": "2019-06-30T22:11:35.797+02:00",
       "opprettetAv": "bruker@n5.example.com",
       "_links": {
         "self": {
           "href": "https://n5.example.com/api/arkivstruktur/kryssreferanse/852989ee-293d-41fe-b46a-fa3cdf607d74/"
         },
         "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/kryssreferanse/": {
           "href": "https://n5.example.com/api/arkivstruktur/kryssreferanse/852989ee-293d-41fe-b46a-fa3cdf607d74/"
         },
         "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/klasse/": {
           "href": "https://n5.example.com/api/arkivstruktur/klasse/e66a8e49-d966-496d-a5ca-ad440001e9e1/"
         }
       }
     }
   ],
   "_links": {
      ....
   }
}

Merk: Det er ikke mulig å opprette duplikat kryssreferanser mellom to entiteter. Eventuelle forsøk på å opprette en duplikat kryssreferanse skal avvises med 400 (Bad Request).

En kryssreferanse kan slettes med en DELETE-forespørsel til self URLen til kryssreferansen. Fra eksempelet over betyr det at kryssreferansen slettes med en DELETE mot https://n5.example.com/api/arkivstruktur/kryssreferanse/852989ee-293d-41fe-b46a-fa3cdf607d74/

En kryssreferanse kan endres. En endringsforespørsel kan kun ende til entiteten. Det er ikke mulig å endre fra entiteten. Klienten må bruke href som tilsvarer self relasjonsnøkkelen for kryssreferansen og legge til "$ref?$id=" etterfulgt at URLen til den nye arkivenheten.

Type: Class

Arver: Arkivenhet

En mappe grupperer dokumenter som på en eller annen måte hører sammen. Helst bør dokumentene i en mappe utgjøre en instans (dvs. en utførelse) av en aktivitet, med en definert begynnelse og slutt. Et eksempel på dette er enkeltsaker i et sakarkiv. En slik sak kan f.eks. omhandle et spørsmål som er til behandling, og dokumentene i saken vil da utgjøre behandlingsforløpet for dette spørsmålet. Slike saker kan typisk starte med en søknad eller henvendelse utenfra, og ende med et vedtak.

Men av og til er det naturlig å gruppere dokumentene i en mappe etter andre kriterier. I noen tilfeller legges alle dokumenter som omhandler et objekt i én mappe, f.eks. personalmapper. Slike mapper kalles også dossiermapper. I andre tilfeller kan det være naturlig å legge alle dokumentene som tilhører samme prosess (dvs. gjentakelse av samme type aktivitet) i samme mappe. Dette vil ofte dreie seg om svært rutinemessige aktiviteter, hvor hver aktivitet kanskje bare skaper ett dokument. I sakarkiver er dette kjent som samlemapper eller samlesaker.

Måten innholdet i en mappe grupperes på, vil avhenge av klassifikasjonssystemet. En trenger ikke nødvendigvis å ha egne personalmapper dersom klassifikasjonssystemet er objektbasert på person. Innholdet i personalmappen kan da ordnes etter aktivitet. Dersom en likevel velger å ha personalmapper, kan klassifikasjonssystemet være på et overordnet nivå med bare noen få klasser. Dokumentene som skapes i et bestemt prosjekt kan samles i en prosjektmappe (med undermapper), men det er sannsynligvis bedre å definere prosjektet i klassifikasjonssystemet og gruppere mappene etter instanser av aktiviteter.

Mapper skal ha en egen identifikasjon som er unik innenfor et og samme arkiv. Noark 5 stiller ingen krav til hvordan denne koden skal se ut. Når det gjelder saksmapper, anbefales det at en fortsetter med samme mal som i tidligere versjoner av Noark-standarden - dvs. en kombinasjon av årstallet da mappen ble opprettet og et fortløpende seksjonsnummer innenfor året, f.eks. 2011/3869.

Hvis pakken Sakarkiv er tilgjengelig, så skal følgende relasjonsnøkler også være tilgjengelig via Mappe-instanser.

Type: Class

Arver:

En eller flere merknader skal kunne knyttes til en mappe, registrering eller en dokumentbeskrivelse. Merknader skal brukes for å dokumentere spesielle forhold rundt saksbehandlingen og arkivering av dokumenter, og denne informasjonen skal tas med i arkivuttrekket.

Type: Class

Arver:

En eller flere virksomheter eller personer kan være knyttet til en mappe eller registrering som parter.

Metadata for part skal kunne grupperes inn i metadata for mappe og registrering. Part er valgfritt, og kan forekomme en eller flere ganger i tilknytning til en mappe og registrering. Dersom det er mer enn én part, må metadataene grupperes sammen ved eksport og utveksling.

Type: Class

Arver: Part

Type: Class

Arver: Part

Type: Class «dataType»

Arver:

Skjerming benyttes til å skjerme registrerte opplysninger eller enkeltdokumenter. Skjermingen trer i kraft når en tilgangskode påføres den enkelte mappe, registrering eller det enkelte dokument. (Se Noark 5 v5.0 eget kapittel: 2.8.1 Skjerming)

Type: Class «dataType»

Arver:

I Noark 5 er kassasjon beskrevet i et eget kapittel, mens sletting er omtalt i ulike krav spredt utover i ulike kapitler i standarden.

Et viktig krav i Noark 5 er at arkiverte elektroniske dokumenter ikke skal kunne slettes. Et arkivert dokument (Journalstatus på Journalpost og Dokumentstatus på Dokumentbeskrivelse) har følgende kjente verdier:

Journalført (J), Ferdigstilt fra saksbehandler (F), Godkjent av leder (G), Ekspedert (E), Utgår (U), Midlertidig registrering av innkommet dokument (M), Saksbehandler har registrert innkommet dokument (hovedsakelig e-post) (S) og Reservert dokument (ikke ferdigstilt) (R).

Dokumenter med status R (Reservert dokument) kan slettes. Dokumenter med status M (Midlertidig) kan benyttes ulikt i forskjellige organ / systemer, så disse kan eksempelvis ikke slettes om de er overført fra et fagsystem hvor de har status F og er satt opp til å få status M i Noark-systemet.

For dokumenter som ikke er knyttet til Journalpost, må man se på verdier knyttet til Dokumentbeskrivelse og Dokumentstatus når man vurderer om et dokument kan slettes.

Når det foreligger behov for autorisert kassasjon sender klienten en DELETE forespørsel på aktuell ressurs (URL). Alle ressurslenker med relasjonsnøkkel "self" kan potensielt slettes om autorisert bruker har nødvendige rettigheter. Respons har statuskode 204 hvis ressursen ble slettet.

Klienten sender en DELETE forespørsel på aktuell ressurs(url). Alle ressurslenker med rel="self" kan potensielt slettes om bruker har nødvendige rettigheter. Respons gir statuskode 204 om ressursen er korrekt slettet.

Dersom et dokument er arkivert i mer enn én versjon, skal det være mulig å slette de eldre versjonene. Vanligvis er det bare den siste, ferdigstilte versjon som skal arkiveres. Men det kan også være aktuelt å arkivere tidligere versjoner dersom disse har dokumentasjonsverdi.

Det kan f.eks. være tilfelle dersom en leder har gjort vesentlige endringer i utkastet til en saksbehandler. Saksbehandlers utkast kan da arkiveres som en tidligere versjon av det ferdige dokumentet. Dette vil gi ekstra dokumentasjon om selve saksbehandlingsforløpet.

Dersom tidligere versjoner er blitt arkivert unødvendig, skal det være mulig å rydde opp på en effektiv måte. Slik opprydding skal alltid skje før det produseres et arkivuttrekk.

Type: Class «dataType»

Arver:

Metadata for utført kassasjon er obligatorisk når kassasjon er utført før arkivuttrekket produseres. Det skal grupperes inn i metadata for dokumentbeskrivelse. Dersom en hel arkivdel er kassert, skal metadata grupperes inn i arkivdel.

Figur 7.20. Nasjonale identifikatorer - (diagram)

Nasjonale identifikatorer gjør tjenestegrensesnittet kompatibelt med GeoIntegrasjon, og gjør det mulig å knytte mapper og registreringer til kataloger som brønnøysundsregisteret, folkeregisteret, matrikkelen og kart.