Learn how to send search requests to yuuvis® Momentum via Web-API Gateway.

Introduction

This article describes how to use the search endpoint POST /api-web/api/dms/objects/search of the Web-API Gateway that supports the rapid development of custom clients and is used, e.g., by yuuvis® Momentum client as reference implementation. The search functionality is based on the search offered by the core system and simplifies specific calls for use in web client technologies.
>> Search Query Language

Parameters in Search Requests

The search endpoint POST /api-web/api/dms/objects/search of the Web-API Gateway accepts a JSON request body with specific parameters in a specific structure. The following optional parameters can be specified.

Offset and Size of Result List

The optional parameter from sets the offset for the result list, default is 0. The optional parameter size allows you to configure the maximum amount of hits to be returned, default is 20.
If the parameters should be included in the request, they have to be specified at the beginning of the JSON structure.

"from": <integer>,
"size": <integer>

Full-text Search Term

The parameter term is used to request a full-text search.

"term": "<query string>"

If the specified query string consists of multiple words, it is parsed into a series of individual words connected by operators. Per default, individual words are connected by AND. For example, the query string capital of Hungary is translated to the following request to the core system:

SELECT * FROM type where CONTAINS('capital AND of AND Hungary')

Note: The Web-API Gateway uses the placeholders ? (for a single character) and * (for any string) instead of the usual SQL placeholders.

For each object in the result list, the score is provided as object property. The results are sorted by their score values unless otherwise specified via sort parameter.

Sorting

The parameter sort arranges the result list in ascending (asc) or descending (desc) sort order of the specified field. It must be inserted in the upper part of the request body.

"sort":{                             
       "field" : "<field>",
       "order" : "<sort order>"
      }

Default sorting:

If a term parameter is specified (full-text search), the results are ordered by score.
If no term parameter is specified, the results are ordered by the system:creationDate property.

Properties in the Result List

The parameter fields defines the objects' properties to be displayed in the result list.

"fields":
 [
     "<field1>",
     "<field2>",
     ...
]

Object Types in the Result List

The parameter types includes an array with one or more object type IDs (combined by OR). Only objects of those types will be included in the result list.

 "types": 
  [                             
    "<object type>"
  ]

Conditions on Metadata

The parameter filters contains conditions for filtering the result list based on the objects' metadata. The structure is shown below.

The subparameter lo is used to combine several logical conditions (default value: AND). If there is only one logical condition or the conditions are combined by AND, the subparameter lo can be omitted.

Each entry in the filters subparameter list configures a condition by means of the following subparameters:

Via the subparameter f, the ID of a property can be specified. The value of this property should match the condition.
The subparameter o describes the relationship between the subparameter f and the value to compare v. The list of allowed comparison operators is given below.
The subparameter v contains the values to compare. The following types of comparing values are possible:
Type Example
string "Meier"
numeric 50
date/datetime "2016-01-01T00:00:00.000Z"
logical "true"
"false"
Regardless of the type, it is possible to use a null value to indicate that the corresponding property does not have any value.
The subparameter useNot reverses the meaning of the preceding logical comparison. While, e.g.,
```
"f": "system:versionNumber", 
"eq": 1, 
"v": 1
```
returns all objects with version number 1, the additional subparameter
```
"notUse": "true"
```
ensures that all objects are returned that do NOT have this version number.

Available Comparison Operators

