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", lte = lower than equalgtelt, gtelte, 
      "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",      "thisweek", "v1lastweek":, "idpicthismonth",     },
"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",         "v1": "Developer""months", "quarters", "years",
      // can also be "null" to find objects with no value for this attribute     };     "basisdocument.age": { //       "o": "lte",       "v1": 50and 'number' as an integer like '12', e.g 'last12days'
       // for numeric fields"v1": "lastquarter"
    },
    "basisdocument.statuscreated": {             // object attribute
      "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>
      "personalfile.activesince": {
      "o": "eq",
      "v1": "2016-01-01T00:00:00.000Zidpic"
 // for date and datetime fields
 },
   }, 	"personalfilebasisdocument.pathactive": {			// 
      "o": "matcheq",					//
For string fields with classification 'Path', match all documents with paths that exist within a particular path
      "v1": "/Europe/Switzerland" 	// '/Europe/Switzerland', for example /Europe/Switzerland/Zürich, /Europe/Switzerland/Zürich (ZH), /Europe/Switzerland/Zürich/Winterthur
								 "v1": "true"           // field of type 'boolean' can also be "false" or "null"
    },
    "personalfile.employee": {
      "o": "in",
}   },   "typesv1": [
        "Applicant",         // optional: list of objectterms types combined with OR. InThe thewildcards case'*' ofand index'?' datacan search,be onlyused onein objectstring typefields. isFor allowedcatalog fields, the term must "picture"be an exact ],match of the "contextfoldertypes": [catalog value.
   // optional: list of context folders"Manager"
(technical names) combined with OR  ]
  "personalfile"  },
        "personalfile.cv.position": {	// <technical findname allof objectsobjecttype>.<technical thatname areof savedfield>.<technical inname theof generalcolumn>
location with 'sysroot'   ],   "fieldso": ["eq",
        // optional"v1": list"Developer" of general object attributes and index// fieldscan which shouldalso be returned"null" into thefind resultobjects with no value for this attribute
    };
    "basisdocument.age": {
     // if this section is not specified, a default set of general attributes as configured is delivered "o": "lte",
      "v1": 50           "type"     // for numeric fields
    },
     // default: technical name of object type as configured in the designer"basisdocument.status": {
      "o": "eq",
      "titlev1",: null                // default:For individuallyany defined for each object type
    "description",  field, this query returns documents that have no value in the named field.
    },
   // default "personalfile.activesince": individually{
defined for each object type    "o": "createdeq",
            "v1": "2016-01-01T00:00:00.000Z"  // default: thefor date theand objectdatetime wasfields
created    },
 	"creatorpersonalfile.path", : {			// 
            "o": "match",					// loginFor namestring offields the user who created the objectwith classification 'Path', match all documents with paths that exist within a particular path
      "creatorfullnamev1",       // default: full name of user who created the object; format: <first name> <name>
    "creatortitle",: "/Europe/Switzerland" 	// '/Europe/Switzerland', for example /Europe/Switzerland/Zürich, /Europe/Switzerland/Zürich (ZH), /Europe/Switzerland/Zürich/Winterthur
								   
    }
  },
  "types": [          // title of user who modified the object;// format: <name>,<first name> (<login name>)
    "modified",          optional: list of object types combined with OR. In the case of index data search, only one object type is allowed
    "picture"
  ],
  "contextfoldertypes": [    // defaultoptional: list theof context datefolders the(technical objectnames) wascombined modifiedwith OR
    "modifierpersonalfile",           // find all objects //that loginare namesaved ofin the usergeneral wholocation modifiedwith the'sysroot'
object  ],
  "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: mimetechnical typename of aobject filetype as givenconfigured in the operating systemdesigner
    "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",               // default: the ofdate the object was documentcreated file
    "filesizecreator",               // login name of the document file user who created the object
    "idpicture.widthcreatorfullname",        // anydefault: objectfull fieldname mustof beuser givenwho bycreated itsthe qualifiedobject; technicalformat: name<first inname> the<name>
