Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

This search-service API supports client developers to use the Elasticsearch capabilities in an easier waymore easily. It offers two specific main parts, : one to find objects by determining filters and one to get statistics via aggregations. Another part is to support data export with resolved object references and user names. 

...

Code Block
{
  "term": "optimal", // 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 result list, default is 0
  
 "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.
    "creator": {     // object attribute, similar is "modifier" 
      "o": "eq",     // operator: eq = "term" is "eq"ual field value of type string, number, or date
					 // 		  in = "term" is "in" field value 					 // of type catalog
         rg = predefined range, "v1" is one of these:    //           gt = greater than "v1", lt = lower //                "today", "yesterday", "thisweek", "lastweek", "thismonth", "lastmonth", "thisyear", "lastyear"than "v1", gte = greater than equal "v1", lte = lower than equal "v1" 
                     //           gtgtlt = greater than "v1", lt =and lower than "v1v2" , gteetc =for greatergtlte, than equal "v1"gtelt, gtelte, lte
  = lower than equal "v1": ["smith","#currentuser"],   // A list of strings with the login name of a user. The placeholder #currentuser# is resolved by the //login name of the requesting    user.
  gtlt = greater than "v1usenot": andtrue lower than "v2" , etc for gtlte,  gtelt, gtelte, 
      "v1": "smith" // optional attribute with default 'false' searches for objects not containing smith in the specified object property.
     },
    "mimetypegroup": {        // object attribute
      "o": "in",
      "v1": [
        "pdf",
        "word"
      ]
    },
    "modified": {             // object attribute
      "o": "rg",       "v1": "thismonth"       // },     "created": {    rg = predefined range, "v1" is one of these: //
object attribute
      "o": "gtelte",
      "v1": "2016-01-01T00:00:00.000Z",       "v2": "2016-01-10T00:00:00.000Z"     },     "personalfile.name": {   //  <technical name of object type>.<technical name of field>       "otoday":, "eqyesterday",
      "v1thisweek":, "idpiclastweek", "thismonth",    }"lastmonth", "thisyear", "lastyear"
   "basisdocument.active": {       "o": "eq",       "v1": "true"           // field of type 'boolean' can also be "false" or "null"     }, starting with version 10.10: "personalfile.employeetomorrow": {
      "o": "in",, "nextweek", "nextmonth", "nextyear", "thisquarter", "lastquarter", "nextquarter", and
      "v1": [               "Applicant",         // list of terms combined with OR. The wildcards  '*' and '?' can be used ina stringrange fields.which Forfollows catalogthe fields, the term must be an exact match of the catalog value.syntax "prefixnumberpostfix" with prefix = "last" and "next",
            "Manager"       ]     },     "personalfile.cv.position": {	// <technical name of objecttype>.<technical name of field>.<technical name of column>      and postfix = "odays":, "eqweeks", "months", "quarters", "years",
     "v1": "Developer"      // can also be "null" to find objects with no value for this attribute          //        };     "basisdocument.age": {  and 'number' as an integer "o": "lte",like '12', e.g 'last12days'
      "v1": 50"lastquarter"
    },
    "created": {     // for numeric fields     },// object attribute
  "basisdocument.status": {
      "o": "eqgtelte",
      "v1": null"2016-01-01T00:00:00.000Z",
      "v2": "2016-01-10T00:00:00.000Z"
    },
  // For any field, this query returns documents that have no value in the named field. "personalfile.name": {   // <technical name of object type>.<technical name of field>
      "o": "eq",
      "v1": "idpic"
    },
    "personalfilebasisdocument.activesinceactive": {
      "o": "eq",
      "v1": "2016-01-01T00:00:00.000Ztrue"  // for date and datetime fields     },
	"personalfile.path": {			// field of type 'boolean' can also be "ofalse": or "match",					// For string fields with classification 'Path', match all documents with paths that exist within a particular pathnull"
    },
    "personalfile.employee": {
        "v1o": "/Europe/Switzerland" 	// '/Europe/Switzerland', for example /Europe/Switzerland/Zürich, /Europe/Switzerland/Zürich (ZH), /Europe/Switzerland/Zürich/Winterthur
								   
in",
      "v1": [
   }   },   "typesApplicant":, [        // list of terms combined with OR. The wildcards // optional: list of object types combined with OR. In the case of index data search, only one object type is allowed
    "picture"
  ],
  "contextfoldertypes": [    // optional: list of context folders (technical names) combined with OR'*' and '?' can be used in string fields. For catalog fields, the term must be an exact match of the catalog value.
        "Manager"
      ]
    },
    "personalfile.cv.position": {	// <technical name of objecttype>.<technical name of field>.<technical name of //column>
find all objects that are saved in the general location with 'sysroot' "o": "eq",
     ],   "fieldsv1": ["Developer"      // can also // optional: list of general object attributes and index fields which should be returned in the result
    be "null" to find objects with no value for this attribute
    };
    "basisdocument.age": {
      "o": "lte",
      "v1": 50  // if this section is not specified, a default set of general attributes as configured// isfor deliverednumeric fields
   "type" },
    "basisdocument.status": {
      "o": "eq",
   // default: technical name of object type as configured in the designer"v1": null            "title",    // For any field, this query returns documents that have no value in //the default:named individuallyfield.
defined for each object type},
    "descriptionpersonalfile.activesince",: {
      "o": "eq",
 // default: individually defined for each object type
    "created", "v1": "2016-01-01T00:00:00.000Z"  // for date and datetime fields
    },
	"personalfile.path": {			// 
     // default"o": the date the object was created 
    "creator",      "match",					// For string fields with classification 'Path', match all documents with paths that exist within a particular path
      "v1": "/Europe/Switzerland" 	// login name of the user who created the object'/Europe/Switzerland', for example /Europe/Switzerland/Zürich, /Europe/Switzerland/Zürich (ZH), /Europe/Switzerland/Zürich/Winterthur
								   
  "creatorfullname",  }
  },
 // default"types": full[ name of user who created the object; format: <first name> <name>     "creatortitle", // optional: list of object types combined with  // titleOR. In the case of index userdata whosearch, modifiedonly theone object; format: <name>,<first name> (<login name>)type is allowed
    "modifiedpicture",
  ],
     "contextfoldertypes": [     // defaultoptional: list of thecontext datefolders the(technical objectnames) wascombined modifiedwith OR
    "modifierpersonalfile",              // loginfind nameall ofobjects thethat userare whosaved modifiedin the objectgeneral location with 'sysroot'
  ],
  "modifierfullnamefields": [         // defaultoptional: full namelist of usergeneral whoobject modifiedattributes theand object;index format:fields <firstwhich name>should <name>be returned in the result
"modifiertitle",         // title of user who modified the object; format: <name>,<first name> (<login name>) // if this section "finalized"is not specified, a default set of general attributes as configured is delivered
 // finalization state of"type" an object showing 'true' or 'false'     "mimetype",        // default: technical name of object // mime type of a file as givenconfigured in the operatingdesigner
system     "mimetypegrouptitle",         // same as 'filetype' of the document file which// groupdefault: mimeindividually types, e.g., all Microsoft Word mime types are grouped as 'word', and all imagedefined for each object type
as 'image'
    "filenamedescription",           // default: individually //defined offor theeach documentobject filetype
    "filetypecreated",               // of default: the date the object was documentcreated file
    "filesizecreator",               // login name of the document fileuser who created the object
    "creatorfullname"idpicture.width,        // anydefault: objectfull fieldname mustof beuser givenwho bycreated itsthe qualifiedobject; technicalformat: name<first in the format: <technical name of object type>_<technical name of field>name> <name>
    "creatortitle",        "myobject.mytable.mycolumn",  // the columntitle of auser tablewho ofmodified anthe object
	"contextfolderid",
	"personalfile.name"
  ],; format: <name>,<first name> (<login name>)
    "options": { modified",              // optionaldefault: definesthe somedate special search behaviorsthe object was modified 
    "tracktotalhits": falsemodifier",              // wiht default 'true'  login name of the user who modified the object
    "searchmodemodifierfullname":  "idxs",     // (default: "idxs")optional,  index data search; case insensitive with wildcards '*' and '?' allowedfull name of user who modified the object; format: <first name> <name>
    "modifiertitle",         // title of user who modified the object; format: <name>,<first name> (<login  name>)
   // "ftsfinalized" =  full-text search
	"resolvereference":true, // (default: false) resolves ID references of users and objects
	"resolveorgaddon" :false,// (default: true) resolves user ID, if false the login name will be returned
	"withcontext: true,		 // (default: false) returns additionally title, description and ID of the context folder  for every hit
	"expertmode": false,          // finalization state of an object showing 'true' or 'false'
    "mimetype",              // mime type of a file as given in the operating system
    "mimetypegroup",         // (default: false) if true, the "term" is interpreted in the syntax of the Elasticsearch engine
    "sort": {     same as 'filetype' of the document file which group mime types, e.g., all Microsoft Word mime types are grouped as 'word', and all image type as 'image'
    "filename",      // optional: defines the sort order   // of the document "created":file
{    "filetype",      "order": "asc",       // controlof the resultdocument order;file
possible settings are 'asc' and 'desc' "filesize",           "missing": "_first"   // controlof howthe todocument handle missingfile
field values: possible settings are "_lastcontextfolderid", and "_first" in the list  // id of the folder }an object is saved in
}
    "scope" : "all"idpicture.width,          // any "all"object asfield defaultmust searchesbe ingiven indexdataby andits content, "indexdata" onlyqualified technical name in indexdata,the and "content" only in contents (document files).
    }
  }
}

