Index Fields Management Services - CaseIndexerFieldsManager

Info

WADL definition is available at:
https://<hgdb_server_name>[:port]/mercury-ws-app/restServices/CaseIndexerFieldsManagerRest.wadl

Example: https://testcluster.hgdb.io/mercury-ws-app/restServices/CaseIndexerFieldsManagerRest.wadl.

A service created to support query building mechanisms. It contains a number of methods that allow you to retrieve information about indexed fields and their statistics. Below is a list of available methods with their descriptions divided into functional categories:

Retrieving data about field types

	Method(HTTP Method)	Description
✅️	getSearchTypes(POST)	Gets the search types in the Lucene index associated with the field definition.
✅️	getCategories(POST)	Gets the field categories. A field category is a description of where the fields come from. If we look at the Lucene Index article, we will find that fields come from different case object storage structures.

Gets field data by search type

	Method(HTTP Method)	Description
✅️	getFieldsBySerachType(POST)	Gets a list of fields for a specific search field type.

Gets field data by field category

	Method(HTTP Method)	Description
✅️	getFields(POST)	retrieves a list of all index fields divided into their categories.
✅️	getFieldsByCategory(POST)	retrieves a list of fields for a specific category.
✅️	getFieldsByTypeCodes(POST)	retrieves a list of fields for the definition/case type with the given code.
✅️	getFieldsByTypeCodesAndCategory(POST)	retrieves a list of fields for the definition/case type with the given code and for the given category.
✅️	getFieldsByTypeIds(POST)	retrieves a list of fields for a case definition/type with the given code.
✅️	getFieldsByTypeIdsAndCategory(POST)	retrieves a list of fields for a case definition/type with the given type version identifier and for the given category.

Retrieving field data for complex fields

	Method(HTTP Method)	Description
✅️	getFieldsBySubFieldName(POST)	retrieves a list of fields for a parent case field defined by the type of another (sub) case.
✅️	getFieldsBySubFieldNameAndTypeCode(POST)	get list of fields for parent case field, defined by type of another (sub) case for given case type code.

Get field statistics

	Method(HTTP Method)	Description
✅️	getFieldsStatisticsByFieldName(POST)	get statistics of field with given name. Optionally, you can provide field value.

Get field type data

Use case

Can be used to get data that we will later use to build criteria in field data getter services.

Services return simple lists of search type or category names in response (response structure):

Parameter	Description	Example value
errorCode	Error code. When the operation is successful, it takes the value null . Information about the data contained in the value of this parameter can be obtained by reading the article What does the value of the "errorCode" field mean?	`null`
errorMessage	Error message. When the operation is successful, it takes the value `null` .	`null`
bag	List of string values - names.	`[]`

getSearchTypes

Get a list of Lucene index field type names. Field types are described in the article describing Lucene Index.

Fixed method result

Generally speaking, the list is fixed, the query result is fixed for a given version of the Mercury DB (HgDB) 3.0 system implementation, so we could try to define the list permanently in our solutions, instead of issuing a query.

The method has only one input argument:

Parameter name	Type	Required?	Description	Example value
context	`Context`	Yes	Request context. You can find more about the context in the article SOAP/REST service request context.	`{ "appName": "mercury-ws-app", "appVersion": "0.0.1", "userName": "ttesteusz", ... }`

Example of a JSON method request for a REST service.

{
  "context": {
    "appName": "mercury-ws-app",
    "appVersion": "1.0",
    "userName": "anonymous",
    "comment": null,
    "maxResults": 10000,
    "queryTimeout": 2147483647,
    "locale": "pl_PL",
    "timeZone": "Europe/Warsaw",
    "userFullName": null,
    "eager4omdBuilder": "true",
    "trustedData": false,
    "ignoredCustomFields": null,
    "currentRole": null,
    "userRoles": null,
    "sourceOfRequest": "USER_DEV.localhost",
    "rootVersionContextID": null,
    "rootTagName": null,
    "directRequest": false,
    "formats": {
      "date.format.long": "dd-MM-yyyy HH:mm:ss XXX"
    },
    "ignoreAlternateFields": true,
    "decodeResult": "DATE_AND_LOB",
    "maxDepthResult": 3,
    "decodeRequest": "DATE_AND_LOB",
    "ignoreCaseHeaderInResponse": true,
    "cacheUsage": "REFRESH",
    "httpResponseCacheUsage": "NONE",
    "defaultLuceneSortClause": null,
    "viewDefinition": null
  }
}

Response example - Lucene index field type list
{
   "errorCode": null,
   "errorMessage": null,
   "bag":    [
      "LongField",
      "StringField",
      "TextField",
      "SubQuery",
      "IntField",
      "DateField",
      "CompositeIdField",
      "FloatField",
      "DoubleField"
   ]
}

getCategories

Get the list of Lucene index field categories related to the field definition (see Fixed/predefined fields). Recall that field categories correspond to the names of entities from which the predefined fields come.

Fixed method result

In general, the list of predefined field categories is fixed, the query result is fixed for a given version of the Mercury DB (HgDB) 3.0 system implementation, so we could try to define the list permanently in our solutions, instead of issuing a query.

The method has only one input argument:

Parameter name	Type	Required?	Description	Example value
context	`Context`	Yes	Request context. For more on context, see SOAP/REST Service Request Context.	`{ "appName": "mercury-ws-app", "appVersion": "0.0.1", "userName": "ttesteusz", ... }`

Example of a JSON method request for a REST service.

{
  "context": {
    "appName": "mercury-ws-app",
    "appVersion": "1.0",
    "userName": "anonymous",
    "comment": null,
    "maxResults": 10000,
    "queryTimeout": 2147483647,
    "locale": "pl_PL",
    "timeZone": "Europe/Warsaw",
    "userFullName": null,
    "eager4omdBuilder": "true",
    "trustedData": false,
    "ignoredCustomFields": null,
    "currentRole": null,
    "userRoles": null,
    "sourceOfRequest": "USER_DEV.localhost",
    "rootVersionContextID": null,
    "rootTagName": null,
    "directRequest": false,
    "formats": {
      "date.format.long": "dd-MM-yyyy HH:mm:ss XXX"
    },
    "ignoreAlternateFields": true,
    "decodeResult": "DATE_AND_LOB",
    "maxDepthResult": 3,
    "decodeRequest": "DATE_AND_LOB",
    "ignoreCaseHeaderInResponse": true,
    "cacheUsage": "REFRESH",
    "httpResponseCacheUsage": "NONE",
    "defaultLuceneSortClause": null,
    "viewDefinition": null
  }
}

