Document and Document Version

Document

Document (Dokument) is an entity representing the description of an electronic document stored in the archive.

  • Being a core Noark5 model entity, Document (Dokument) is managed using the POST /transaction operation.
  • Single Document (Dokument) entity instance can be owned by a single record and cannot be shared accross records
  • All of the types of records can have a Document (Dokument) entity attached to them
  • Document (Dokument) cannot be created without a transaction::link action to an entity on the records level through refRegistrering reference

Diagram showing the relation of Document (Dokument) to any other entities through its reference fields. The diagram depicts the most important set of fields, leaving some of the use cases out of it for simplicity. child-parent-relation

Data Fields

Common Data Fields

Following the Noark5 specification requirements and the internal implementation details the following set of data fields are present for all entities :

Field Name Type Noark Metadata No. Required on Create Value Always Available Modifiable Description
id string unique entity identifier in the specific Documaster installation, used for referencing the entity in the API. The id for created entities is a numeric value.
Default : new value generated on creation
Sortable
version string contains the verions of the entity, used for optimistic locking
Default : sequence version number of the entity
uuid string M001 globally unique identification of the entity, an UUID value (sysemId)
Default : new value generated on creation
Indexed, Sortable
opprettetDato timestamp M600 date and time at which the entity was created (createdDate)
Default : current date time
Indexed, Sortable
opprettetAv string M601 name of the user that created the entity (createdBy)
Default : logged in user name
Sortable
opprettetAvBrukerIdent string M601 identifier of the user that created the entity (createdByIdent)
Default : logged in user identifier
Sortable

Dokument Specific Data Fields

Field Name Type Noark Metadata No. Required on Create Value Always Available Modifiable Description
avsluttetDato timestamp M602 date and time when the archive unit was finalized (finalizedDate)
Sortable
avsluttetAv string M603 name of the user who finalized the archive unit (finalizedBy)
Sortable
avsluttetAvBrukerIdent string M603 unique identifier of the user who finalized the archive unit (finalizedByIdent)
Sortable
dokumenttype string M083 type of document (documentType)
Code List : dokumenttype
dokumentstatus string M054 status of the document (documentStatus)
Code List : dokumentstatus
Default : B - Dokumentet er under redigering
tittel string M020 title of the document (title)
Indexed, Sortable
beskrivelse string M021 description of the document (description)
forfatter string M024 author of the document
Sortable
dokumentmedium string M300 indication of whether the archive unit contains physical documents, electronic documents or a mixture of physical and electronic documents
Code List : dokumentmedium
Default : E - Elektronisk arkiv
Indexed
tilknyttetRegistreringSom string M217 indication of the role the document has in relation to the record (main document, attachment) (linkedToRecordAs)
Code List : tilknyttetRegistreringSom
dokumentnummer number M007 sequence number of the document withint the record (documentNumber)
Default : sequence number in the context of the record
Indexed, Sortable
kassasjonsvedtak string M450 action to be performed at the end of the preservation period (disposalAction)
Code List : kassasjonsvedtak
kassasjonshjemmel string M453 authority for disposal (disposalAuthority)
Code List : kassasjonshjemmel
bevaringstid number M451 number of year the document should be kept before being scheduled for disposal (retentionPeriod)
Sortable
skjerming string M500 indication that the documents belonging to the registry entry are not publicly available in accordance with the Public Access to Information Act (offentlighetsloven) or for any other reason (accessRestriction)
Code List : skjerming
Indexed
forventetKassasjonsDato timestamp expected disposal date
Sortable
kassertDato timestamp M630 date at which the document was disposed (disposedDate)
Sortable
kassertAv string M631 name of the user who performed the disposal of the document (disposedBy)
Sortable
kassertAvBrukerIdent string unique identifier of the user who disposed the document
Sortable
virksomhetsspesifikkeMetadata object M711 overarching metadata element that can contain custom metadata. When metadata for an entity is updated, the whole of it is ovewritten. Examples for handling business specific metadata can be found in the usage section of the page. (businessSpecificMetadata)
Not Queryable

Reference Fields