Result (response body)

For this request, the data is sent in JSON format, as seen in the following example.

Code Block
{
    "took": 31,                     // time the response needed (in milliseconds)format: <technical name of object type>.<technical name of field>
    "myobject.mytable.mycolumn",  // the column of a table of an object
	"personalfile.class_id"  // beginning with 10.16 LTS, it is possible let the id of a catalog property be returned instead of the usual value with.
    "timedpersonalfile.class_outdata":// false,beginning with 10.16 LTS, it is possible let the data value of a //catalog OK,property nobe timeoutreturned wasinstead reachedof the usual localized value
"hits": {
     ],
   "totaloptions": 5,{               //  // 5 hits are shown in the following hit list !! use this code in versions 6.0 or earlier
        "total": {					// 5 hits are shown in the following hit list !! use this code for versions 6.0 or later !! Breaking change, see comment below this code block !!
            "value": 5,				
            "relation": "eq"
        },optional: defines some special search behaviors
    "tracktotalhits": false  // wiht default 'true' 
    "searchmode": "idxs",    // (default: "idxs") optional, index data search; case insensitive with wildcards '*' and '?' allowed
                       "max_score": 2.1420739,     // for"fts" each hit, a score is given which can be used for sorting purposes
        "hits": [{
             "_index": "enaiored",= full-text search
	"resolvereference":true, // (default: false) resolves ID references of users and objects
	"resolveorgaddon" :false,// (default: true) resolves user ID, if false the login name will be returned
	"withcontext: true,		 // (default: false) returns additionally title, description and ID of the context folder for every hit
	"expertmode": false,     // name of search index database 
        (default: false) if true, the "term" is interpreted in the syntax of the Elasticsearch engine
    "_typesort": "dmsobject",{           // internal notation only  // optional: defines the sort order
      "_idcreated": "7A241428D3164044AB98533A70A382D4",{
         "order": "asc",     // control the result order; possible "_score": 2.1420739,  
settings are 'asc' and 'desc'
         "missing":   "_sourcefirst": {// control how to handle missing field values: possible settings are "_last" and "_first" in //the list
of result list parameters as requested }
    }
    "scope" : "all"       "idpicture.firstname": "Martin",  // "all" as default searches in indexdata and content, "indexdata" only in indexdata, and "content" only in  "created": "2016-01-21T02:47:40Z",contents (document files).
    }
  }
}

Result (response body)

For this request, the data is sent in JSON format, as seen in the following example.


Code Block
{
    "took": 31,          "modifiertitle": "Roth, Rudger",         // time the response needed (in milliseconds)
    "creatortitletimed_out": "Rothfalse, Rudger",            // OK, no timeout was reached
    "modifiedhits": "2017-02-16T06:39:40Z",{
                   "id"total": "7A241428D3164044AB98533A70A382D4"5,    // ID of the object, which must be used in the client URL to// show5 thehits objectare asshown described in the following sectionhit list !! use this code in versions 6.0 or          earlier
        "typetotal": "idpicture",                         
          {					// 5 hits are shown in the following hit list !! use this code for versions 6.0 or later !! Breaking change, see comment below this code block !!
            "value": 5,				
            "relation": "eq"
        },
        "idpicture.namemax_score": "Schriddel"2.1420739, 				   "idpicture.participant": "FEFA1C490EAE4EBDBBFC100C10627013",
				   "idpicture.participant_meta":{
        				"title": "Bartonitz, Martin",
 // for each hit, a score is given which can be used for sorting purposes
        				"idhits": "2FF19AE615174A4188E2BB3AB3881FF3", [{
            					 "type_index": "personalakteenaiored",    // name  				}of search index database 
            }, 			"context_type": { 								// context folder of this dms object 
				"title": "Akte", 						// title of the context folder
				"description": "Personalakte", 			// description of the context folder
				""dmsobject",      // internal notation only
             "_id": "F6483A09F580420D86950BB4722D02A27A241428D3164044AB98533A70A382D4"//, id of the context folder 			}, 			... 
       }]     }, 	"config_score": {								// a result list configuration by type and optional context type.			 2.1420739,  
             "type_source": "dokument",{     "elements": [         // list of result list parameters as requested
          // list of field parameters depending on the use of "idpicture.firstname": "typeMartin",
       {            "namecreated": "type2016-01-21T02:47:40Z",
        "qname": "sysobject.type",           "hitnamemodifiertitle": "typeRoth, Rudger",
         "label": "Type",         "descriptioncreatortitle": "Type of the object.Roth, Rudger",
         "type": "STRING",         "readonlymodified": true,"2017-02-16T06:39:40Z",
         "baseparameter": true,         "systemid": true"7A241428D3164044AB98533A70A382D4",    // ID of   "selectedforenrichment": falsethe object, which must be used in the client URL "required": true,
        "maxlen": 0,to show the object as described in the following section
          "minlen": 0,
        "scaletype": 0"idpicture",           "precision": 0,         "withtime": false   
   },       {         "idpicture.name": "mimetypegroupSchriddel",
     				   "qnameidpicture.participant": "sysdocument.mimetypegroupFEFA1C490EAE4EBDBBFC100C10627013",
   				     "hitname"idpicture.participant_meta":{
"mimetypegroup",         "label				"title": "FileBartonitz, groupMartin",
        				"descriptionid": "File group of the content.2FF19AE615174A4188E2BB3AB3881FF3",
       					 "type": "STRINGpersonalakte",
      				}
    "readonly": true,        },
			"baseparametercontext": true,
        "system": true,
        "selectedforenrichment": false,
        "required": true,
        "maxlen": 0,
        "minlen": 0,
   { 								// context folder of this dms object 
				"title": "Akte", 						// title of the context folder
				"description": "Personalakte", 			// description of the context folder
				"id": "F6483A09F580420D86950BB4722D02A2"// id of the context folder
			},
			...
        }]
    },
	"config": {								// a result list configuration by type and optional context type.			
    "scaletype": 0"dokument",
    "elements": [             "precision": 0,              // list "withtime": false
      },of field parameters depending on the use of "type"
      {
        "name": "titeltype",
        "qname": "dokumentsysobject.titeltype",
        "hitname": "dokument.titeltype",
        "label": "titelType",
        "description": "titelType of the object.",
        "type": "STRING",
        "readonly": falsetrue,
        "baseparameter": falsetrue,
        "system": falsetrue,
        "selectedforenrichment": false,
        "required": true,
        "maxlen": 500,
        "minlen": 50,
        "scale": 0,
        "precision": 0,
        "withtime": false
      },
      {
        "name": "bemerkungmimetypegroup",
        "qname": "dokumentsysdocument.bemerkungmimetypegroup",
        "hitname": "dokument.bemerkungmimetypegroup",
        "label": "bemerkungFile group",
        "description": "bemerkungFile group of the content.",
        "type": "STRING",
        "readonly": falsetrue,
        "baseparameter": falsetrue,
        "system": falsetrue,
        "selectedforenrichment": false,
        "required": falsetrue,
        "maxlen": 2000,
        "minlen": 0,
        "scale": 0,
        "precision": 0,
        "withtime": false
      },
, 	...     }

Search Response for hits

In the search response, hits.total is an object. The total count of hits that match the search request is now returned as an object with a value and a relation.

The value specifies the number of hits that match. The relation specifies whether the value is accurate (eq) or a lower bound (gte):

Code Block
languagejava
{
    "hits": {
        "total": {
            "value": 1000,
            "relation": "eq"
        },
        ...
    }
}

The total object count in the response specifies that the query matches exactly 1.000 documents ("eq"). The value is always accurate ("relation": "eq") when track_total_hits is set to true (default) in the request.

Example: Find all documents without a file

Beginning with version 9.4, the following example requests only objects that are no folders and that do not contain a document file.

Code Block
titleDocuments without a file
"filters": {
  "filesize": {
     "o": "rg{
        "name": "titel",
        "qname": "dokument.titel",
        "hitname": "dokument.titel",
        "label": "titel",
        // operator for range"description": "titel",
        "v1type": "noneSTRING",
        // none stands for no content (document file)
  },"readonly": false,
        "baseparameter": false,
        "foldersystem": { false,
        "selectedforenrichment": false,
       // this determines to exclude folders "required": true,
        "omaxlen": "eq"50,
        "minlen": 5,
        "v1scale": 0,
  false   } }  

Example: Searching a Term in Several Fields

The following example requests objects where the string "irina@qs.optimal-systems.de" is part of the fields "systo" OR "syscc" in the object type "sysemail". The example uses Elasticsearch engine syntax, so you must append ".fts" to the field specifier.

Code Block
{
	"term": "txt_sysemail_systo:irina@qs.optimal-systems.de OR txt_sysemail_syscc:irina@qs.optimal-systems.de",
	"options": 
	{
		"expertmode": true"precision": 0,
        "withtime": false
      },
     	}
}

Endpoint Method Overview for Aggregations

...

Full path

...

[Gateway-URL]/search/aggregate

...

HTTP method

...

POST

...

Success code

...

200: OK

...

Failure codes

...

404: Not Found
412: Precondition Failed
500: Internal Server Error

...

Types consumed

...

application/json

...

Types produced

...

application/json;charset=UTF-8

Endpoint Request Parameter

...

Authorization

...

optional parameter

...

RequestHeader 

...

Accept-Language

...

optional parameter; default is local of the server.

...

RequestHeader

Aggregations

The following examples show how to request aggregations and what the response looks like.

Example: Aggregation for Object Types

The following example requests aggregations over the objects that were modified today with a specified time zone regarding the requesting user:

Code Block
{
	"aggs": {  				// The aggregations object (the key aggs can also be used) in the JSON holds the aggregations to be computed
		"type": {			// Property name of an object for that the aggregation should be calculated, here the system property "type" that is used for the object types
			"size" : 30,				// This key is optional with the default 10. The terms aggregation returns the buckets for the set terms ordered. 
										// Set "size" for a different number of returned buckets
    {
        "name": "bemerkung",
        "qname": "dokument.bemerkung",
        "hitname": "dokument.bemerkung",
        "label": "bemerkung",
        "description": "bemerkung",
        "type": "STRING",
        "readonly": false,
        "baseparameter": false,
        "system": false,
        "selectedforenrichment": false,
        "required": false,
        "ordermaxlen" : "desc",     200,
     // This key is optional with the default "desc" for descanding order in respect with the key "sort". Set "asc" for ascanding."minlen": 0,
        "scale": 0,
            "sortprecision" : "_count",     0,
    // This key is optional with the default "_count" for"withtime": false
             "min_doc_count" : 1
		}} ,
	"filters": {...    
}

Search Response for hits

In the search response, hits.total is an object. The total count of hits that match the search request is now returned as an object with a value and a relation.

The value specifies the number of hits that match. The relation specifies whether the value is accurate (eq) or a lower bound (gte):


Code Block
languagejava
{
    "hits": {
        "total": {
 // The "filter" objects configures how to reduce the hits
		"modified            "value": 1000,
            "relation": "eq"
        },
        ...
    }
}

The total object count in the response specifies that the query matches exactly 1.000 documents ("eq"). The value is always accurate ("relation": "eq") when track_total_hits is set to true (default) in the request.

Example: Find all documents without a file

Beginning with version 9.4, the following example requests only objects that are no folders and do not contain a document file.

Code Block
titleDocuments without a file
"filters": {
  "filesize": {
   // The system property "modified" contains the date of the last modification of an object
				"oo": "rg",         // operator for range
     "v1": "rgnone",       // Thenone operatorstands "o"for isno setcontent to "rg" for a date range configuration
				"v1":"today"    // The filter value "v1" for the range is set to "today" to get only objects that were modified today.
		}
	},
	"options": 
	{
		"timezone": "+02:00"   // The timezone can be used if users are working in different timezones.
	}
}

...

(document file)
  },
  "folder": {           // this determines to exclude folders
     "o": "eq",
     "v1": false
  }
}

Example: Searching a Term in Several Fields

The following example requests objects where the string "irina@qs.optimal-systems.de" is part of the fields "systo" OR "syscc" in the object type "sysemail". The example uses Elasticsearch engine syntax, so you must append ".fts" to the field specifier.

Code Block
{
	"aggregationsterm": { 		"type": {
			"doc_count_error_upper_bound": 0,
			"sum_other_doc_count": 0,
			"buckets": [
				{
					"key": "personalfile","txt_sysemail_systo:irina@qs.optimal-systems.de OR txt_sysemail_syscc:irina@qs.optimal-systems.de",
	"options": 
	{
		"expertmode": true          // technical
name of the object type
					"doc_count": 2,    	}
}

Example: Searching with "usenot" in fields of type string, number, and date

Beginning with version 10.10, add the attribute "usenot" with true to the filter. Wildcards are supported.

Code Block
"filters": {
  "employee.firstname": {             // numberfield of foundtype string
objects of the object type "personalfileo"
				},
				{
					"key: "eq",         
     "v1": "qsfolderThomas",
					"doc_count": 1,
				}
			]
		}
	}
}

     "usenot" : true
  }
}