Operator name	Description	Example
`eq`	Returns objects with values that are equal to `v1`.	`"f": "appPersonalfile:name",` `"o":` `"eq","v1":` `"idpic"`
`in`	Returns objects that match at least one of the provided values (value has to be an array), i.e., list of terms combined by OR. An array of values to compare must be specified.	`"f":` `"appPersonalfile:employee",` `"o":` `"in",` `"v1":`[`"Applicant",` `"Manager"` ]
`gt`	Returns objects with values greater than `v1`.	`"f":` `"system:creationDate",` `"o":` `"gt",` `"v1":` `"2016-01-01T00:00:00.000Z"`
`gte`	Returns objects with values greater than or equal to `v1`.	similar to `gt`
`lt`	Returns objects with values less than `v1`.	similar to `gt`
`lte`	Returns objects with values less than or equal to `v1`.	similar to `gt`
`gtlt`	Returns objects with values within the specified interval: greater than `v1` and less than `v2`.	`"f":` `"system:creationDate",` `"o":` `"gtelte",` `"v1":` `"2016-01-01T00:00:00.000Z",` `"v2":` `"2016-01-10T00:00:00.000Z`
`gtelte`	Returns objects with values within the specified interval: greater than or equal to `v1` and less than or equal to `v2`.	similar to `gtlt`
`gtlte`	Returns objects with values within the specified interval: greater than `v1` and less than or equal to `v2`.	similar to `gtlt`
`gtelt`	Returns objects with values within the specified interval: greater than or equal to `v1` and less than `v2`.	similar to `gtlt`
`like`	Used to search for a specific pattern with wildcards. The `?` character represents a single character, the `` character represents multiple characters. A maximum number of 10 `` and `?` characters are allowed in one `like` expression.	`"f": "system:tenant",` `"v1": "??Tenant",` `"o": "like"`
`contains`	As of 2023 Autumn. Performs full-text search for the specified field.	{ "f": "appClient:clientdescription", "v1": "test", "o": "contains" }

Filters Structure

"filters": 
 [  {
    "lo": "<logical operator>",
    "filters": 
	[
       {
       "f": "<field1>",
       "v1": <comparing value1>,
       "o": "<comparison operator1>",
       "useNot": <"true" or "false">
       },
       {
       "f": "<field2>",
       "v2": <comparing value2>,
       "o": "<comparison operator2>"
       }
       ...
    ]
    }
 ]

Multiple Conditions on Table Rows

As of 2022 Winter, the tableFilters section can be specified. Its structure is similar to the filters section as shown in the following example code. Specify the ID of the table property to which you want to apply conditions as value for table. In the columnFilters list, specify the individual conditions that are connected with a logical AND. Thus, they have to be matched in the SAME TABLE ROW.

Example query with two conditions on one table row.

{   
     "size": 50,
     "lots": ["appMyapp:invoice"],
     "fields": [
         "appClient:clienttitle",
         "system:objectId",
         "appMyapp:accountassignment"
     ],
     "tableFilters": [
         {
             "table": "appMyapp:accountassignment",
             "columnFilters": [
                 {
                     "f": "account",
                     "o": "eq",
                     "v1": "123456"
                 } ,
                 {
                     "f": "grossamount",
                     "o": "gt",
                     "v1": "1000"
                 }
             ]
         }
     ]
}

Aggregation

The aggs parameter can be used to specify a list of one or more property IDs (combined by OR) for which an aggregation is to be calculated.

 "aggs": 
  [
    "<field>"
  ]

Secondary Object Type(s)

A list of secondary object types combined by OR can be specified using the sots parameter. At least one of these secondary object types must be assigned to the DMS objects to be included in the result list.

"sots":
 ["<object type1>", "<object type2>", ...
 ]

Leading Object Type(s)

A list of leading object types combined by OR can be specified using the lots parameter. Exactly one of these leading object types must be assigned to the DMS objects to be included in the result list.

"lots":
 ["<object type1>", "<object type2>", ...
 ]

Example Request and Response

The following code blocks show an example request body using all parameters described above and a corresponding example response body.

Request Body

curl -X 'POST' \
  'https://kolibri.enaioci.net/api-web/api/dms/objects/search' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
"from": 4,
"size": 10,
"term": "Martin",
"sort":  [ 
    {
    "field" : "system:versionNumber",
    "order" : "desc"
    }
         ],
"fields":
 [
     "system:createdBy",
     "system:creationDate",
     "system:objectTypeId",
     "system:versionNumber"  
 ]
},
"types": [                             
    "appPersonalfile:dossier"
  ],
