First API Interaction

Execute First Query

At this point, the integration developer should have the following details:

  • client_id and client_secret, username and password, provided as part of the onboarding process
  • Integration environment API HTTP endpoint
  • Fonds ID (Arkiv) and Series ID (Arkivdel)

Get Fonds Details

Query any core Noark5 entity object in Documaster is done through the Query (POST /noark5/v1/query) operation. The operation allows selecting a single type of objects (or a set of different object, having the same base type).

Retrieving the Fonds (Arkiv) details would require the following call to be made, where as input the already created Fonds ID (in this case 1088) is provided as a query parameter. Additionally an access token should have already beein aquired as part of the Authentication and Authorization process.

HTTP parameters mapping
Field Location Value Description
Authorization Bearer {{accessToken}} access token aquired as part of the authentication call, prefixed with Bearer
Content-Type value of application/json
X-Documaster-Error-Response-Type value of application/json custom header indicating that any error should be reported in JSON format, rather than the standard text format
$.type value of Arkiv the element defines the type of the entity the query is executed for, in this case it is Arkiv
$.limit value of 1 maximum number of records the query should return
$.query value of id = @fonds query written in the Documaster Noark5 API language, where @fondsID is a parameter supplied in $.parameters object
$.parameters.@fondsID the parameter @fonds value to be used, in this case 1088, alredy existing Fonds ID defines the parameter value for @fondsID parameter of the query

      Request

POST https://v2-34-0.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": "Arkiv",
  "limit": 1,
  "query": "id = @fondsID",
  "parameters" : {
    "@fondsID" : "1088"
  }
}

      Response

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

{
    "hasMore": false,
    "results": [
        {
            "type": "Arkiv",
            "id": "1088",
            "version": "4",
            "fields": {
                "uuid": "82281a12-3453-43d9-bca6-4ae0910bf5ec",
                "opprettetDato": "2021-11-29T12:54:32.303+0100",
                "opprettetAv": "External Integrator ACME",
                "opprettetAvBrukerIdent": "e6e6318e-fdcb-41cb-ae3a-1940f98ea153",
                "tittel": "Integration Fonds",
                "beskrivelse": "API Created Fonds",
                "arkivstatus": "O",
                "dokumentmedium": "E"
            },
            "links": {}
        }
    ]
}

QueryResponse<Arkiv> queryResults = client.query(Arkiv.class, "id = @fondsID", 1)
        .addQueryParam("@fondsID", "1088")
        .execute();

if (!queryResults.getResults().isEmpty()) {
    Arkiv fondsDetails = queryResults.getResults().iterator().next();
    System.out.println(fondsDetails.getTittel());
}

QueryResponse<Arkiv> queryResults = client.Query<Arkiv>("id = @fondsID", 1)
        .AddQueryParam("@fondsID", "1088")
        .Execute();

if (queryResults.Results.Count() > 0) {
    Arkiv fondsDetails = queryResults.Results.First();
    Console.WriteLine(fondsDetails.Tittel);
}

The result of the query above returns the details of the Fonds (Arkiv) entity object that is already present. All the elements under $.results[].fields are the specific fields for the Fonds with their respective values. Details about the meaning of those fields can be found in Data Model/Core Entities/Fonds.

Get Fonds Creator

Now that the Fonds (Arkiv) details are retrieved, it would be important to see how relations between entity objects can be used for queries. As depicted on the diagram in Model and Operations Overview, each Fonds (Arkiv) should have a least one Fonds Creator (Arkivskaper), so the already existing Fonds with ID : 1088 should have a creator.

Querying for an object based on the objects it is linked to is done through the reference fields (fields prefixed with ref). Example queries how this is achived through the API follow.

HTTP parameters mapping

Only modified elements in the current request are shown, other headers/body elements remain the same

Field Location Value Description
$.type value of Arkivskaper the element defines the type of the entity the query is executed for, in this case it is Arkivskaper (Fonds Creator)
$.query value of refArkiv.id = @fondsID query written in the Documaster Noark5 API language, where @fondsID is a parameter supplied in $.parameters object, containing the FondsID. The change with the previous query is that now the query uses refArkiv, refernece to the link between the Fonds (Arkiv) and the Fonds Creator (Arkivskaper), name as defined for the Fonds Creator (Arkivskaper) entity. refArkiv.id referes to the Fonds ID that is linked to the creator.

      Request

POST https://v2-34-0.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": "Arkivskaper",
  "limit": 5,
  "query": "refArkiv.id = @fondsID",
  "parameters" : {
    "@fondsID" : "1088"
  }
}

      Response

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

{
    "hasMore": false,
    "results": [
        {
            "type": "Arkivskaper",
            "id": "1089",
            "version": "2",
            "fields": {
                "uuid": "93d0938f-e4bd-4fb2-9e31-2f41fe48ac9d",
                "opprettetDato": "2021-11-29T12:54:32.307+0100",
                "opprettetAv": "External Integrator ACME",
                "opprettetAvBrukerIdent": "e6e6318e-fdcb-41cb-ae3a-1940f98ea153",
                "arkivskaperIdent": "EXI",
                "arkivskaperNavn": "External Integrator"
            },
            "links": {
                "refArkiv": 1088
            }
        }
    ]
}

QueryResponse<Arkivskaper> qrArkivSkapper = client.query(Arkivskaper.class, "refArkiv.id = @fondsID", 1)
        .addQueryParam("@fondsID", "1088")
        .execute();

if (!qrArkivSkapper.getResults().isEmpty()) {
    Arkivskaper fondsCreatorDetails = qrArkivSkapper.getResults().iterator().next();
    System.out.println(fondsCreatorDetails.getArkivskaperNavn());
}

QueryResponse<Arkivskaper> qrArivskaper = client.Query<Arkivskaper>("refArkiv.id = @fondsID", 1)
        .AddQueryParam("@fondsID", "1088")
        .Execute();

if (qrArivskaper.Results.Count() > 0) {
    Arkivskaper fondsCreatorDetails = qrArivskaper.Results.First();
    Console.WriteLine(fondsCreatorDetails.ArkivskaperNavn);
}

Get Fonds Series

Retrieving the Series (Arkivdel) linked to the Fonds (Arkiv) should be trivial, following the samples above. Entity type is Arkivdel and the relation from Series (Arkivdel) to Fonds (Arkiv) is again refArkiv. Details for this example are left out so it can be used as simple check point for basic query opertion usage knowledge.