Example: Searching with "usenot" for catalog fields

Beginning with version 910.16 LTS10, the bucket keys for the system property "type" and for codesystems (catalogues) are localized in the language of the calling user.

Example: Use of Sub-Aggregations

This example shows how to configure the aggregation request for counting document objects sub-aggregated regarding the object type of the folder the document objects are saved to:

...

add the attribute "usenot" with true to the filter. Wildcards are supported.

Code Block
"filters": {
 							 		"typeemployee.class": {						
			"sub": {
				"contextfoldertype": {             				}
			}
		}// field of type catalog 
    }, 	"filterso": { 		"folderin": {,
          / this determines to exclude folders
			"o"v1": "eqfreelancer",
			"v1": false    "usenot" : true
  }
	}
}

The response looks like this:

Code Block
{
    ...
    "aggregations": {
        "type}

Endpoint Method Overview for Aggregations

PropertyValue
Full path
[Gateway-URL]/search/aggregate
HTTP method
POST
Success code
200: OK
Failure codes
404: Not Found
412: Precondition Failed
500: Internal Server Error
Types consumed
application/json
Types produced
application/json;charset=UTF-8

Endpoint Request Parameter

NameCommentType
Authorization
optional parameter
RequestHeader 
Accept-Language
optional parameter; default is local of the server.
RequestHeader

Aggregations

The following examples show how to request aggregations and what the response looks like.

Example: Aggregation for Object Types

The following example requests aggregations over the objects that were modified today with a specified time zone regarding the requesting user:

Code Block
{
	"aggs": {  				// The aggregations object (the key aggs can also be  "doc_count_error_upper_bound": 0,
            "sum_other_doc_count": 0,
            "buckets": [
                {
                    "key": "letterofconcent",used) in the JSON holds the aggregations to be computed
		"type": {			// Property name of an object for that the aggregation should be calculated, here the system property "type" that is used for the object types
			"size" : 30,				// This key is optional with the default 10. The terms aggregation returns the buckets for the set terms ordered. 
										// Set "size" for a different number of returned buckets
          // technical document"order" object type nam: "desc",           // This key is optional with the    default "doc_countdesc": 3,for descanding order in respect with the key "sort". Set "asc" for ascanding.
        // summed number of his"sort" for: "_count"letterofcontent,          // This key is optional with the default    "contextfoldertype_count": {
          for 
             "min_doc_count_error_upper_bound" : 1
0		},
	"filters": {              // The "filter" objects configures how to reduce the hits
"sum_other_doc_count		"modified": 0,{        // The system property "modified" contains the date of the last modification of an    "bucketsobject
				"o": ["rg",      // The operator "o" is set to "rg" for a date range      configuration
				"v1":"today"    // The {filter value "v1" for the range is set to "today" to get only objects that were modified today.
		}
	},
	"options": 
           "key	{
		"timezone": "personalfile", +02:00"   // technichalThe nametimezone ofcan folderbe objectused typeif nameusers are working in different timezones.
	}
}

The response to the above request will look like the following JSON example:

Code Block
{
	"aggregations": {
		"type": {
			"doc_count_error_upper_bound": 0,
			"sum_other_doc_count": 0,
			"buckets": [
               "doc_count": 2  				{
					"key": "personalfile",          // technical numbername of "letterofcontent"the foundobject intype
"personalfile"
					"doc_count": 2,                 // number of found objects of the object type   "personalfile"
				},
                            {
                                				{
					"key": "projectqsfolder",
                                					"doc_count": 1,
				}
			]
		}
	}
}

Beginning with version 9.16 LTS, the bucket keys for the system property "type" and for codesystems (catalogues) are localized in the language of the calling user.

Example: Use of Sub-Aggregations

This example shows how to configure the aggregation request for counting document objects sub-aggregated regarding the object type of the folder the document objects are saved to:

Code Block
{
	"aggs": {    // number of "letterofcontent" found in "project"
   							
		"type": {						
			"sub": {
				"contextfoldertype": {       
				}
			}
		}
    },
	"filters": {
		"folder": {      }     / this determines to exclude folders
			"o": "eq",
			"v1": false
        }
 ]	}
}

The response looks like this:

Code Block
{
    ...
    "aggregations": {
        "type": }{
            "doc_count_error_upper_bound": 0,
  }          "sum_other_doc_count": 0,
 ]         } 	} }

