Endre opplastingsprosedyre til å unngå ufullstendige dokumentobjekt-i…

…nstanser Tillat opplasting direkte fra mappe, registrering, dokumentbeskrivelse og dokumentobjekt. Endre fra dagens opplastingsprosedyre, som har et mellomsteg der arkivet er i en ufullstendig tilstand, mellom oppretting av dokumentobjekt-instans og vellykket opplasting av arkivfil, og i stedet la en laste opp fil directe fra dokumentbeskrivelse, registrering og mappe. Etter opplasting returnerer de nyopprettede barneinstansene i _embedded, jamfør JSON Hypertext Application Language. Dette forslaget er basert på ideer i mangelmelding #25, og Løser utfordringer omtalt i mangelmelding #285.
arkivverket · May 13, 2023 · 6185aa3 · 6185aa3
1 parent f985130
commit 6185aa3
Show file tree

Hide file tree

Showing 2 changed files with 178 additions and 15 deletions.
diff --git a/kapitler/06-konsepter_og_prinsipper.rst b/kapitler/06-konsepter_og_prinsipper.rst
@@ -1330,7 +1330,7 @@ GET https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-8
 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
+dokumentobjekt-instansen. 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
@@ -1339,14 +1339,150 @@ 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**
+**Opplasting**
 
-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.
+Opplasting av dokumentfiler kan enten gjøres fra mappe, registrering,
+dokumentbeskrivelse eller dokumentobjekt.  Resultatet fra en vellykket
+opplasting returnerer JSON for det nyopprettede eller oppdaterte
+dokumentobjektet med HATEOAS "_embedded"-informasjon om de
+nyopprettede foreldreentietene som beskrevet i *JSON Hypertext
+Application Language*.  De nyopprettede instansene er ferdig utfylt
+med verdier hentet fra den opplastede filen der det er mulig, eller
+gis verdien 'UNKNOWN'.  Etter opplasting og eventuell nyoppretting av
+instanser så må metadata i de opprettende instansene sjekkes og
+eventuelle 'UNKNOWN'-verdier endres.
+
+Eksempel på oppretting fra registrering
+
+::
+
+   POST https://n5.example.com/api/arkivstruktur/Registrering/f22d76b2-bc51-11ed-96a7-0737240e5910/fil
+   Content-Type: image/jpeg
+   Content-Length: 2000000
+
+   JPEG data
 
