Search Service API

This article is valid as of yuuvis® Momentum Version 2020 Autumn.

This article describes how to use the Web-API-based Search API that supports the rapid development of custom clients and is used by our reference implementation of the yuuvis® client. This API is based on the Search API of our core system (see this documentation: Search Query Language) and simplifies specific calls for use in web client technologies.

Table of Contents

Endpoint Method Overview for Search

PropertyValue
Full path
api-web/dms/search
HTTP method
POST
Success code
200: OK
Failure codes
401: Unauthorized
422: Unprocessable Entity
Types consumed
application/json
Types produced
application/json;charset=UTF-8

Request (HTTP body) 

For this request, the data is sent in JSON format.

The following shows all possibilities for searching including the specific explanations.

Note on the "term" below: When using the full-text search in the client, the documentation for the query string can be read here: Search Query Language.
The only difference is the wildcards. This API allows the use of ? and *. The ? is a placeholder for any random single character, the * is a placeholder for any random string.

{
  "term": "query string", 			       // optional: a query string is parsed into a series of terms and operators. A term can be a single word  or a phrase.
					 				       // The default operator is AND. For example, the query 'capital of Hungary' is translated to 'capital AND of AND Hungary' 
  "from": 0,         				       // optional: parameter sets the offset for the result list, default is 0
  "size": 20,         					   // optional: parameter allows you to configure the maximum amount of hits to be returned, default is 20
  "aggs": [appClientsystem:leadingTypeId], // optional: the fields for the aggregation should be calculated
  "filters":                               // optional: can be used to restrict the search in respect to special object attributes (baseparams), 
		"lo" : "OR",					   // optional: logical operator, default AND
		"filters" : [ {                    // optional: can be used to restrict the search in respect to special object attributes (baseparams), 
                                           // index data and/or object types. Different filter groups are combined with AND (default) or OR.
      "f": system:createdBy":              // object attribute" 
      "o": "eq",                           // operator: eq = "term" is "equal" to the field value
					                       // 		    in = "term" is containd "in" the field value
                                           //           gt = greater than "v1", lt = less than "v1", gte = greater than or equal to "v1", lte = less than or equal to "v1" 
                                           //           gtlt = greater than "v1" and less than "v2" , etc for gtlte,  gtelt, gtelte, 
      "v1": "smith"
    },
    { "f": "system:creationDate",          // object attribute
      "o": "gtelte",
      "v1": "2016-01-01T00:00:00.000Z",
      "v2": "2016-01-10T00:00:00.000Z"
    },
    "appPersonalfile:name": {              // custom field
      "o": "eq",
      "v1": "idpic"
    },
    "appPersonalfile:active": {
      "o": "eq",
      "v1": "true"                         // field of type 'boolean' can also be "false"
    },
    "appPersonalfile:employee": {
      "o": "in",
      "v1": [
        "Applicant",                       // list of terms combined with OR
        "Manager"
      ]
    },
    "appPersonalfile:age": {
      "o": "lte",
      "v1": 50                             // for numeric fields
    },
    "appPersonalfile:status": {
      "o": "eq",
      "v1": null                          // for any field, this query returns documents that have no value in the named field.
    },
    "appPersonalfile:activesince": {
      "o": "eq",
      "v1": "2016-01-01T00:00:00.000Z"    // for date and datetime fields
    }
  ],
  "types": [                              // optional: list of object types combined with OR
    "appPersonalfile:dossier"
  ],
  "sots": [                               // optional: list of seconary object types combined with OR
    "appClientsystem:leadingType", "appClient:clientdefaults"
  ],
  "fields": [         		              // optional: list of general object attributes and index data fields that should be returned in the result
                      				      // if this section is not specified, a default set of general attributes as configured is delivered
    "system:objectTypeId"    		      // default: technical name of the object type as configured 
    "appClient:clienttitle",              // default: individually defined for each object type
    "appClient:clientdescription",        // default: individually defined for each object type
    "system:creationDate",                // default: the date the object was created 
    "system:createdBy"                    // login name of the user who created the object  
  ],
   "sort": {    			              // optional: defines the sort order
	   "field" : "system:creationDate", 
       "order" : "asc"                    // control the result order; possible settings are 'asc' and 'desc'
      }
}

Result (response body)

Each search request for DMS objects always returns an array of DMS objects called objects, even if the result set is only a single object. I.e,. if a single object is requested, the result is a single-element array, given the object exists. Otherwise, the result is an empty array.