Example: Aggregate with ranges for Number Properties

The following example shows how to use the range "rg" parameter that defines a list of three ranges starting from "o1" to "o2".

Code Block
titleAggregation with ranges for numbers properties
{"buckets": [
     "aggs": {         "invoice.amountbeforetax": {
                    "rgkey": ["letterofconcent",           // technical document object type nam
{                     "o1doc_count": 0.03,                     "o2": 2000.0
    // summed number of his for "letterofcontent
           },             "contextfoldertype": {
   {                     "o1doc_count_error_upper_bound": 2001.0,
                        "o2sum_other_doc_count": 4000.00,
                      },  "buckets": [
             {               {
     "o1": 4001.0,                     "o2": 6000.0    "key": "personalfile",    // technichal name of folder object type name
}             ]         }     },     "typesdoc_count": ["invoice"]
}

The response looks like:

Code Block
titleResponse of an aggregation with range for a number property
{2      ...,     "aggregations": {
  // number of "letterofcontent" found in "personalfile"
      "invoice.amountbeforetax": {             "buckets": [       },
         {                   {
 "key": "0.0_2000.0",                     "from": 0.0,          "key": "project",
          "to": 2000.0,                     "doc_count": 21            // number of "letterofcontent" found },in "project"
               {             }
       "key": "2001.0_4000.0",                ]
    "from": 2001.0,               }
     "to": 4000.0,          }
            ]
"doc_count": 7       }
	}
}

Example: Aggregate with ranges for Number Properties

The following example shows how to use the range "rg" parameter that defines a list of three ranges starting from "o1" to "o2".

Code Block
titleAggregation with ranges for numbers properties
{
    "aggs": {
 },       "invoice.amountbeforetax": {
        {    "rg": [
               "key": "4001.0_6000.0", {
                    "fromo1": 40010.0,
                    "too2": 60002000.0,
                },
   "doc_count": 10            {
    }             ]         }"o1": 2001.0,
     }
}

Example: Aggregate with ranges for Date Properties

The following example shows how to use the range "rg" parameter that defines a list of three ranges starting from "o1" to "o2".

Code Block
titleAggregation with ranges for numbers properties
{     "aggs": {         "qdoc.effectivefromo2": { 4000.0
               "rg": [ },
                {
                    "o2o1": "2010-12-31"4001.0,
                 },   "o2": 6000.0
            {    }
            ]
   "o1     }
    },
    "types": ["2011-01-01",
invoice"]
}

The response looks like:

Code Block
titleResponse of an aggregation with range for a number property
{
    ...,
    "aggregations": {
        "o2invoice.amountbeforetax": "2016-12-31"{
                },"buckets": [
                {
                    "o1key": "2017-01-01"0.0_2000.0",
                }    "from": 0.0,
        ]         }   "to": 2000.0,
} } 

The response looks like:

Code Block
titleResponse of an aggregation with range for a date property
{     ...,     "aggregations": {
        "qdoc.effectivefromdoc_count": 2
{               "buckets": [ },
                {
                    "key": "to_2010-12-312001.0_4000.0",
                    "tofrom": 12001.2937536E120,
                    "to_as_string": "2010-12-31T00:00:00.000Z"4000.0,
                    "doc_count": 76697
                },
                {
                    "key": "2011-01-01_2016-12-314001.0_6000.0",
                    "from": 14001.29384E120,
                    "from_as_stringto": "2011-01-01T00:00:00.000Z"6000.0,
                    "todoc_count": 1.4831424E12, 10
                }
     "to_as_string": "2016-12-31T00:00:00.000Z",      ]
        }
    }
"doc_count": 11220}

Example: Aggregate with ranges for Date Properties

The following example shows how to use the range "rg" parameter that defines a list of three ranges starting from "o1" to "o2".

Code Block
titleAggregation with ranges for numbers properties
{
    "aggs": {
        "qdoc.effectivefrom": {
 },           "rg": [
                {
                    "keyo2": "from_20172010-0112-01",31"
                },
               "from": 1.4832288E12, {
                    "from_as_stringo1": "20172011-01-01T00:00:00.000Z01",
                    "doc_counto2": 65"2016-12-31"
                },
            ]    {
              }     }
}

Example: Use of Metrics for Number Properties

The following configuration shows how to use the aggregation attribute metrics for properties of type numbers like the amount of an invoice:

Code Block
{
	"aggs": {			
		"invoice.amount": { "o1": "2017-01-01"
                }
         // technical name of]
an object property 			"metrics" : "<metrics type>"	 // see legend below	}
    		}
	} }