Answer Example - Lucene Index Constant Field Type Category List
{
   "errorCode": null,
   "errorMessage": null,
   "bag":    [
      "Comment",
      "TypeCode",
      "QuickTask",
      "TypeKind",
      "TypeCase",
      "GroupCase",
      "Source",
      "Case",
      "CaseDocument",
      "KtmNumber",
      "Participant",
      "InitStatus"
   ]
}

Retrieving field data by type

Use case

Let's assume that we are building a query builder. We can use all services to suggest the field name to use in the query being constructed.

Using the getSearchTypes(POST) method, we retrieve a list of search types, and then we can use the following methods to retrieve Lucene index field data for a given search type.

getFieldsBySearchType

Retrieving a list of Lucene index fields for a given search type. Search types are described in the article Lucene Index.

The method has the following input argument:

Parameter name	Type	Required?	Description	Example value
context	`Context`	Yes	Request context. For more information about context, see SOAP/REST Service Request Context.	`{ "appName": "mercury-ws-app", "appVersion": "0.0.1", "userName": "ttesteusz", ... }`
searchType	`String`	Yes	Name of the field type for which the field list is to be presented. See the description of Lucene Index.	`"DateField"`
complexity	`String`	No	Filtering the field list by the `complexity`¹ parameter representing the complexity of the field. The argument can take one of the following values: `SIMPLE`, `SUBCASE`, `ALL`. If we do not send any value, the default value is `SIMPLE`.	`"SIMPLE"`

Example of a method request in JSON form for the REST service. Retrieving a list of fields of type DateField.

{
	"context": {
		"appName": "mercury-ws-app",
		"appVersion": "1.0",
		"userName": "anonymous",
		"comment": null,
		"maxResults": 10000,
		"queryTimeout": 2147483647,
		"locale": "pl_PL",
		"timeZone": "Europe/Warsaw",
		"userFullName": null,
		"eager4omdBuilder": "true",
		"trustedData": false,
		"ignoredCustomFields": null,
		"currentRole": null,
		"userRoles": null,
		"sourceOfRequest": "USER_DEV.localhost",
		"rootVersionContextID": null,
		"rootTagName": null,
		"directRequest": false,
		"formats": {
			"date.format.long": "dd-MM-yyyy HH:mm:ss XXX"
		},
		"ignoreAlternateFields": true,
		"decodeResult": "DATE_AND_LOB",
		"maxDepthResult": 3,
		"decodeRequest": "DATE_AND_LOB",
		"ignoreCaseHeaderInResponse": true,
		"cacheUsage": "REFRESH",
		"httpResponseCacheUsage": "NONE",
		"defaultLuceneSortClause": null,
		"viewDefinition": null
	},
	"searchType": "DateField"
}

Response parameters of methods for retrieving field data by type

In response, we will receive an object with the following structure:

Parameter	Description	Example value
errorCode	Error code. When the operation is successful, it takes the value `null`. Information about the data contained in the value of this parameter can be obtained by reading the article What does the value of the "errorCode" field mean?	`null`
errorMessage	Error message. When the operation is successful, it takes the value `null`. See also the article What does the value of the "errorCode" field mean?	`null`
dto	An IndexFieldSearchType object with a list of fields associated with a given search type.	`{ "searchType": "DateField", "fields": [...] }`

IndexFieldSearchType


Layers used	Business
Type	Business object
Java interface	Serializable, IFieldCollector
Java implementation	`pro.ibpm.mercury.lucene.indexers.api.IndexFieldSearchType`
DTO implementation	`pro.ibpm.mercury.lucene.indexers.api.IndexFieldSearchType`
XML definition	hgdb-lucene-indexers-3.0.xsd

Search result. An object representing a category with its list of fields.

XML field	JSON field	Description	Type	Example value
searchType	searchType	The search type for which fields are returned.	`String`	`DateField`
field	fields	A list of values of type IndexField representing data describing Lucene index fields.	`List<IndexField>`	`[{"name": "mrc_createDate", "type": "DateField", "complexity": "SIMPLE", "category": "Case", "searchType": "DateField"}, {"name": "mrc_updateDate", "type": "DateField", "complexity": "SIMPLE", "category": "Case", "searchType": "DateField"}]`

IndexField


Layers used	Business
Type	Business Object
Java Interface	Serializable
Java Implementation	`pro.ibpm.mercury.lucene.indexers.api.IndexField`
DTO implementation	`pro.ibpm.mercury.lucene.indexers.api.IndexField`
XML definition	hgdb-lucene-indexers-3.0.xsd

Search result element. Its task is to send a minimal and sufficiently large amount of data that uniquely describes the Lucene index field.