-Et dokumentobjekt opprettes før opplasting. Hvis noen av feltene
+   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"
+            },
+            "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/dokumentbeskrivelse/":{
+                "href":"https://n5.example.com/api/arkivstruktur/dokumentbeskrivelse/0003f272-918a-444d-9db0-f76f8b2cb4a7/"
+            }
+        },
+        "_embedded": {
+            "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/dokumentbeskrivelse/":{
+                "systemID":"0003f272-918a-444d-9db0-f76f8b2cb4a7",
+                "dokumenttype":{
+                    "kode":"NQ",
+                    "kodenavn":"Bilde"
+                },
+                "dokumentstatus":{
+                    "kode":"F",
+                    "kodenavn":"Dokumentet er ferdigstilt"
+                },
+                "tittel":"1629",
+                "dokumentnummer":1,
+                "tilknyttetDato":"2021-06-09T11:13:33+02:00",
+                "tilknyttetAv": "pålogget bruker",
+                "referanseTilknyttetAv": "8f58d80c-9b5c-4ddf-af5a-764f08a7661e",
+                "tilknyttetRegistreringSom":{
+                       "kode":"H",
+                       "kodenavn":"Hoveddokument"
+                   },
+                "opprettetDato":"2021-06-09T11:13:33+02:00",
+                "opprettetAv":"[email protected]",
+                "endretDato":"2021-06-09T11:13:33+02:00",
+                "endretAv": "pålogget bruker",
+                "referanseEndretAv": "8f58d80c-9b5c-4ddf-af5a-764f08a7661e",
+                "_links":{
+                    "self":{
+                        "href":"https://n5.example.com/api/arkivstruktur/dokumentbeskrivelse/0003f272-918a-444d-9db0-f76f8b2cb4a7/"
+                    },
+                    "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/dokumentbeskrivelse/":{
+                        "href":"https://n5.example.com/api/arkivstruktur/dokumentbeskrivelse/0003f272-918a-444d-9db0-f76f8b2cb4a7/"
+                    },
+                    "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/registrering/":{
+                        "href":"https://n5.example.com/api/arkivstruktur/dokumentbeskrivelse/0003f272-918a-444d-9db0-f76f8b2cb4a7/registrering"
+                    },
+                    "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/dokumentobjekt/":{
+                        "href":"https://n5.example.com/api/arkivstruktur/dokumentbeskrivelse/0003f272-918a-444d-9db0-f76f8b2cb4a7/dokumentobjekt/"
+                    },
+                    "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/ny-dokumentobjekt/":{
+                        "href":"https://n5.example.com/api/arkivstruktur/dokumentbeskrivelse/0003f272-918a-444d-9db0-f76f8b2cb4a7/ny-dokumentobjekt/"
+                    },
+                    "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/part/":{
+                        "href":"https://n5.example.com/api/arkivstruktur/dokumentbeskrivelse/0003f272-918a-444d-9db0-f76f8b2cb4a7/part/",
+                        "templated":true
+                    },
+                    "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/ny-partperson/":{
+                        "href":"https://n5.example.com/api/arkivstruktur/dokumentbeskrivelse/0003f272-918a-444d-9db0-f76f8b2cb4a7/ny-partperson/"
+                    },
+                    "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/ny-partenhet/":{
+                           "href":"https://n5.example.com/api/arkivstruktur/dokumentbeskrivelse/0003f272-918a-444d-9db0-f76f8b2cb4a7/ny-partenhet/"
+                    },
+                    "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/merknad/":{
+                           "href":"https://n5.example.com/api/arkivstruktur/dokumentbeskrivelse/0003f272-918a-444d-9db0-f76f8b2cb4a7/merknad/"
+                    },
+                    "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/ny-merknad/":{
+                           "href":"https://n5.example.com/api/arkivstruktur/dokumentbeskrivelse/0003f272-918a-444d-9db0-f76f8b2cb4a7/ny-merknad/"
+                    },
+                    "https://rel.arkivverket.no/noark5/v5/api/metadata/graderingskode/":{
+                           "href":"https://n5.example.com/api/metadata/graderingskode"
+                    },
+                    "https://rel.arkivverket.no/noark5/v5/api/metadata/slettingstype/":{
+                           "href":"https://n5.example.com/api/metadata/slettingstype"
+                    },
+                    "https://rel.arkivverket.no/noark5/v5/api/metadata/dokumentmedium/":{
+                           "href":"https://n5.example.com/api/metadata/dokumentmedium"
+                    },
+                    "https://rel.arkivverket.no/noark5/v5/api/metadata/dokumentstatus/":{
+                           "href":"https://n5.example.com/api/metadata/dokumentstatus"
+                    },
+                    "https://rel.arkivverket.no/noark5/v5/api/metadata/dokumenttype/":{
+                           "href":"https://n5.example.com/api/metadata/dokumenttype"
+                    },
+                    "https://rel.arkivverket.no/noark5/v5/api/metadata/tilgangsrestriksjon/":{
+                           "href":"https://n5.example.com/api/metadata/tilgangsrestriksjon"
+                    },
+                    "https://rel.arkivverket.no/noark5/v5/api/metadata/skjermingdokument/":{
+                           "href":"https://n5.example.com/api/metadata/skjermingdokument"
+                    },
+                    "https://rel.arkivverket.no/noark5/v5/api/metadata/skjermingmetadata/":{
+                           "href":"https://n5.example.com/api/metadata/skjermingmetadata"
+                    }
+                }
+            }
+        }
+    }
+
+Et dokumentobjekt også kan opprettes før opplasting når en laster opp
+fil via dokumentobjekcts opplastingsrelasjon.  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
@@ -1356,15 +1492,23 @@ 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
+stemmer overens med verdiene i dokumentobjekt-instansen, 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
+som ikke var satt ved oppretting av dokumentobjekt-instansen, det vil
 si utleder «format», «mimeType», «filnavn», «sjekksum», og
 «filstoerrelse» basert på filens innhold samt, samt gir
 «sjekksumAlgoritme» aktuell verdi.
 