The

...

response looks like:

...

Code Block

...

The response for a single metrics request is:

Code Block
titleResponse for a single metrics request
titleResponse of an aggregation with range for a date property
{
    ...,
    "aggregations": {
   ...     "aggregationsqdoc.effectivefrom": {
         "min#invoice.amount_min":   "buckets": [
                {
            "value": 123.0     } } 

Beginning with version 10.0 it is possible to request for more than one value in the metrics. They must be comma-separated like "min,max". The response looks a bit different regarding the key with an additional extension:

Code Block
titleResponse for a single metrics request
{
   ... "key": "to_2010-12-31",
          "aggregations": {         "min#invoice.amount_minto": {1.2937536E12,
            "value": 123.0,         "max#invoice.amount_max": {"to_as_string": "2010-12-31T00:00:00.000Z",
             "value       "doc_count": 7669
 155.0         }     } } 

Example: Use of sub-aggregation combined with metrics

Beginning with version 10.0, the following request shows how to get the sum for a number attribute like the turnover for customers instead of the document counts:

Code Block
titleRequest
{,
   "aggs" : {     "invoice.customer" : {    {
  "size" : 10,       "oder" : "asc",       "sortkey" : "invoice.turnover.value2011-01-01_2016-12-31",
      "sub": {              "from"invoice.turnover" : {: 1.29384E12,
                    "metricsfrom_as_string" : "sum"
2011-01-01T00:00:00.000Z",
       }       }     } "to": 1.4831424E12,
} }

The response looks like this:

Code Block
titleResponse
{     ...     "aggregations": {         "invoice.customer": {"to_as_string": "2016-12-31T00:00:00.000Z",
                    "doc_count_error_upper_bound": 0,11220
             "sum_other_doc_count": 0,  },
          "buckets": [
                {
                    "key": "Sunshine Inc.from_2017-01-01",
                    "doc_countfrom": 1.4832288E12,
                    "sum#invoice.turnover": {
   from_as_string": "2017-01-01T00:00:00.000Z",
                    "valuedoc_count": 43.2
65
                   }
            ]
   },     }
           {
                    "key": "BuyMe Org",
}
}


Example: Use of Metrics for Number Properties

The following configuration shows how to use the aggregation attribute metrics for properties of type numbers like the amount of an invoice:

Code Block
{
	"aggs": {			
		"invoice.amount": {                  //  "doc_count": 1,
                    "sum#einvoice.turnover": {
    technical name of an object property
			"metrics" : "<metrics type>"	 // see legend below	    
		}
      	}
}

The metrics types are:

metrics typeDescription
avgcomputes the average of numeric values that are extracted from the aggregated objects.
maxreturns the maximum value among the numeric values extracted from the aggregated objects.
minreturns the minimum value among numeric values.
sumsums up numeric values that are extracted from the aggregated objects
medianapproximates the median absolute deviation of its search results

The response for a single metrics request is:

Code Block
titleResponse for a single metrics request
{
   ...
    "valueaggregations": 235.62{
        "min#invoice.amount_min": {
          }  "value": 123.0
    }
} 

Beginning with version 10.0, it is possible to request for more than one value in the metrics. They must be comma-separated like "min,max". The response looks a bit different regarding the key with an additional extension:

Code Block
titleResponse for a single metrics request
{
   ...
    "aggregations": {
 },       "min#invoice.amount_min": {
        ...    "value": 123.0,
       ]
  "max#invoice.amount_max": {
      }     }
}

...

 "value": 155.0
        }
    }
} 

Example: Use of sub-aggregation combined with metrics

Beginning with version 10.0, the following request shows how to get the sum for a number attribute like the turnover for customers instead of the document counts:

Code Block
titleRequest
{
  "aggs" : {
    "invoice.customer" : {
      "size" : 10,
      "oder" : "asc",
      "sort" : "invoice.turnover_max.value",
      "sub": {
        "invoice.turnover" : {
          "metrics" : ["sum","min","max"]
        }
      }
    }
  }
}

The response looks like this:

Code Block
titleResponse
}{
    ...
    "aggregations": {
        "etlainvoiceinvoice.etlasuppliernocustomer": {
            "doc_count_error_upper_bound": 0,
            "sum_other_doc_count": 0,
            "buckets": [
                {
                    "key": "Sunshine Inc.",
                    "doc_count": 1,
                    "sum#invoice.turnover_sum": {
                        "value": 43.2
                    },
                },
   "max#invoice.turnover_max": {             {
           "value": 43.2        "key": "BuyMe Org",
                 }   "doc_count": 1,
                    "min#invoicesum#einvoice.turnover_min": {
                        "value": 43235.262
                    }
                },
                ...
            ]
        }
    }
}

