Query

Description

POST /noark5/v1/query

The POST /noark5/v1/query or as referred to in the documentation as query, is the operation for retrieving entitiy details from the Documaster Archive model. The operation allows querying for a single type of entity (or entities from a common type). Flexible query language allows retrieval of entities by complex relations traversal throught the archive structure.

Request

HTTP Request Mapping

Example of a simple query using parameters can be found in the Getting Starter/First API Interaction section. Sample queries for every core entity type can be found in the Examples section. A more complex query utilizing parameters, joins and sorting follows. The sample query below queries for any type of Folders, through basic type AbstraktMappe type, that has 2 distinct secondary classes, referenced through refSekundaerKlasse field. One of the classes is with id 1111, while the other one has an class identity APIC2. The results are sorder by the folder identity element mappeIdent. Note that some of the response entities fields in the response are omitted from the sample for clarity.

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": "AbstraktMappe",
  "limit": 10,
  "query": "#secClass1.id = @class1Id && #secClass2.klasseIdent = @class2Ident",
  "parameters" : {
    "@class1Id" : "1111",
    "@class2Ident" : "APIC2"
  },
  "joins": {
    "#secClass1" : "refSekundaerKlasse",
    "#secClass2" : "refSekundaerKlasse"
  },
  "sortOrder" : [
    {
      "field" : "mappeIdent",
      "order" : "desc"
    }
  ]
}

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

HTTP/1.1 200 OK
Connection: close
Date: Mon, 06 Dec 2021 09:57:13 GMT
Content-Type: application/json

{
  "hasMore": false,
  "results": [
    {
      "type": "Saksmappe",
      "id": "1122",
      "version": "10",
      "fields": {
        "opprettetAv": "External Integrator ACME",
        "mappeIdent": "2021/7",
        "tittel": "API Created Case File - 2",
        "beskrivelse": "Second API created Case File",
        "dokumentmedium": "E",
        "saksaar": 2021,
        "sakssekvensnummer": 7,
        "administrativEnhet": "AD1",
        "saksansvarlig": "External Integrator ACME",
        "saksstatus": "B"
      },
      "links": {
        "refPrimaerKlasse": 681,
        "refArkivdel": 688
      }
    },
    {
      "type": "Saksmappe",
      "id": "981",
      "version": "14",
      "fields": {
        "opprettetAv": "External Integrator ACME",
        "mappeIdent": "2021/6",
        "tittel": "API Created Case File",
        "beskrivelse": "First API created Case File",
        "dokumentmedium": "E",
        "saksaar": 2021,
        "sakssekvensnummer": 6,
        "administrativEnhet": "AD1",
        "saksansvarlig": "External Integrator ACME",
        "saksstatus": "B"
      },
      "links": {
        "refPrimaerKlasse": 681,
        "refArkivdel": 688
      }
    }
  ]
}

QueryResponse<AbstraktMappe> qrMappe = client.query(
                  AbstraktMappe.class,
                  "#secClass1.id = @class1Id && #secClass2.klasseIdent = @class2Ident", 100)
        .addQueryParam("@class1Id", "1111")
        .addQueryParam("@class2Ident", "APIC2")
        .addJoin("#secClass1", "refSekundaerKlasse")
        .addJoin("#secClass2", "refSekundaerKlasse")
        .addSortOrder("mappeIdent", Order.DESCENDING)
        .execute();

if (!qrMappe.getResults().isEmpty()) {
    AbstraktMappe folder = qrMappe.getResults().iterator().next();
    if (folder instanceof Saksmappe) {
        Saksmappe caseFile = (Saksmappe)folder;
        System.out.println(caseFile.getTittel());
    }
}

QueryResponse<AbstraktMappe> qrMappe = client.Query<AbstraktMappe>(
      "#secClass1.id = @class1Id && #secClass2.klasseIdent = @class2Ident", 100)
            .AddQueryParam("@class1Id", "1111")
            .AddQueryParam("@class2Ident", "APIC2")
            .AddJoin("#secClass1", "refSekundaerKlasse")
            .AddJoin("#secClass2", "refSekundaerKlasse")
            .AddSortOrder("mappeIdent", Order.Descending)
            .Execute();

if (qrMappe.Results.Count() > 0)
{
    AbstraktMappe folder = qrMappe.Results.First();
    if (folder is Saksmappe)
    {
        Saksmappe caseFile = (Saksmappe)folder;
        Console.WriteLine(caseFile.Tittel);
    }
}

Response

Response of the operation is an array($.results), with the entity objects matching the specified $.query in the request. The matched entity objects are returned with their complete representation and no filtering on the entity fields is supported currently. Successful execution of the query would result in an HTTP 200 OK response as shown in the example above.

HTTP Response Fields