+**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.
+
+
 ::
 
    POST https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785/referanseFil
@@ -1409,19 +1553,18 @@ For å starte en opplastingssesjon:
 #. Når siste overføring er gjort så returneres statuskode 201 Created.
 
 Det er ikke mulig å overskrive filen tilhørende en eksisterende
-dokumentobjekt-entitet med en POST eller en PUT-forespørsel. Hvis en
+dokumentobjekt-instans 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.
+Når en filopplasting er vellykket, så returneres tilhørende instanser
+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.
+klientens ansvar å slette relaterte ikke lenger relevante instanser
+ved hjelp av DELETE på instansenes self-relasjon.
 
 Komplett eksempel
 
@@ -1489,6 +1632,9 @@ Last opp siste del:
            },
            "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/fil/": {
                "href": "https://n5.example.com/api/arkivstruktur/Dokumentobjekt/e37be679-f87b-4485-a680-4c3e3c529bdf/referanseFil"
+           },
+           "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/dokumentbeskrivelse/":{
+               "href":"https://n5.example.com/api/arkivstruktur/dokumentbeskrivelse/9ee41886-bc55-11ed-9ca7-e7af3ac784aa/"
            }
        }
    }

diff --git a/kapitler/07-tjenester_og_informasjonsmodell.rst b/kapitler/07-tjenester_og_informasjonsmodell.rst
@@ -1164,6 +1164,14 @@ 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.
 
+Ved opplasting av fil ved bruk av relasjonen
+https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/fil/ , så vil
+det automatisk opprettes både en dokumentbeskrivelse og et
+dokumentobjekt med forvalgte verdier avledet fra den opplastede filen.
+JSON for disse objektene returneres som en JSON-liste som resultat av
+opplastingen, på eneste forespørslen for små filer og på siste
+forespørsel for store filer.
+
 .. list-table:: Relasjoner
    :widths: 4 5 4 4
    :header-rows: 1
@@ -1226,6 +1234,7 @@ XML ved avlevering som Noark 5 versjon 4.
  * - https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/bygning/
  * - https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/dnummer/
  * - https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/dokumentbeskrivelse/
+ * - https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/fil/
  * - https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/foedselsnummer/
  * - https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/klasse/
  * - https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/korrespondansepart/
@@ -1488,6 +1497,13 @@ begrepet enkeltdokument. En registrering som dokumenterer en
 transaksjon, vil vanligvis bestå av bare ett enkeltdokument.
 Dokumentbeskrivelsen inneholder altså metadata for enkeltdokumenter.
 
+Ved opplasting av fil ved bruk av relasjonen
+https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/fil/ , så vil
+det automatisk opprettes et dokumentobjekt med forvalgte verdier
+avledet fra den opplastede filen.  JSON for dette objektet returneres
+som resultat av opplastingen, på eneste forespørslen for små filer og
+på siste forespørsel for store filer.
+
 .. list-table:: Relasjoner
    :widths: 4 5 4 4
    :header-rows: 1
@@ -1524,6 +1540,7 @@ Dokumentbeskrivelsen inneholder altså metadata for enkeltdokumenter.
  * - self
  * - https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/dokumentbeskrivelse/
  * - https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/dokumentobjekt/
+ * - https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/fil/
  * - https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/merknad/
  * - https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/ny-dokumentbeskrivelse/
  * - https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/ny-dokumentobjekt/