Example: Use of Histograms for DateTime Properties

The following configuration shows how to use the aggregation attribute histogram for object properties of type datetime. Possible histograms can be used for days, weeks, month, and years.

...

And if you want to get more than one metric you can request such this with the sorting one specifically:

Code Block
titleRequest
{
  "aggs" : {
    "invoice.customer" : {
       // Beginning with version 9.16 LTS, the following histogram based aggregations for days, months, weeks, and years are supported:
			"histogram": {
				"calendar_interval" : "year",   // This single-value aggregation responds buckets per year
				"format" : "yyyy","size" : 10,
      "oder" : "asc",
      "sort" : "invoice.turnover_max.value",
      "sub": {
        "invoice.turnover" : {
          "metrics" : ["sum","min","max"]
        }
    // The syntax}
of the format is that of Elasticsearch. It is important that calendar_interval and format must fit together to optain meaningful results.
    }
  }
}

The response looks like this:

Code Block
titleResponse
}
    ...
    "aggregations": {
        "etlainvoice.etlasupplierno": {
            "sizedoc_count_error_upper_bound": 100,
            "sum_other_doc_count": 0,
        // Return maximal 10 "buckets
			}": [
                {
                   		}, 		"project.datefield2key": {
			"histogram": {"Sunshine Inc.",
                           
				"calendar_interval" : "month",  // This single-value aggregation responds buckets per month in the format year-month like 2023-01 for January of 2023
				"format" : "yyyy-MM"
			}
		},
		"document.datefield3": {
			"histogram": {
				"calendar_interval" : "week",  // This single-value aggregation responds buckets per week in the format year-week like 2023-47 for th 47th week of 2023
				"format" : "yyyy-ww"
			}
		},
		"document.datefield4": {
			"histogram": {
				"calendar_interval" : "day",   // This single-value aggregation responds buckets per day in the format year-month-day like 2023-12-31 for the day 31st of December 2023
				"format" : "yyyy-MM-dd",
"doc_count": 1,
                    "sum#invoice.turnover_sum": {
                        "value": 43.2
                    },
                    "max#invoice.turnover_max": {
               "size" : 5,       "value": 43.2
            // In this case of a histogram aggregation use},
this parameter for the number of partial values (buckets) within "histogram"!
                "min_doc_countmin#invoice.turnover_min": 1,{
            // This parameter forces to return only buckets with a least one document found."value": 43.2
                "sort": "_count",   }
           // Returns the buckets sorted by},
number of documents per bucket.            ...
    "order": "desc"       ]
        }
// The order can be "desc" or "asc" (default).
			}
		}
	},
}

