Documaster Noark5 API > Examples > Per Usecase > Create Registry Entry and Document

Create Registry Entry and Document

Usecase Details

Common usecase for an integrating system is to create a Registry Entry(Journalpost) and a single Document(Dokument) with a single DocumentVersion(Dokumentversjon) and an electronic document uploaded. The Registry Entry (Journalpost) is linked to an existing Case File (Saksmappe).

Accomplishing this through the API is done following a set of steps outlined in the diagram below.

child-parent-relation

Authentication and Authorization (1, 2)

Aquiring an OAuth2 access token is done through the configured Identity Provider (IDP) used by the customer. Details on how to get the access token, how it should be cached and renewed can be found in Authentication and Authorization section of the documentation.

Retrieve existing Case File (3, 4, 5)

Already created case files in the Documaster system can be found using the POST /query operation. Recommended case files query criteria would be the case year and sequence number (saksaar and sakssekvensnummer) or an externalID (through refExternId).

Examples below retrieve a case with externalID : ISID:0000004572, case year : 2021 and sequence number : 6.

Query Request by CaseYear and CaseSequenceNumber

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

{
  "type": "Saksmappe",
  "limit": 1,
  "query": "saksaar = @caseYear && sakssekvensnummer = @caseSequenceNumber",
  "parameters" : {
      "@caseYear" : "2021",
      "@caseSequenceNumber" : "6"
  }
}

Query Request by ExternalID

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

{
  "type": "Saksmappe",
  "limit": 1,
  "query": "refEksternId.eksterntSystem = @externalSystemID && refEksternId.eksternID = @externalID",
  "parameters" : {
      "@externalSystemID": "Integrating System 1",
      "@externalID" : "ISID:0000004572"
  }
}

Response

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

{
    "hasMore": false,
    "results": [
        {
            "type": "Saksmappe",
            "id": "981",
            "version": "8",
            "fields": {
                "uuid": "31b474d1-9474-4139-b1e6-2d0ffb77b2e0",
                "opprettetDato": "2021-11-25T13:51:10.494+0100",
                "opprettetAv": "External Integrator ACME",
                "opprettetAvBrukerIdent": "e6e6318e-fdcb-41cb-ae3a-1940f98ea153",
                "mappeIdent": "2021/6",
                "tittel": "API Created Case File",
                "beskrivelse": "First API created Case File",
                "dokumentmedium": "E",
                "saksaar": 2021,
                "sakssekvensnummer": 6,
                "saksdato": "2021-11-25",
                "administrativEnhet": "AD1",
                "saksansvarlig": "External Integrator ACME",
                "saksansvarligBrukerIdent": "e6e6318e-fdcb-41cb-ae3a-1940f98ea153",
                "saksstatus": "B"
            },
            "links": {
                "refPrimaerKlasse": 681,
                "refArkivdel": 688
            }
        }
    ]
}

Query by CaseYear and CaseSequenceNumber

    // client is an instance of NoarkClient
    QueryResponse<Saksmappe> queryResults = client.query(Saksmappe.class, "saksaar = @caseYear && sakssekvensnummer = @caseSequenceNumber", 1)
            .addQueryParam("@caseYear", "2021")
            .addQueryParam("@caseSequenceNumber", "6")
            .execute();

    if (!queryResults.getResults().isEmpty()) {
        Optional<Saksmappe> first = queryResults.getResults().stream().findFirst();

        // ID of the first case file, assuming only one is returned
        String caseFileID = first.get().getId();
    }

Query Request by ExternalID

    // client is an instance of NoarkClient
    QueryResponse<Saksmappe> queryResults = client.query(Saksmappe.class, "refEksternId.eksterntSystem = @externalSystemID && refEksternId.eksternID = @externalID", 1)
            .addQueryParam("@externalSystemID", "Integrating System 1")
            .addQueryParam("@externalID", "ISID:0000004572")
            .execute();

    if (!queryResults.getResults().isEmpty()) {
        Optional<Saksmappe> first = queryResults.getResults().stream().findFirst();

        // ID of the first case file, assuming only one is returned
        String caseFileID = first.get().getId();
    }

Important detail to be retrieved from the response is the ID of the existing case file - $.results[0].id in this case equal to 981. Client SDKs faciliate the extraction of the ID from the response as shown in the examples.

Creating new RegistryEntry and linked Correspondence Party (6, 7, 8)

Creating a new registry entry is described in details in this example, here it is provided for completenes. Bear in mind that the retrieved CaseFile ID (Saksmappe) should be used to link the newly created RegistryEntry to it. This is done (in the case of the raw HTTP API) through the element $.actions[1].linkToId as can be seen below.

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": "Journalpost",
            "id": "journalpost-temp-id-1",
            "fields": {
                "tittel": "API Created Registry Entry",
                "beskrivelse": "Registry Entry Description",
                "journalposttype": "U"
            }
        },
        {
            "action": "link",
            "type": "Journalpost",
            "id": "journalpost-temp-id-1",
            "ref": "refMappe",
            "linkToId": "981"
        },
        {
            "action": "save",
            "type": "Korrespondansepart",
            "id": "korrespondansepart-temp-id-1",
            "fields": {
                "korrespondanseparttype": "EA",
                "korrespondansepartNavn": "Correspondence Party Name"
            }
        },
        {
            "action": "link",
            "type": "Korrespondansepart",
            "id": "korrespondansepart-temp-id-1",
            "ref": "refRegistrering",
            "linkToId": "journalpost-temp-id-1"
        }
    ]
}

Response

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

{
    "saved": {
        "journalpost-temp-id-1": {
            "type": "Journalpost",
            "id": "994",
            "version": "8",
            "fields": {
                "uuid": "cf7eb80b-5c58-4418-b3e5-fb09c978e794",
                "opprettetDato": "2021-11-25T14:18:55.674+0100",
                "opprettetAv": "External Integrator ACME",
                "opprettetAvBrukerIdent": "e6e6318e-fdcb-41cb-ae3a-1940f98ea153",
                "registreringsIdent": "2021/9",
                "tittel": "API Created Registry Entry",
                "beskrivelse": "Registry Entry Description",
                "registreringsDato": "2021-11-25T14:18:55.714+0100",
                "dokumentmedium": "E",
                "journalaar": 2021,
                "journalsekvensnummer": 9,
                "journalpostnummer": 1,
                "journalansvarlig": "External Integrator ACME",
                "journalansvarligBrukerIdent": "e6e6318e-fdcb-41cb-ae3a-1940f98ea153",
                "journalposttype": "U",
                "journalstatus": "J",
                "skjermKorrespondanseParterEInnsyn": false
            },
            "links": {
                "refMappe": 981
            }
        },
        "korrespondansepart-temp-id-1": {
            "type": "Korrespondansepart",
            "id": "995",
            "version": "3",
            "fields": {
                "uuid": "ff3ec7de-6451-4347-88e2-0b81de6f1b75",
                "opprettetDato": "2021-11-25T14:18:55.718+0100",
                "opprettetAv": "External Integrator ACME",
                "opprettetAvBrukerIdent": "e6e6318e-fdcb-41cb-ae3a-1940f98ea153",
                "korrespondanseparttype": "EA",
                "korrespondansepartNavn": "Correspondence Party Name"
            },
            "links": {
                "refRegistrering": 994
            }
        }
    }
}

Upload an electronic document (9, 10, 11)

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.

Creating a Document and DocumentVersion and link them to RegistryEntry (12, 13)

As a final set of steps to be executed as part of this use case, a Document (Dokument) and DocumentVersion (Dokumentversjion) should be created. The electronic document ID, created in the previous step is now 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
            }
        }
    }
}