Field Name Referenced Entity Type Cardinality Link Required on Create Modifiable Description
refRegistrering Registrering 1 reference to the record (Journalpost, Saksmappe, Moeteregistrering) to which the Document (Dokument) belongs
Returned
refDokumentversjon Dokumentversjon 0 . . * reference to a list of Document Versions (Dokumentversjon) of the Document (Dokument)
refEksternId EksternId 0 . . * reference to a list of External ID (EksternId) entities, containing the document identification in external systems
refMerknad Merknad 0 . . * reference to a list of Notes (‘Merknad’) entities associated with the Document (Dokument)

Document Version

Document Version (Dokumentversjon) is an entity representing a specific version of the Document (Dokument).

  • Entity name in the API : Dokumentversjon.
  • Being a core Noark5 model entity, Document Version (Dokumentversjon) is created/modified using the Transaction :: POST /transaction operation.
  • Document Version (Dokumentversjon) can be created only after an electronic document has been uploaded upfront with the Upload :: POST /upload operation.

Electronic document should be uploaded before creating the Document Version (Dokumentversjon). The upload of the document should be done with the same account as the one creating the Document Version (Dokumentversjon) later on.

Data Fields

Common Data Fields

Following the Noark5 specification requirements and the internal implementation details the following set of data fields are present for all entities :

Field Name Type Noark Metadata No. Required on Create Value Always Available Modifiable Description
id string unique entity identifier in the specific Documaster installation, used for referencing the entity in the API. The id for created entities is a numeric value.
Default : new value generated on creation
Sortable
version string contains the verions of the entity, used for optimistic locking
Default : sequence version number of the entity
uuid string M001 globally unique identification of the entity, an UUID value (sysemId)
Default : new value generated on creation
Indexed, Sortable
opprettetDato timestamp M600 date and time at which the entity was created (createdDate)
Default : current date time
Indexed, Sortable
opprettetAv string M601 name of the user that created the entity (createdBy)
Default : logged in user name
Sortable
opprettetAvBrukerIdent string M601 identifier of the user that created the entity (createdByIdent)
Default : logged in user identifier
Sortable

Dokumentversjon Specific Data Fields

Field Name Type Noark Metadata No. Required on Create Value Always Available Modifiable Description
versjonsnummer number M005 identification of the document version (versionNumber)
Indexed, Sortable
variantformat string M700 variant of the document - production, archive, … (variantFormat)
Code List : variantformat
format string M701 format of the document - mime type representing the document format (format)
Sortable
formatDetaljer string M702 additional specification of the format of the document, compression, etc. (formatDetails)
Sortable
sjekksum string M705 checksum of the document (checksum)
sjekksumAlgoritme string M706 algorithm used to calculate the checksum of the document (checksumAlgorithm)
filstoerrelse number M707 the size of the file in bytes specified with decimal numbers (fileSize)
kryptertDokument boolean indication whether the document is encrypted (encryptedDocument)
filnavn string file name of the document (fileName)
Sortable
innholdstype string identified by the system content type (contentType)
referanseDokumentfil string M218 identifier of the uploaded electronic document coming in the result of the call to Upload :: POST /upload (referenceElectronicDocument)
Sortable

Reference Fields

Field Name Referenced Entity Type Cardinality Link Required on Create Modifiable Description
refDokument Dokument 1 reference to Document (Dokument), a Document Version (Dokumentversjob) is owned by a single Document and cannot be attached to any other
refEksternId EksternId 0 . . * reference to a list of External ID (EksternId) entities, containing the document identification in external systems

Working with Document and Document Version

Creating Document and Document Version

Document (Dokument) and Document Version (Dokumentversjon) entities are created using the POST /transaction operation. A Document (Dokument) entitiy can be created withouth corresponding Document Version (Dokumentversjon) entity, but this is a very specific use case, so the samples below represent the creation of both the entities and how the electronic document is associated to the newly created Document Version (Dokumentversjon) through the POST /upload operation.

Document (Dokument) entity should be linked to one of the Record (Registrering) types available.

Upload an electronic document