...

Full path

...

[Gateway-URL]/search/export

...

HTTP method

...

POST

...

Success code

...

200: OK

...

Failure codes

...

404: Not Found
412: Precondition Failed
500: Internal Server Error

...

Types consumed

...

application/json

...

Types produced

...

text/csv;charset=UTF-8

Endpoint Request Parameter

...

Authorization

...

optional parameter

...

RequestHeader 

...

Accept-Language

...

optional parameter; default is locale of the server.

...

RequestHeader

Request (HTTP body) 

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

Notes:

  • The names of the object types and fields are the technical names, as used in yuuvis® RAD designer.
  • The delimiter character (separates each cell in a row) is configured in the search-prod.yml of the search service:
    csv.delimiter : ';'
    Default delimiter is  ';'.
  • Important: sort order is not considered

Example: Exporting Objects Created Within a Time Range

The following example exports the objects that were created yesterday as a CSV file.

Code Block
{
	"filters":
	{
		"created":
		{
			"o": "rg",
			"v1":"yesterday"
		}
	} }
}

Example: Use of Histograms for DateTime Properties

The following configuration shows how to use the aggregation attribute histogram for object properties of type datetime. Possible histograms can be used for days, weeks, month, and years.

Code Block
{
	"aggs": {  							
		"project.datefield1": {        // Beginning with version 9.16 LTS, the following histogram based aggregations for days, months, weeks, and years are supported:
			"histogram": {
				"calendar_interval" : "year",   // This single-value aggregation responds buckets per year
				"format" : "yyyy",              // The syntax of the format is that of Elasticsearch. It is important that calendar_interval and format must fit together to optain meaningful results.
                "size": 10,                     // Return maximal 10 buckets
			}                                   
		},
		"project.datefield2": {
			"histogram": {                           
				"calendar_interval" : "month",  // This single-value aggregation responds buckets per month in the format year-month like 2023-01 for January of 2023
				"format" : "yyyy-MM"
			}
		},
		"document.datefield3": {
			"histogram": {
				"calendar_interval" : "week",  // This single-value aggregation responds buckets per week in the format year-week like 2023-47 for th 47th week of 2023
				"format" : "yyyy-ww"
			}
		},
		"document.datefield4": {
			"histogram": {
				"calendar_interval" : "day",   // This single-value aggregation responds buckets per day in the format year-month-day like 2023-12-31 for the day 31st of December 2023
				"format" : "yyyy-MM-dd",
                "size" : 5,                     // In this case of a histogram aggregation use this parameter for the number of partial values (buckets) within "histogram"!
                "min_doc_count": 1,             // This parameter forces to return only buckets with a least one document found.
                "sort": "_count",               // Returns the buckets sorted by number of documents per bucket.
                "order": "desc"                 // The order can be "desc" or "asc" (default).
			}
		}
	},
}