format: <technical name of object type>_<technical name of field>"creatortitle",        "myobject.mytable.mycolumn",  // the columntitle of auser tablewho ofmodified anthe object
	"contextfolderid",
	"personalfile.name"
  ],; format: <name>,<first name> (<login name>)
    "options": { modified",              // optionaldefault: defines some special search behaviorsthe date the object was modified 
    "tracktotalhitsmodifier":, false  // wiht default 'true'      "searchmode": "idxs", // login name of // (default: "idxs")optional,  index data search; case insensitive with wildcards '*' and '?' allowed
               the user who modified the object
    "modifierfullname"       // default: full name of user who modified the object; format: <first name> <name>
    "modifiertitle",         // "fts" = 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,     // (default: false) if true, the "term" is interpreted in the syntax of the Elasticsearch engine
    "sort": {title of user who modified the object; format: <name>,<first name> (<login name>)
    "finalized"              // finalization state of an object showing 'true' or 'false'
    "mimetype",              // mime type of a file as given in the operating system
    "mimetypegroup",         // same as 'filetype' of the document file //which optional:group definesmime the sort order
      "created": {
         "order": "asc",types, e.g., all Microsoft Word mime types are grouped as 'word', and all image type as 'image'
    "filename",              // controlof the resultdocument order;file
possible settings are 'asc' and 'desc' "filetype",          "missing": "_first"   // controlof howthe todocument handlefile
missing field values: possible settings are "_lastfilesize", and "_first" in the list       }  // of the }document file
   "scope" : "allcontextfolderid",          // "all"id asof defaultthe searchesfolder inan indexdataobject and content, "indexdata" only is saved in
indexdata,
and "content" only in contents (document files)."idpicture.width,       } // any }
}

Result (response body)

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

Code Block
{
    "took": 31,                   object field must be given by its qualified technical name in the format: <technical name of object type>.<technical name of field>
    "myobject.mytable.mycolumn",  // time the responsecolumn neededof (ina milliseconds)table of an object
 	"timedpersonalfile.class_out": false,             // OK, no timeout was reachedid"  // beginning with 10.16 LTS, it is possible let the id of a catalog property be returned instead of the usual value with.
    "hits": {
        "total": 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"
        },
        "max_score": 2.1420739,     // for each hit, a score is given which can be used for sorting purposespersonalfile.class_data"// beginning with 10.16 LTS, it is possible let the data value of a catalog property be returned instead of the usual localized value
  ],
  "options": {               // 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
                             // "hitsfts": [{= full-text search
	"resolvereference":true, // (default: false) resolves ID references of users and objects
	"_indexresolveorgaddon" : "enaiored",    false,// name of search index database 
             "_type": "dmsobject",      // internal notation only
  (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,     // (default: false) if true, the "_idterm": "7A241428D3164044AB98533A70A382D4",is interpreted in the syntax of the Elasticsearch engine
    "sort": {        "_score": 2.1420739,       // optional: defines the sort order
      "_sourcecreated": {
         "order": "asc",     // listcontrol ofthe result listorder; parameterspossible assettings requestedare 'asc' and 'desc'
                "idpicture.firstname": "Martin",
                   "created": "2016-01-21T02:47:40Z",
  "missing": "_first" // control how to handle missing field values: possible settings are "_last" and "_first" in the list
      }
    }
    "modifiertitlescope" : "Roth, Rudgerall",          // "all" as default searches in indexdata and  content, "creatortitleindexdata": "Roth, Rudger" only in indexdata, and "content" only in contents (document files).
    }
       "modified": "2017-02-16T06:39:40Z",
   }
}

Result (response body)

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