"filters": 
   [  {
    "lo": "OR",
    "filters": 
	[
       {
       "f": "system:versionNumber",
       "v1": 1,
       "o": "eq",
       "useNot": true      
       },
       {
       "f": "system:tenant",
       "v1": "kolibri",
       "o": "eq"
       }
    ]
    },
    { "f": "system:creationDate",         
      "o": "gtelte",
      "v1": "2010-01-01T00:00:00.000Z",
      "v2": "2021-01-10T00:00:00.000Z"
    },
    { "f": "system:lastModifiedBy",
      "v1": "?685*",
      "o": "like"
    }
 ]
},
"aggs":  [
    "appClientsystem:leadingTypeId"
  ]
,
"sots":  [   
    "appClient:clientdefaults"
  ],
"lots":  [ 
    "appClientsystem:leadingTypeId"
  ]
}'

Response Body

Each search request for DMS objects always returns a list of DMS objects called objects. If only one object matches the search query, the result is a single-element list. If no object matches the query, the response body contains an empty objects list.

{
  "objects": [
    {
      "properties": {
        "system:createdBy": {
          "title": "Schubert, Martin",
          "value": "2612df3a-1cf8-4da3-968c-0a4a10b48921"        },
        "system:creationDate": {
          "value": "2020-11-16T10:23:56.740Z"
        },
        "system:objectTypeId": {
          "value": "tenKolibri:qadoctableofnotices"
        },
        "system:versionNumber": {
          "value": 14
        }
      }
    },
    {
      "properties": {
        "system:createdBy": {
          "title": "Schubert, Martin",
          "value": "2612df3a-1cf8-4da3-968c-0a4a10b48921"        },
        "system:creationDate": {
          "value": "2020-09-02T13:03:25.680Z"
        },
        "system:objectTypeId": {
          "value": "appPersonalfile:pfdocumentdlm"
        },
        "system:versionNumber": {
          "value": 10
        }
      }
    },
    {
      "properties": {
        "system:createdBy": {
          "title": "Wayne, Bruce",
          "value": "e823c59a-e073-40e1-af0a-e95e08a8e36c"
        },
        "system:creationDate": {
          "value": "2020-10-22T10:49:24.290Z"
        },
        "system:objectTypeId": {
          "value": "appEmail:email"
        },
        "system:versionNumber": {
          "value": 9
        }
      }
    },
    {
      "properties": {
        "system:createdBy": {
          "title": "Lauterbach, Ralf",
          "value": "0b09ef34-2954-451c-9ebc-a898020bd004"
        },
        "system:creationDate": {
          "value": "2020-07-22T11:08:03.870Z"
        },
        "system:objectTypeId": {
          "value": "appClient:minidoc"
        },
        "system:versionNumber": {
          "value": 8
        }
      }
    },
    {
      "properties": {
        "system:createdBy": {
          "title": "Miller, Brad",
          "value": "a2f7e1aa-ff42-4140-b9ec-5de4cc61f1a5"
        },
        "system:creationDate": {
          "value": "2020-12-17T08:30:26.380Z"
        },
        "system:objectTypeId": {
          "value": "tenKolibri:qadoctableofnotices"
        },
        "system:versionNumber": {
          "value": 8
        }
      }
    },
    {
      "properties": {
        "system:createdBy": {
          "title": "Schubert, Martin",
          "value": "2612df3a-1cf8-4da3-968c-0a4a10b48921"
        },
        "system:creationDate": {
          "value": "2020-02-13T18:48:03.860Z"
        },
        "system:objectTypeId": {
          "value": "appPhotoarchive:paphoto"
        },
        "system:versionNumber": {
          "value": 8
        }
      }
    },
  ],
  "numItems": 5,
  "hasMoreItems": true,
  "totalNumItems": 160
}

Summary

The creation of search queries in JSON format via the Web-API enables the output of objects using various parameters without directly accessing the core.

Read on

Web-API Gateway Endpoints

The higher-level API of the Web-API Gateway on top of the core, as it is useful for client application developers. Keep reading

POST /api-web/api/dms/objects

Creates a DMS object with the data passed in the multipart request body including the metadata in JSON structure and optionally a binary content file. Keep reading

yuuvis® Momentum

Search via Web-API Gateway

Table of Contents