Endpoint Method Overview for CSV Exports

PropertyValue
Full path
[Gateway-URL]/search/export
HTTP method
POST
Success code
200: OK
Failure codes
404: Not Found
412: Precondition Failed
500: Internal Server Error
Types consumed
application/json
Types produced
text/csv;charset=UTF-8

Endpoint Request Parameter

NameCommentType
Authorization
optional parameter
RequestHeader 
Accept-Language
optional parameter; default is locale of the server.
RequestHeader

Request (HTTP body) 

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

Notes:

  • The names of the object types and fields are the technical names, as used in yuuvis® RAD designer.
  • The delimiter character (separates each cell in a row) is configured in the search-prod.yml of the search service:
    csv.delimiter : ';'
    Default delimiter is  ';'.
  • Important: sort order is not considered

Example: Exporting Objects Created Within a Time Range

The following example exports the objects created yesterday as a CSV file.

Code Block
{
	"filters":
	{
		"created":
		{
			"o": "rg",
			"v1":"yesterday"
		}
	}
}

Beginning with version 10.16 LTS, the request parameter withurl=true leads to export with an additional column URL that contains the URL to open the object in the client. 

Remark: Beginning with version 10.6, the column labels are only given in English. If other labels should be contained in the CSV file, they must be part of the payload as shown below:

The list of fields controls the column sequence in the CSV file. The value of the fields contains the qualified name of the field (object type property) followed by the label (all characters after the first space). If no label is given, the technical name is used for it.

Code Block
{
  "types": [
    "personaldossier"
  ],
  "options": {
    ...
  },
  "fields": [
    "type Type",
    "personaldossier.dateofdeployment Date of employment",
    "personaldossier.class Class",
    "personaldossier.firstname First name",
    "personaldossier.surname Family name",
    ...
    "created Created",
    "creatortitle Creator",
    "modified Edited",
    "modifiertitle Editor"
  ]
}