Code Block
{
    "took": 31,                "id": "7A241428D3164044AB98533A70A382D4",    // IDtime of the object,response which must be used needed (in themilliseconds)
client URL to show the object as described in the following section "timed_out": false,             // OK, no timeout was reached
       "typehits": "idpicture",{
        "total": 5,                 // 5 hits are shown in the following hit list !! use this code in versions 6.0 or "idpicture.nameearlier
        "total": "Schriddel",
{					// 5 hits are shown  "idpicture.participant": "FEFA1C490EAE4EBDBBFC100C10627013",
				   "idpicture.participant_meta":{
        				"title": "Bartonitz, Martin",
        				"id": "2FF19AE615174A4188E2BB3AB3881FF3"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"
        },
       					 "type": "personalakte"
      				}
      "max_score": 2.1420739,     // for each hit, a score is given which can be used for sorting purposes
       }, 			"contexthits": [{ 								// context folder of this dms object 
				"title
             "_index": "Akteenaiored", 						    // titlename of search theindex contextdatabase folder
				"description": "Personalakte", 			// description of the context folder
				"id      "_type": "F6483A09F580420D86950BB4722D02A2dmsobject"//,  id of the context folder
			},
			...
// internal notation only
       }]     }, 	"config_id": {								// a result list configuration by type and optional context type.			"7A241428D3164044AB98533A70A382D4",        
             "type_score": "dokument"2.1420739,  
  "elements": [          "_source":  {               // list of fieldresult list parameters dependingas onrequested
the use of "type"       {         "nameidpicture.firstname": "typeMartin",
         "qname": "sysobject.type",         "hitnamecreated": "type2016-01-21T02:47:40Z",
         "label": "Type",         "descriptionmodifiertitle": "Type of the object.Roth, Rudger",
        "type": "STRING",           "readonlycreatortitle": true,"Roth, Rudger",
         "baseparameter": true,         "systemmodified": true"2017-02-16T06:39:40Z",
        "selectedforenrichment": false,           "requiredid": true"7A241428D3164044AB98533A70A382D4",    // ID of the  "maxlen": 0,
        "minlen": 0,object, which must be used in the client URL to show the object as described in the following section
         "scale": 0,         "precisiontype": 0"idpicture",           "withtime": false       },      
{         "name": "mimetypegroup",         "qnameidpicture.name": "sysdocument.mimetypegroupSchriddel",
				   "idpicture.participant": "FEFA1C490EAE4EBDBBFC100C10627013",
				   "hitnameidpicture.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,{ 								// 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
			},
			...
        }]
    },
	"minlenconfig": 0,
    {								// 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
      },
      {
        "name": "titel",
	...
        "qname": "dokument.titel",
        "hitname": "dokument.titel",
      }

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",         // operator for range
     "v1": "none"       // none stands for no content (document file)
  },
  "folder": {           // this determines to exclude folders
     "o": "eq  "label": "titel",
        "description": "titel",
        "type": "STRING",
        "readonly": false,
        "baseparameter": false,
        "system": false,
        "selectedforenrichment": false,
        "required": true,
        "maxlen": 50,
        "minlen": 5,
        "scale": 0,
        "precision": 0,
        "withtime": false
      },
      {
        "name": "bemerkung",
        "qname": "dokument.bemerkung",
        "hitname": "dokument.bemerkung",
        "label": "bemerkung",
        "description": "bemerkung",
        "type": "STRING",
        "readonly": false,
        "baseparameter": false,
        "system": false,
        "selectedforenrichment": false,
        "required": false,
        "maxlen": 200,
        "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 do not contain a document file.

Code Block
titleDocuments without a file
"filters": {
  "filesize": {
     "o": "rg",         // operator for range
     "v1": "none"       // none stands for no content (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
{
	"term": "txt_sysemail_systo:irina@qs.optimal-systems.de OR txt_sysemail_syscc:irina@qs.optimal-systems.de",
	"options": 
	{
		"expertmode": true           
	}
}

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": {             // field of type string
     "o": "eq",         
     "v1": "Thomas",
     "v1usenot" : falsetrue
  }
}

Example: Searching

...

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.

...

with "usenot" for catalog fields

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

Code Block
"filters": {
  "employee.class": {             // field of type catalog 
     "o": "in",
     "v1": "freelancer",
     "usenot" : true
  
	}
}

Endpoint Method Overview for Aggregations

...

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
{
	"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 likeas 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.

...