Uploading a document is done using the POST /upload operation. The file content is streamed in the API request and as a result the API returns a new unique identifier of this electronic document. The document is deleted from Documaster Archive in case it is not linked for a certain period of time to a DocumentVersion (Documentverjion) and from there to a Document (Dokument).

The ID of the electronic document is not the same ID as the one of the Document (Dokument) entity objects. Document (Dokument) entity object is metadata describing the document, while the ID returned as a result of this operation identfies the actually uploaded document.

      Request

POST https://<documaster-instance>.local.documaster.tech:8083/rms/api/public/noark5/v1/upload HTTP/1.1
...
Authorization: Bearer {{accessTokenIntegrator}}
Content-Disposition: attachment; filename="sample-document.pdf"; filename*=utf-8''sample-document.pdf
Content-Type: application/octet-stream

... binary file content ...

      Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id":"999"
}

ID of the electronic document is extracted from $.id of the response.

Document (Dokument) and DocumentVersion (Dokumentversjion) are created using the POST /transaction operation. The electronic document ID, retrieved as the result of the POST /upload operation is used in the creation of the DocumentVersion(Dokumentversjion) through the field $.actions[?(@.action == 'save' && @.type=='Dokumentversjon')].fields.referanseDokumentfil, which is a field of DocumentVersion.

      Request

POST https://<documaster-instance>.local.documaster.tech:8083/rms/api/public/noark5/v1/transaction HTTP/1.1
...
Authorization: Bearer {{accessTokenIntegrator}}
Content-Type: application/json
X-Documaster-Error-Response-Type: application/json

{
    "actions": [
        {
            "action": "save",
            "type": "Dokument",
            "id": "dokument-temp-id-1",
            "fields": {
                "tittel": "sample-document.pdf",
                "tilknyttetRegistreringSom": "V"
            }
        },
        {
            "action": "link",
            "type": "Dokument",
            "id": "dokument-temp-id-1",
            "ref": "refRegistrering",
            "linkToId": "994"
        },
        {
            "action": "save",
            "type": "Dokumentversjon",
            "id": "dokumentversjon-temp-id-1",
            "fields": {
                "format": "pdf",
                "referanseDokumentfil": "1079",
                "variantformat": "P"
            }
        },
        {
            "action": "link",
            "type": "Dokumentversjon",
            "id": "dokumentversjon-temp-id-1",
            "ref": "refDokument",
            "linkToId": "dokument-temp-id-1"
        }
    ]
}

      Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "saved": {
        "dokument-temp-id-1": {
            "type": "Dokument",
            "id": "1081",
            "version": "7",
            "fields": {
                "uuid": "8775e127-29ad-48de-a549-7a0c75ab0bd2",
                "opprettetDato": "2021-11-25T14:58:35.242+0100",
                "opprettetAv": "External Integrator ACME",
                "opprettetAvBrukerIdent": "e6e6318e-fdcb-41cb-ae3a-1940f98ea153",
                "dokumentstatus": "B",
                "tittel": "sample-document.pdf",
                "dokumentmedium": "E",
                "tilknyttetRegistreringSom": "V",
                "dokumentnummer": 2
            },
            "links": {
                "refRegistrering": 994
            }
        },
        "dokumentversjon-temp-id-1": {
            "type": "Dokumentversjon",
            "id": "1082",
            "version": "5",
            "fields": {
                "uuid": "f20796a3-3550-4c87-85dd-36bc18cc65f7",
                "opprettetDato": "2021-11-25T14:58:35.250+0100",
                "opprettetAv": "External Integrator ACME",
                "opprettetAvBrukerIdent": "e6e6318e-fdcb-41cb-ae3a-1940f98ea153",
                "versjonsnummer": 1,
                "variantformat": "P",
                "format": "pdf",
                "kryptertDokument": false,
                "sjekksum": "59844ce7572b1411445179c25e4182e328e43391d733782828277f22e340166b",
                "sjekksumAlgoritme": "SHA-256",
                "filstoerrelse": 3191,
                "filnavn": "sample-document.pdf",
                "referanseDokumentfil": "1079",
                "innholdstype": "application/pdf"
            },
            "links": {
                "refDokument": 1081
            }
        }
    }
}