XML field	JSON field	Description	Type	Example value
fieldName	fieldName	Field name.	`String`	`mrc_createDate`
-	name	Name that is the basis for creating the Lucene index field name. The field does not appear in SOAP services.	`String`	`mrc_createDate`
searchType	searchType	Field type. See the description of Lucene Index.	`String`	`DateField`
alternateSearchTypes	alternateSearchTypes	Alternative search types for which the field can be used.	`List<String>`	`["DateField", "StringField"]`
store	store	Whether the field is stored in the index. The value `NO` means that the field is not stored in the index, and its value is calculated based on other fields.	`String`	`NO`
-	paramName	The name of the parameter used for searching in the relational database. It can be empty if the field is not a case parameter - a field based on which we will find a direct link to the basic information of the parameter definition. Additionally, the field is used to verify permissions. The field is not present in SOAP services.	`String`	`null`
-	entityFieldName	The name of the field in the entity, if the field is mapped to an entity field. The field is not present in SOAP services.	`String`	`null`
category	category	The category of the field, corresponding to the name of the entity the field comes from. See the description of the [Lucene Index] field categories (/docs/Architecture/Index_Lucene/#predefined-constants-field-names).	`String`	`Case`
recommendedLabel	recommendedLabel	The recommended label for the field, if available.	`String`	`null`
sorted	sorted	Is the field sorted?	`Boolean`	`true` or `false`
complexity	complexity	The complexity of the field. It can take values `SIMPLE` (a simple field) or `SUBCASE` (a complex field representing a sub-case).	`String`	`SIMPLE`

Example of an IndexField object in JSON
{
  "fieldName": "mrc_createDate",
  "name": "mrc_createDate",
  "searchType": "DateField",
  "alternateSearchTypes": ["DateField", "StringField"],
  "store": "NO",
  "paramName": null,
  "entityFieldName": null,
  "category": "Case",
  "recomendedLabel": null,
  "sorted": false,
  "complexity": "SIMPLE"
}

Example of response of methods for retrieving data about fields by type

Example of response of method getFieldsBySearchType(POST) to request for retrieving fields of type SubQuery

REST service response example
SOAP service response example

{
  "errorCode": null,
  "errorMessage": null,
  "dto": {
    "searchType": "SubQuery",
    "fields": [
      {
      "fieldName": "acceptance",
      "name": "acceptance",
      "searchType": "SubQuery",
      "alternateSearchTypes": null,
      "store": "NO",
      "paramName": null,
      "entityFieldName": null,
      "category": "Case",
      "recomendedLabel": null,
      "sorted": false,
      "complexity": "SUBCASE"
      },
      {
      "fieldName": "acceptor",
      "name": "acceptor",
      "searchType": "SubQuery",
      "alternateSearchTypes": null,
      "store": "NO",
      "paramName": null,
      "entityFieldName": null,
      "category": "Case",
      "recomendedLabel": null,
      "sorted": false,
      "complexity": "SUBCASE"
      }
    ]
  }
}

<return>
  <errorCode/>
  <errorMessage/>
  <dto xmlns="http://index.lucene.hgdb.io/searchFields"
      xsi:schemaLocation="http://index.lucene.hgdb.io/searchFields https://hgdb.org/xsd/lucene/hgdb-lucene-indexers-3.0.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <searchType>SubQuery</searchType>
      <field>
        <fieldName>acceptance</fieldName>
        <searchType>SubQuery</searchType>
        <store>NO</store>
        <category>Case</category>
        <sorted>false</sorted>
        <complexity>SUBCASE</complexity>
      </field>
      <field>
        <fieldName>acceptor</fieldName>
        <searchType>SubQuery</searchType>
        <store>NO</store>
        <category>Case</category>
        <sorted>false</sorted>
        <complexity>SUBCASE</complexity>
      </field>
  </dto>
</return>

soapui_getFieldsBySerachType

Retrieving data about fields divided into field categories

Use case

Let's assume that we are building a query builder. We can use all services for mechanisms suggesting what field name to use in the constructed query.

getFields

Retrieving a list of all Lucene index fields divided into their categories. Field category is a description of the origin of the fields. If we review the Lucene Index article, we will learn that the fields come from different case object storage structures. The method has the following input argument:

Parameter name	Type	Required?	Description	Example value
context	`Context`	Yes	Request context. You can find more about context in the article SOAP/REST Service Request Context.	`{ "appName": "mercury-ws-app", "appVersion": "0.0.1", "userName": "ttesteusz", ... }`
complexity	`String`	No	Filtering the list of fields by the `complexity`¹ parameter representing the complexity of the field. The argument can take one of the following values: `SIMPLE`, `SUBCASE`, `ALL`. If no value is sent, the default value is `SIMPLE`.	`"SIMPLE"`

Example method request in JSON form for the REST service for the complexity of the SUBCASE field.

{
	"context": {
		"appName": "mercury-ws-app",
		"appVersion": "1.0",
		"userName": "anonymous",
		"comment": null,
		"maxResults": 10000,
		"queryTimeout": 2147483647,
		"locale": "pl_PL",
		"timeZone": "Europe/Warsaw",
		"userFullName": null,
		"eager4omdBuilder": "true",
		"trustedData": false,
		"ignoredCustomFields": null,
		"currentRole": null,
		"userRoles": null,
		"sourceOfRequest": "USER_DEV.localhost",
		"rootVersionContextID": null,
		"rootTagName": null,
		"directRequest": false,
		"formats": {
			"date.format.long": "dd-MM-yyyy HH:mm:ss XXX"
		},
		"ignoreAlternateFields": true,
		"decodeResult": "DATE_AND_LOB",
		"maxDepthResult": 3,
		"decodeRequest": "DATE_AND_LOB",
		"ignoreCaseHeaderInResponse": true,
		"cacheUsage": "REFRESH",
		"httpResponseCacheUsage": "NONE",
		"defaultLuceneSortClause": null,
		"viewDefinition": null
	},
	"complexity": "SUBCASE"
}

getFieldsByCategory

Gets a list of fields for a specific category. A field category is a description of where the fields come from. If we look at the Lucene Index article, we will find that the fields come from different case object storage structures. The method has the following input argument:

Parameter name	Type	Required?	Description	Example value
context	`Context`	Yes	The request context. You can find more about the context in the SOAP/REST Service Request Context article.	`{ "appName": "mercury-ws-app", "appVersion": "0.0.1", "userName": "ttesteusz", ... }`
category	`String`	Yes	The field category for which the field list is to be presented. See the description of the [Lucene Index] field category (/docs/Architecture/Lucene_Index/#predefined-constants-field-names).	`"Case"`
complexity	`String`	No	Filter the list of fields by the `complexity`¹ parameter representing the complexity of the field. The argument can take one of the following values: `SIMPLE`, `SUBCASE`, `ALL`. If no value is passed, the default value is `SIMPLE`.	`"SIMPLE"`

Example method request in JSON form for the REST service for the Case category with the complexity of SUBCASE.

{
  "context": {
    "appName": "mercury-ws-app",
    "appVersion": "1.0",
    "userName": "anonymous",
    "comment": null,
    "maxResults": 10000,
    "queryTimeout": 2147483647,
    "locale": "pl_PL",
    "timeZone": "Europe/Warsaw",
    "userFullName": null,
    "eager4omdBuilder": "true",
    "trustedData": false,
    "ignoredCustomFields": null,
    "currentRole": null,
    "userRoles": null,
    "sourceOfRequest": "USER_DEV.localhost",
    "rootVersionContextID": null,
    "rootTagName": null,
    "directRequest": false,
    "formats": {
      "date.format.long": "dd-MM-yyyy HH:mm:ss XXX"
    },
    "ignoreAlternateFields": true,
    "decodeResult": "DATE_AND_LOB",
    "maxDepthResult": 3,
    "decodeRequest": "DATE_AND_LOB",
    "ignoreCaseHeaderInResponse": true,
    "cacheUsage": "REFRESH",
    "httpResponseCacheUsage": "NONE",
    "defaultLuceneSortClause": null,
        "viewDefinition": null
    },
    "category":"Case",
    "complexity": "SUBCASE"  
}

getFieldsByTypeCodes

Gets a list of fields defined in the Lucene index assigned to a defined case object type, based on its code. The method has the following input argument:

Parameter name	Type	Required?	Description	Example value
context	`Context`	Yes	Request context. For more on context, see SOAP/REST Service Request Context.	`{ "appName": "mercury-ws-app", "appVersion": "0.0.1", "userName": "ttesteusz", ... }`
typeCodes	`String[]`	Yes	List of case type codes for which the list of fields is to be presented. See the description of the case type codes entity TypeCode.	`["ElixAddress", "FsmTimeSlot"]`
complexity	`String`	No	Filtering the list of fields by the parameter `complexity`¹ representing the complexity of the field. The argument can take one of the following values: `SIMPLE`, `SUBCASE`, `ALL`. If no value is passed, the default value is `SIMPLE`.	`"SIMPLE"`

Example method request in JSON form for the REST service for case type codes ElixAddress and FsmTimeSlot with complexity SIMPLE.

{
  "context": {
    "appName": "mercury-ws-app",
    "appVersion": "1.0",
    "userName": "anonymous",
    "comment": null,
    "maxResults": 10000,
    "queryTimeout": 2147483647,
    "locale": "pl_PL",
    "timeZone": "Europe/Warsaw",
    "userFullName": null,
    "eager4omdBuilder": "true",
    "trustedData": false,
    "ignoredCustomFields": null,
    "currentRole": null,
    "userRoles": null,
    "sourceOfRequest": "USER_DEV.localhost",
    "rootVersionContextID": null,
    "rootTagName": null,
    "directRequest": false,
    "formats": {
      "date.format.long": "dd-MM-yyyy HH:mm:ss XXX"
    },
    "ignoreAlternateFields": true,
    "decodeResult": "DATE_AND_LOB",
    "maxDepthResult": 3,
    "decodeRequest": "DATE_AND_LOB",
    "ignoreCaseHeaderInResponse": true,
    "cacheUsage": "REFRESH",
    "httpResponseCacheUsage": "NONE",
    "defaultLuceneSortClause": null,
        "viewDefinition": null
  },
  "typeCodes":["ElixAddress", "FsmTimeSlot"],
  "complexity":"SIMPLE"
}

getFieldsByTypeCodesAndCategory

Gets a list of fields defined in the Lucene index assigned to a defined case object type, based on its code, with an additional criterion indicating the field category. The method has the following input argument:

Parameter name	Type	Required?	Description	Example value
context	`Context`	Yes	Request context. For more on context, see SOAP/REST service request context.	`{ "appName": "mercury-ws-app", "appVersion": "0.0.1", "userName": "ttesteusz", ... }`
typeCodes	`String[]`	Yes	List of case type codes for which the field list is to be presented. See the description of the entity for case type codes TypeCode.	`["ElixAddress", "FsmTimeSlot"]`
category	`String`	Yes	The field category for which the field list is to be presented. See the description of the field category Lucene Index.	`"Case"`
complexity	`String`	No	Filtering the field list by the parameter `complexity`¹ representing the complexity of the field. The argument can take one of the following values: `SIMPLE`, `SUBCASE`, `ALL`. If no value is passed, the default value is `SIMPLE`.	`"SIMPLE"`

Example of a JSON method request for a REST service for case type codes ElixAddress and FsmTimeSlot with complexity SIMPLE and category Case.

{
  "context": {
    "appName": "mercury-ws-app",
    "appVersion": "1.0",
    "userName": "anonymous",
    "comment": null,
    "maxResults": 10000,
    "queryTimeout": 2147483647,
    "locale": "pl_PL",
    "timeZone": "Europe/Warsaw",
    "userFullName": null,
    "eager4omdBuilder": "true",
    "trustedData": false,
    "ignoredCustomFields": null,
    "currentRole": null,
    "userRoles": null,
    "sourceOfRequest": "USER_DEV.localhost",
    "rootVersionContextID": null,
    "rootTagName": null,
    "directRequest": false,
    "formats": {
      "date.format.long": "dd-MM-yyyy HH:mm:ss XXX"
    },
    "ignoreAlternateFields": true,
    "decodeResult": "DATE_AND_LOB",
    "maxDepthResult": 3,
    "decodeRequest": "DATE_AND_LOB",
    "ignoreCaseHeaderInResponse": true,
    "cacheUsage": "REFRESH",
    "httpResponseCacheUsage": "NONE",
    "defaultLuceneSortClause": null,
        "viewDefinition": null
  },
  "typeCodes":["ElixAddress", "FsmTimeSlot"],
  "category":"Case",
  "complexity":"SIMPLE"
}

getFieldsByTypeIds

Gets a list of fields defined in the Lucene index assigned to the defined case object type, based on its identifier. The method has the following input argument:

Parameter name	Type	Required?	Description	Example value
context	`Context`	Yes	The request context. For more on context, see SOAP/REST Service Request Context.	`{ "appName": "mercury-ws-app", "appVersion": "0.0.1", "userName": "ttesteusz", ... }`
typeIds	`Long[]`	Yes	List of case type identifiers for which the field list is to be presented. See the description of the TypeCase case type entity.	`[123344, 123345]`
complexity	`String`	No	Filter the list of fields by the parameter `complexity`¹ representing the complexity of the field. The argument can take one of the following values: `SIMPLE`, `SUBCASE`, `ALL`. If no value is passed, the default value is `SIMPLE`.	`"SIMPLE"`

Example method request in JSON form to the REST service for case type identifiers 123344 and 123345 with complexity SIMPLE.

{
  "context": {
    "appName": "mercury-ws-app",
    "appVersion": "1.0",
    "userName": "anonymous",
    "comment": null,
    "maxResults": 10000,
    "queryTimeout": 2147483647,
    "locale": "pl_PL",
    "timeZone": "Europe/Warsaw",
    "userFullName": null,
    "eager4omdBuilder": "true",
    "trustedData": false,
    "ignoredCustomFields": null,
    "currentRole": null,
    "userRoles": null,
    "sourceOfRequest": "USER_DEV.localhost",
    "rootVersionContextID": null,
    "rootTagName": null,
    "directRequest": false,
    "formats": {
      "date.format.long": "dd-MM-yyyy HH:mm:ss XXX"
    },
    "ignoreAlternateFields": true,
    "decodeResult": "DATE_AND_LOB",
    "maxDepthResult": 3,
    "decodeRequest": "DATE_AND_LOB",
    "ignoreCaseHeaderInResponse": true,
    "cacheUsage": "REFRESH",
    "httpResponseCacheUsage": "NONE",
    "defaultLuceneSortClause": null,
        "viewDefinition": null
  },
  "typeIds":[123344, 123345],
  "complexity":"SIMPLE"
}

getFieldsByTypeIdsAndCategory

Gets a list of fields defined in the Lucene index assigned to a defined case object type, based on its identifier, with an additional criterion indicating the field category. The method has the following input argument:

Parameter name	Type	Required?	Description	Example value
context	`Context`	Yes	Request context. For more on context, see SOAP/REST service request context.	`{ "appName": "mercury-ws-app", "appVersion": "0.0.1", "userName": "ttesteusz", ... }`
typeIds	`Long[]`	Yes	List of case type identifiers for which the field list is to be presented. See the description of the [TypeCase] entity (/docs/Architecture/Cases_MetaData/#typecase).	`[123344, 123345]`
category	`String`	Yes	The field category for which the field list is to be presented. See the description of the [Lucene Index] field category (/docs/Architecture/Index_Lucene/#fixedpredefined-field-names).	`"Case"`
complexity	`String`	No	Filtering the field list by the `complexity`¹ parameter representing the complexity of the field. The argument can take one of the following values: `SIMPLE`, `SUBCASE`, `ALL`. If no value is passed, the default value is `SIMPLE`.	`"SIMPLE"`

Example of a JSON method request for a REST service for case type identifiers 123344 and 123345 with complexity SIMPLE and category Case.

{
  "context": {
    "appName": "mercury-ws-app",
    "appVersion": "1.0",
    "userName": "anonymous",
    "comment": null,
    "maxResults": 10000,
    "queryTimeout": 2147483647,
    "locale": "pl_PL",
    "timeZone": "Europe/Warsaw",
    "userFullName": null,
    "eager4omdBuilder": "true",
    "trustedData": false,
    "ignoredCustomFields": null,
    "currentRole": null,
    "userRoles": null,
    "sourceOfRequest": "USER_DEV.localhost",
    "rootVersionContextID": null,
    "rootTagName": null,
    "directRequest": false,
    "formats": {
      "date.format.long": "dd-MM-yyyy HH:mm:ss XXX"
    },
    "ignoreAlternateFields": true,
    "decodeResult": "DATE_AND_LOB",
    "maxDepthResult": 3,
    "decodeRequest": "DATE_AND_LOB",
    "ignoreCaseHeaderInResponse": true,
    "cacheUsage": "REFRESH",
    "httpResponseCacheUsage": "NONE",
    "defaultLuceneSortClause": null,
        "viewDefinition": null
  },
  "typeIds":[123344, 123345],
  "category":"Case",
  "complexity":"SIMPLE"
}

Response parameters of methods for retrieving data about fields divided into field categories

In response, we will receive an object with the following structure:

Parameter	Description	Example value
errorCode	Error code. When the operation is successful, it takes the value `null`. Information about the data contained in the value of this parameter can be obtained by reading the article What does the value of the "errorCode" field mean?	`null`
errorMessage	Error message. When the operation is successful, it takes the value `null`. See also the article What does the value of the "errorCode" field mean?	`null`
map/dto	Map, the key of which is the name representing the field category. The value of the map is represented by a list of the object IndexFieldCategory with a list of fields associated with a given category. The map may be empty if there is no case type defined in the system with the given type code.	`{ "category": "Case", "fields": [...] }`

IndexFieldCategory


Layers used in	Business
Type	Business object
Java interface	Serializable, IFieldCollector
Java implementation	`pro.ibpm.mercury.lucene.indexers.api.IndexFieldCategory`
DTO implementation	`pro.ibpm.mercury.lucene.indexers.api.IndexFieldCategory`
XML definition	hgdb-lucene-indexers-3.0.xsd

An object representing a category with its list of fields.

XML field	JSON field	Description	Type	Example value
category	category	The field category, corresponding to the name of the entity from which the field comes. See the description of the Lucene Index field category.	`String`	`Case`
field	fields	A list of values of type IndexField representing data describing Lucene index fields.	`List<IndexField>`	`[{"name": "mrc_createDate", "type": "DateField", "complexity": "SIMPLE", "category": "Case", "searchType": "DateField"}, {"name": "mrc_updateDate", "type": "DateField", "complexity": "SIMPLE", "category": "Case", "searchType": "DateField"}]`

Example of an IndexFieldCategory object in JSON form
{
  "category": "Case",
  "fields": [
    {
      "fieldName": "mrc_createDate",
      "name": "mrc_createDate",
      "searchType": "DateField",
      "alternateSearchTypes": ["DateField", "StringField"],
      "store": "NO",
      "paramName": null,
      "entityFieldName": null,
      "recomendedLabel": null,
      "sorted": false,
      "complexity": "SIMPLE"
    },
    {
      "fieldName": "mrc_updateDate",
      "name": "mrc_updateDate",
      "searchType": "DateField",
      "alternateSearchTypes": ["DateField", "StringField"],
      "store": null,
      "paramName": null,
      "entityFieldName": null,
      "recomendedLabel": null,
      "sorted": false,
      "complexity": null
    }
  ]
}

Example of response of methods of methods for retrieving data about fields by field category

Example of response of method getFieldsByCategory(POST) to request for retrieving fields for category Case

REST service response example
SOAP service response example

{
  "errorCode": null,
  "errorMessage": null,
  "map": {
    "Case": {
      "category": "Case",
      "fields": [
        {
          "fieldName": "mrc_createDate",
          "name": "mrc_createDate",
          "searchType": "DateField",
          "alternateSearchTypes": ["DateField", "StringField"],
          "store": "NO",
          "paramName": null,
          "entityFieldName": null,
          "recomendedLabel": null,
          "sorted": true,
          "complexity": "SIMPLE"
        },
        {
          "fieldName": "mrc_updateDate",
          "name": "mrc_updateDate",
          "searchType": "DateField",
          "alternateSearchTypes": ["DateField", "StringField"],
          "store": null,
          "paramName": null,
          "entityFieldName": null,
          "recomendedLabel": null,
          "sorted": true,
          "complexity": "SIMPLE"
        }
      ]
    }
  }
}

<return>
  <errorCode/>
  <errorMessage/>
  <map xmlns="http://index.lucene.hgdb.io/searchFields"
      xsi:schemaLocation="http://index.lucene.hgdb.io/searchFields https://hgdb.org/xsd/lucene/hgdb-lucene-indexers-3.0.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <entry>
        <key>Case</key>
        <value>
          <category>Case</category>
          <field>
            <fieldName>mrc_createDate</fieldName>
            <searchType>DateField</searchType>
            <store>NO</store>
            <recomendedLabel/>
            <sorted>true</sorted>
            <complexity>SIMPLE</complexity>
          </field>
          <field>
            <fieldName>mrc_updateDate</fieldName>
            <searchType>DateField</searchType>
            <store/>
            <recomendedLabel/>
            <sorted>true</sorted>
            <complexity>SIMPLE</complexity>
          </field>
        </value>
      </entry>
  </map>
</return>

soapui_getFieldsByTypeCodes

Retrieving data about complex fields

Use case

Let's assume that we are building a query builder. We can use all services for mechanisms suggesting what field name to use in the constructed query.

Retrieving data about fields for complex fields pointing to sub-cases.

getFieldsBySubFieldName

Method that retrieves Lucene index field definitions for complex fields whose representation is defined as a dependent case. The list of complex fields can be retrieved using the getFieldsByCategory(POST) method by setting the request arguments "category": "Case" and "complexity": "SUBCASE". The input parameters of the request are as follows:

Parameter name	Type	Required?	Description	Example value
context	`Context`	Yes	The request context. For more on context, see SOAP/REST Service Request Context.	`{ "appName": "mercury-ws-app", "appVersion": "0.0.1", "userName": "ttesteusz", ... }`
fieldName	`String`	Yes	The name of the field for which the field list is to be presented. The field must be a complex field representing a child case.	`"address"`

Example of a JSON method request for a REST service. Retrieving data about a complex field named address.

{
  "context": {
    "appName": "mercury-ws-app",
    "appVersion": "1.0",
    "userName": "anonymous",
    "comment": null,
    "maxResults": 10000,
    "queryTimeout": 2147483647,
    "locale": "pl_PL",
    "timeZone": "Europe/Warsaw",
    "userFullName": null,
    "eager4omdBuilder": "true",
    "trustedData": false,
    "ignoredCustomFields": null,
    "currentRole": null,
    "userRoles": null,
    "sourceOfRequest": "USER_DEV.localhost",
    "rootVersionContextID": null,
    "rootTagName": null,
    "directRequest": false,
    "formats": {
      "date.format.long": "dd-MM-yyyy HH:mm:ss XXX"
    },
    "ignoreAlternateFields": true,
    "decodeResult": "DATE_AND_LOB",
    "maxDepthResult": 3,
    "decodeRequest": "DATE_AND_LOB",
    "ignoreCaseHeaderInResponse": true,
    "cacheUsage": "REFRESH",
    "httpResponseCacheUsage": "NONE",
    "defaultLuceneSortClause": null,
    "viewDefinition": null
  },
  "fieldName":"address"
}

getFieldsBySubFieldNameAndTypeCode

A method that retrieves Lucene index field definitions for complex fields whose representation is defined as a dependent case. We narrow the result to the type with the given code, in which this field occurs. The list of complex fields can be retrieved using the getFieldsByTypeCodesAndCategory(POST) method, setting the request arguments "typeCodes": ["type_code"], "category": "Case" and "complexity": "SUBCASE" (where type_code is the type code of the case object that interests us).

Note

There may be many field definitions with the same name represented by a different complex type in the system. Example: In the case type definition with the code Employee there may be a field address, the definition of which contains the fields: street, postCode, city. In another case type definition, with a different code, e.g. Company, the field named address contains the fields: mainStreet, postCode, mainCity, country. It is therefore worth using this method to avoid making a mistake when building a query that aims to find a case of the type Employee, and in the search criterion we will use the field address.mainStreet, which corresponds to the type Company.

The method has the following input argument:

Parameter name	Type	Required?	Description	Example value
context	`Context`	Yes	Request context. You can find more about context in the article SOAP/REST service request context.	`{ "appName": "mercury-ws-app", "appVersion": "0.0.1", "userName": "ttesteusz", ... }`
fieldName	`String`	Yes	Field name for which the field list is to be presented. The field must be a composite field representing a child case.	`"address"`
typeCode	`String`	Yes	Case type code for which the field list is to be presented. The field must be a composite field representing a child case.	`"Employee"`

Example of a method request in JSON form for the REST service. Retrieving data about a composite field named address for a case type with the code Employee.

{
  "context": {
    "appName": "mercury-ws-app",
    "appVersion": "1.0",
    "userName": "anonymous",
    "comment": null,
    "maxResults": 10000,
    "queryTimeout": 2147483647,
    "locale": "pl_PL",
    "timeZone": "Europe/Warsaw",
    "userFullName": null,
    "eager4omdBuilder": "true",
    "trustedData": false,
    "ignoredCustomFields": null,
    "currentRole": null,
    "userRoles": null,
    "sourceOfRequest": "USER_DEV.localhost",
    "rootVersionContextID": null,
    "rootTagName": null,
    "directRequest": false,
    "formats": {
      "date.format.long": "dd-MM-yyyy HH:mm:ss XXX"
    },
    "ignoreAlternateFields": true,
    "decodeResult": "DATE_AND_LOB",
    "maxDepthResult": 3,
    "decodeRequest": "DATE_AND_LOB",
    "ignoreCaseHeaderInResponse": true,
    "cacheUsage": "REFRESH",
    "httpResponseCacheUsage": "NONE",
    "defaultLuceneSortClause": null,
    "viewDefinition": null
  },
  "fieldName":"address",
  "typeCode":"Employee"
}

Response parameters of methods for retrieving data about complex fields

In response, we will receive an object with the following structure:

Parameter	Description	Example value
errorCode	Error code. When the operation is successful, it takes the value `null`. Information about the data contained in the value of this parameter can be obtained by reading the article What does the value of the "errorCode" field mean?	`null`
errorMessage	Error message. When the operation is successful, it takes the value `null`. See also the article What does the value of the "errorCode" field mean?	`null`
map	Map, whose key is the name representing the field category. The map value is represented by a list object IndexFieldCategory with a list of fields associated with a given category. The map may be empty if there is no case type defined in the system with the given type code.	`{ "category": "Case", "fields": [...] }`

Example of response of methods of methods for retrieving data about complex fields

Example of response of the getFieldsBySubFieldNameAndTypeCode(POST) method to a request to retrieve complex fields for the address field and case type with the code Employee

Page under construction

The page is under construction and does not contain all the information yet. Please be patient. Currently, the problem #180 Problem with some methods in the CaseIndexerFieldsManagerAction service has been reported. The example will be supplemented after the problem is solved.

REST service response example
SOAP service response example

soapui_getFieldsBySubFieldNameAndTypeCode

Getting field statistics

Use case

Field statistics can be useful when creating query optimization mechanisms that are sent to the system.

getFieldsStatisticsByFieldName

The method retrieves statistics for a given field and optionally for its value. The method has the following input argument:

Parameter name	Type	Required?	Description	Example value
context	`Context`	Yes	Request context. You can find more about context in the article SOAP/REST service request context.	`{ "appName": "mercury-ws-app", "appVersion": "0.0.1", "userName": "ttesteusz", ... }`
fieldName	`String`	Yes	Field name for which the list of fields is to be presented.	`"address"`
fieldValue	`String`	No	Field value (term) - field statistics will be limited to the value stored in the field. If we do not provide a value, the default value `` will be used, which represents data indicating that all fields are to be taken. ⚠️ Field value statistics can only be calculated for non-numeric* fields. For numeric (numeric) fields, the value provided will be ignored and general field statistics will be provided.**	`"*"`

Example of a JSON method request for the REST service. Getting statistics for the mrc_typeCodeName field.

{
  "context": {
    "appName": "mercury-ws-app",
    "appVersion": "1.0",
    "userName": "anonymous",
    "comment": null,
    "maxResults": 10000,
    "queryTimeout": 2147483647,
    "locale": "pl_PL",
    "timeZone": "Europe/Warsaw",
    "userFullName": null,
    "eager4omdBuilder": "true",
    "trustedData": false,
    "ignoredCustomFields": null,
    "currentRole": null,
    "userRoles": null,
    "sourceOfRequest": "USER_DEV.localhost",
    "rootVersionContextID": null,
    "rootTagName": null,
    "directRequest": false,
    "formats": {
      "date.format.long": "dd-MM-yyyy HH:mm:ss XXX"
    },
    "ignoreAlternateFields": true,
    "decodeResult": "DATE_AND_LOB",
    "maxDepthResult": 3,
    "decodeRequest": "DATE_AND_LOB",
    "ignoreCaseHeaderInResponse": true,
    "cacheUsage": "REFRESH",
    "httpResponseCacheUsage": "NONE",
    "defaultLuceneSortClause": null,
    "viewDefinition": null
  },
  "fieldName": "mrc_typeCodeName",
  "fieldValue": "geoaddressregister"
}

Response parameters of field statistics methods

In response, we will receive an object with the following structure:

XML Field	JSON Field	Description	Example value
errorCode	errorCode	Error code. When the operation is successful, it takes the value `null`. Information about the data contained in the value of this parameter can be obtained by reading the article What does the value of the "errorCode" field mean?	`null`
errorMessage	errorMessage	Error message. When the operation is successful, it takes the value `null`. See also the article What does the value of the "errorCode" field mean?	`null`
item	bag	IndexFieldStatistics represents an object with field statistics data.	`[{ "fieldName": "mrc_typeCodeName", "currentTerm": "geoaddressregister", "serachType": "StringField", "docCount": 1060843, "maxValue": "zpitriodatenegotiation", "minValue": "0", "sumDocFreq": 45402, "sumTotalDocFreq": -1}]`

IndexFieldStatistics


Layers used	Business
Type	Business Object
Java Interface	Serializable
Java Implementation	`pro.ibpm.mercury.lucene.indexers.api.IndexFieldStatistics`
DTO implementation	`pro.ibpm.mercury.lucene.indexers.api.IndexFieldStatistics`
XML definition	hgdb-lucene-indexers-3.0.xsd

Search result element. Its task is to send Lucene index field statistics data.

XML field	JSON field	Description	Type	Value example
fieldName	fieldName	The actual name of the Lucene index field under which the value is stored. This name is not visible to the Mercury DB (HgDB) API and cannot be used to build queries. These names are used implicitly by the query parser and query executor implemented in HgDB. These names can be used in external tools that allow for direct analysis of the index content, such as Luke. These names have suffixes in relation to the names of the fields used in the queries. All this is to support different types of fields (alternative field types) with the same names. The following suffixes are used: `_S` - a field supporting the `StringField` search type `_N` - a field supporting numeric search types and `DateField` `_T` - a field supporting the `TextField` search type	`String`	`description`
currentTerm	currentTerm	Current term (search value) based on which the field statistics were calculated. If the field does not accept any value, or the character ``, the statistics will apply to all expressions indexed in the field. ⚠️ The field does not accept any value for numeric fields, for which we can calculate only general statistics.*	`String`	Example: `word`
serachType	serachType	The type of search in the Lucene index.	`String`	See the description in Lucene index field types.
docCount	docCount	Returns the number of documents that have at least one value for the given index field, or `-1` if this metric is not stored by index. Example for the document field `description` in the Lucene index, there are the following entries: `doc[1].description` = "This is a word you cannot say." `doc[2].description` = "Then I will remain silent." `doc[3].description` = "Although this word... it is tempting to say this word. This one word is XXXXXX." `doc[4].description` = "This is the end." `doc[5].description` = "This is the end. There is nothing left." For the above example and the term `word`, the value of the statistic will be the number of documents with the given, non-empty, `description` field i.e. 5. For all terms it will also be the number 5. ⚠️ Note that the statistics unfortunately do not include deleted documents.	`Long`	`100`
maxValue	maxValue	The maximum value the field accepts. 🛈 Use case: This value can be used to analyze whether it is worth executing a query. Since the query criterion entered by the user/client does not meet the maximum value of the field, is greater than the given value, then the search can be abandoned and an empty result returned.	`String`	The field takes the form of `String` representing all data types, including numeric.
minValue	minValue	The minimum value the field accepts. 🛈 Use case: This value can be used to analyze whether it is worth executing a query. If the query criterion provided by the user/client does not meet the maximum value of the field, is greater than the given value, then the search can be abandoned and an empty result can be returned.	`String`	The field takes the form `String` representing all data types including numeric.
sumDocFreq	sumDocFreq	Returns the number of documents that contain the current term (search value) for this field, or `-1` if this metric is not stored by the index. Example for the document field `description` in the Lucene index, there are the following entries: `doc[1].description` ="This is a word that you cannot say." `doc[2].description` ="Then I will remain silent." `doc[3].description` ="Although this word... it is tempting to say this word. This one word is XXXXXX." `doc[4].description` ="This is the end." `doc[5].description` ="This is the end. There is nothing left." For the above example and the term `word`, the value of the statistic will be 2. For all terms, this will be number of documents 5. ⚠️ Please note that the statistics unfortunately do not include deleted documents.	`Long`	`100`
sumTotalDocFreq	sumTotalDocFreq	Returns the total number of occurrences of this term (the search value) across all documents (the sum of the freq() for each document containing this term) for this field, or `-1` if this metric is not stored by the index. Example for the document field description in the Lucene index, there are the following entries: `doc[1].description` ="This is a word that you cannot say." `doc[2].description` ="Then I will remain silent." `doc[3].description` ="Although this word... it is tempting to say this word. This one word is XXXXXX." `doc[4].description` ="This is the end." `doc[5].description` ="This is the end. There is nothing left." For the above example and the term `word`, the value statistics will be 4. For all terms it will be the sum of all expressions longer than 2 characters, i.e. 33. ⚠️ Note that statistics unfortunately do not include deleted documents.	`Long`	`33`

Example of an IndexFieldStatistics object in JSON
{
  "fieldName": "advanceAmountSum_N",
  "currentTerm": "*",
  "serachType": null,
  "docCount": 57,
  "maxValue": "471819,45",
  "minValue": "0",
  "sumDocFreq": 57,
  "sumTotalDocFreq": 57
}

Number format

For numeric search type fields, the values of the maxValue and minValue fields in string form represent the numeric value. Remember that you can control the number format by defining the context object parameters in the request (see the description of SOAP/REST service request context).

image2022-6-20_22-36-34

Example of response of methods of getting field statistics

Example of response of method getFieldsStatisticsByFieldName(POST) to request of getting field statistics mrc_typeCodeName.

REST service response example
SOAP service response example

{
   "errorCode": null,
   "errorMessage": null,
   "bag": [{
      "fieldName": "mrc_typeCodeName",
      "currentTerm": "geoaddressregister",
      "serachType": "StringField",
      "docCount": 1054531,
      "maxValue": "zpitriodatenegotiation",
      "minValue": "bpmbpdinstance",
      "sumDocFreq": 45402,
      "sumTotalDocFreq": -1
   }]
}

<return>
  <errorCode/>
  <errorMessage/>
  <item xmlns="http://index.lucene.hgdb.io/statisticsFields"
      xsi:schemaLocation="http://index.lucene.hgdb.io/statisticsFields https://hgdb.org/xsd/lucene/hgdb-lucene-indexers-3.0.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <fieldName>mrc_typeCodeName</fieldName>
      <currentTerm>geoaddressregister</currentTerm>
      <serachType>StringField</serachType>
      <docCount>1054531</docCount>
      <maxValue>zpitriodatenegotiation</maxValue>
      <minValue>bpmbpdinstance</minValue>
      <sumDocFreq>45402</sumDocFreq>
      <sumTotalDocFreq>-1</sumTotalDocFreq>
  </item>
</return>

Description of the meaning of the individual values of the complexity parameter:
- SIMPLE - send only simple fields.
- SUBCASE - send only complex fields, represented by the subcase definition.
- ALL - send all fields, regardless of their complexity.
↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷

Get field type data​

getSearchTypes​

getCategories​

Retrieving field data by type​

getFieldsBySearchType​

Response parameters of methods for retrieving field data by type​

IndexFieldSearchType​

IndexField​

Example of response of methods for retrieving data about fields by type​

Retrieving data about fields divided into field categories​

getFields​

getFieldsByCategory​

getFieldsByTypeCodes​

getFieldsByTypeCodesAndCategory​

getFieldsByTypeIds​

getFieldsByTypeIdsAndCategory​

Response parameters of methods for retrieving data about fields divided into field categories​

IndexFieldCategory​

Example of response of methods of methods for retrieving data about fields by field category​

Retrieving data about complex fields​

getFieldsBySubFieldName​

getFieldsBySubFieldNameAndTypeCode​

Response parameters of methods for retrieving data about complex fields​

Example of response of methods of methods for retrieving data about complex fields​

Getting field statistics​

getFieldsStatisticsByFieldName​

Response parameters of field statistics methods​

IndexFieldStatistics​

Example of response of methods of getting field statistics​

Footnotes​

Get field type data

getSearchTypes

getCategories

Retrieving field data by type

getFieldsBySearchType

Response parameters of methods for retrieving field data by type

IndexFieldSearchType

IndexField

Example of response of methods for retrieving data about fields by type

Retrieving data about fields divided into field categories

getFields

getFieldsByCategory

getFieldsByTypeCodes

getFieldsByTypeCodesAndCategory

getFieldsByTypeIds

getFieldsByTypeIdsAndCategory

Response parameters of methods for retrieving data about fields divided into field categories

IndexFieldCategory

Example of response of methods of methods for retrieving data about fields by field category

Retrieving data about complex fields

getFieldsBySubFieldName

getFieldsBySubFieldNameAndTypeCode

Response parameters of methods for retrieving data about complex fields

Example of response of methods of methods for retrieving data about complex fields

Getting field statistics

getFieldsStatisticsByFieldName

Response parameters of field statistics methods

IndexFieldStatistics

Example of response of methods of getting field statistics

Footnotes