As part of the resposne, business specific metadata is also returned for those entities that has it under $.results[].fields.virksomhetsspesifikkeMetadata. The table below provides the details about BSM values returned. The full path of the elemetns for BSM is shortened for clarity.

Query Language

query operation utilizes a flexible languge for filtering returned entities based on either queried entities fields or field of linked entities. The linked entity objects can be directly referenced by the queried objects or through another reference field. Query string is an optional one in the request payload in $.query element, but it rarely makes sense to use the operation without a query set.

Queries are comprised of expressions. The expressions can be simple, like equal (=), not equal (!=) or like (%=). The expressions can be range like between inclusive ([@param1:@param2]), between exclusive ({@param1:@param2}) and combinations of both (defined by the type of bracket used). Expressions can be grouped ((, )) and also logical oparators can be used between them, like logical and (&&) and logical or (||). Details of the expressions and their usage is provided below.

Literal values are not part of the $.query string, they are assigned a parameter in $.parameters object and the parameter is used in the queries. Each paraemeter name is prefixed with @ (at symbol). The parameters are referenced with the “@” prefix in both the $.parameters object and in $.query string.

Simple Expressions

Examples

Range Expressions

Range expressions allow filtering based on a range of values. Using [ or ] brackets indicates that the limit value is also included in the result set, while { and } indicate the limit values should be excluded. Both type of brackets can be combined in a single query.

Examples

Logical Operators and Grouping

The query language provides two logical operators that can be used between expressions: logical and - && and logical or - ||. Examples of their usage is already present in the examples above. Additionally in order to change evaluation order, the query language suppors grouping of the expressions using ( and ).

Reference Chaining

As shown in the examples below, reference fields (prefixed with ref) can be used to access linked entity objects and use their fields to filter returned entity objects set. Using the dot notation (.) to access reference entity object fields is a simple way to access referenced objects up or down the archive structure. Reference chaining denotes a single path to a linked entity object, which means that if single reference is used more than once in the same query to filter for two distinct referenced objects, the query will not return the expected results.

To give a better idea what is meant by single path imagine the case where there is a single RegistryEntry (Journalpost) having two external IDs (EksternID) associated with it. First External ID (EksternID) has a external system name (eksterntSystem) set to “IS1” and the second one has the same external system name set to “IS2”. Executing a query like this :

{
  "type": "Journalpost",
  "limit": 100,
  "query": "refEksternId.eksterntSystem = @externalSystemID1 && refEksternId.eksterntSystem = @externalSystemID2",
  "parameters" : {
    "@externalSystemID1": "IS1",
    "@externalSystemID2": "IS2"
  }
}

returns an empty set, although there is a Registry Entry (Journalpost) having both external IDs associated with it. The reason is the single path that the reference defines, it is referencing either one of the two external IDs (EksternId), but not both. Having the logical and && operator used causes the response to be empty. Changing the logical operator to || will also not work, because in this case the query would return registry entries that have either one of the two externalIDs (with external system set to the required values), while we want to retrieve those tha have both external IDs. Same is valid for any reference field that can reference multiple related entities, like secondary classes reference from a case file or registry entry.

Reference fields can be chained thus allowing executing queries throughout the entities levels as in the example below, thus allowing deep level of references chaining. The sample below queries for the Record (‘AbstractRegistrering’) which is linked to the Document (Dokument) which is linked to the Document Version (‘Dokumentversjon’) with ID = 56434.

{
    "type": "AbstraktRegistrering",
    "query": "refDokument.refDokumentversjon.id = @documentVersionID",
    "limit": 1,
    "parameters": {
        "@documentVersionID": "56434"    
    }
}

Query Joins

Joins are a way of defining aliases to reference fields, which practically allows using the aliases as separate paths through the archive structure. Joins are defined in the $.joins element of the query request, where each element in the $.joins object is an alias to a reference field. Aliases are prefixed with # (hash symbol). Taking the query above and making it work with joins is done like this:

{
  "type": "Journalpost",
  "limit": 100,
  "query": "#refExternId1.eksterntSystem = @externalSystemID1 && #refExternId2.eksterntSystem = @externalSystemID2",
  "joins": {
      "#refExternId1" : "refEksternId",
      "#refExternId2" : "refEksternId"
  },
  "parameters" : {
    "@externalSystemID1": "IS1",
    "@externalSystemID2": "IS2"
  }
}

As seen in the sample above, there are two join aliases #refExternID1 and #refExternID2 which refer to the same refEksternId field of the Registry Entry (Journalpost). This time though, both aliases define two separate paths in the structure and havin the query using those aliases, rather than directly the reference field gives the expected results, retrieving only the Registry Entries (Journalpost) having both externalIDs from systems with names IS1 and IS2.