To get full access to the Kademi Hub existing customers can login here, or new customers can register here.
Persists and runs a tenant's saved elastic search queries, reports, lookup tables and calculated metrics. Stores each of these as JSON or XML files in a per-account "queries" repository, and builds and caches a parsed Queries snapshot for each repository branch head. Substitutes reporting parameters, such as the date range, the current user, and selected or reporting organisations, into a query's JSON before running it against elastic search, and calculates Metric values with an optional pre-calculated cache. Most of this functionality is reached from server-side JavaScript and Velocity templates through the QueryManager facade rather than being called directly.
Group: Queries
Properties
| Property | Returns | Description |
|---|---|---|
| lag | Lag | The historical comparison period used when calculating a lag (prior period) date range for a query, currently always a year. Used by params to derive lagStartDate and lagEndDate from the selected date range. |
| metrics | List<Metric> | All calculated metrics configured for the current tenant organisation, as loaded from the account's query configuration. |
| queries | Queries | The parsed and cached representation of the current tenant's query configuration: saved queries, reports, lookup tables, metrics and the JavaScript-defined rule types used for points, recognition and voucher expiry. Loaded from the account's "queries" repository and cached by the repository branch's head hash, so repeated calls within the same branch state are cheap. The intention is for this to grow into a general account settings object, holding other account-level configuration such as content types and points rules. |
| queryList | List<QueryBean> | All saved query definitions (elastic search queries and any associated query-builder configuration) for the current tenant organisation, loaded from the "queries" repository. |
| queryParameters | List<QueryParameter> | The static set of query substitution parameters available to every query, such as startDate, userId and selectedOrgs, each carrying a name, type and description used to document and validate query definitions. Built once in the constructor and shared across all accounts. |
| queryRepository | Repository | The account's "queries" repository, which stores saved query, report, lookup table and metric definitions as files. |
| reportList | List<ReportBean> | All saved report definitions for the current tenant organisation, each pairing a title and HTML content with the query table it renders. |
| xstream | XStream |
Methods
getQueryParameters() · getQueryRepository() · getQueries() · saveTable(KCriteriaTable t) · deleteMetric(String metricId) · saveMetric(Metric m) · saveMetrics(List<Metric> metrics) · getQueryList() · getReportList() · createReport(String name, String title, String description, String tableName) · runQuery(QueryBean queryBean, Map<String,Object> params) · runQuery(QueryBean queryBean, Integer from, Integer size, Map<String,Object> params) · preProcessQueryWithParams(String json, Map<String,Object> params) · preProcessQuery(String json, Map<String,Object> params) · getQueryFieldNames(QueryBean queryBean) · params(Request request) · params(Request request, Date startDate, Date endDate, Map<String,Object> params) · findSupplierOrgIds(Profile currentUser) · findSupplierOrgIdsNoCache(Profile currentUser) · findReportingOrgIds(Profile currentUser) · findReportingOrgIdsNoCache(Profile currentUser) · findReportingOrgIds(Profile currentUser, Group group) · findReportingOrgIds(Profile currentUser, List<Group> groups) · findSelectedOrgIds(List<Long> directOrgs, Organisation adminOrg, String cookieName) · calcLagDate(Date dt, Lag lag) · toReportBean(DirectoryNode rootDir, FileNode fn) · getMetrics() · metric(String name) · newCalcContext() · calcMetric(Date startDate, Date endDate, Metric m) · calcMetric(Date startDate, Date endDate, Metric m, CalcContext calcContext) · calcMetric(BaseEntity sourceEntity, Date startDate, Date endDate, Metric m, CalcContext calcContext) · getLag() · lookup(String lookupTableName, BaseEntity participant, Map<String,Object> vars)
getQueryParameters()
Returns: List<QueryParameter>
The static set of query substitution parameters available to every query, such as startDate, userId and selectedOrgs, each carrying a name, type and description used to document and validate query definitions. Built once in the constructor and shared across all accounts.
getQueryRepository()
Returns: Repository
The account's "queries" repository, which stores saved query, report, lookup table and metric definitions as files.
getQueries()
Returns: Queries
The parsed and cached representation of the current tenant's query configuration: saved queries, reports, lookup tables, metrics and the JavaScript-defined rule types used for points, recognition and voucher expiry. Loaded from the account's "queries" repository and cached by the repository branch's head hash, so repeated calls within the same branch state are cheap. The intention is for this to grow into a general account settings object, holding other account-level configuration such as content types and points rules.
saveTable(KCriteriaTable t)
Returns: void
Adds or replaces a table definition in the tenant's controllers.xml configuration, keyed by the table's ID, and writes the updated configuration back to the queries repository.
| Parameter | Description |
|---|---|
t | the table definition to save |
deleteMetric(String metricId)
Returns: void
Removes a metric definition from the tenant's controllers.xml configuration by ID, and writes the updated configuration back to the queries repository.
| Parameter | Description |
|---|---|
metricId | the ID of the metric to remove |
saveMetric(Metric m)
Returns: void
Adds or replaces a single metric definition in the tenant's controllers.xml configuration, keyed by the metric's ID, creating the queries repository first if it does not yet exist.
| Parameter | Description |
|---|---|
m | the metric definition to save |
saveMetrics(List<Metric> metrics)
Returns: void
Adds or replaces several metric definitions in the tenant's controllers.xml configuration in a single write, creating the queries repository first if it does not yet exist.
| Parameter | Description |
|---|---|
metrics | the metric definitions to save |
getQueryList()
Returns: List<QueryBean>
All saved query definitions (elastic search queries and any associated query-builder configuration) for the current tenant organisation, loaded from the "queries" repository.
getReportList()
Returns: List<ReportBean>
All saved report definitions for the current tenant organisation, each pairing a title and HTML content with the query table it renders.
createReport(String name, String title, String description, String tableName)
Returns: void
Creates a new saved report: a JSON descriptor plus a default HTML page that renders the given table, saved as two files in the tenant's "queries" repository. Creates the repository first if it does not yet exist.
| Parameter | Description |
|---|---|
name | the base file name to save the report and its content under |
title | the display title of the report |
description | a short description of the report's purpose |
tableName | the name of the query table the generated report page renders |
runQuery(QueryBean queryBean, Map<String,Object> params)
Returns: KSearchResponse
Runs the given query against elastic search after substituting reporting parameters into its JSON. If the params map contains "from" or "size" entries they are added to the executed query as paging arguments.
| Parameter | Description |
|---|---|
queryBean | the query to run, either a raw JSON query or a query-builder configuration |
params | the substitution parameters to apply, typically built by calling params(Request) |
runQuery(QueryBean queryBean, Integer from, Integer size, Map<String,Object> params)
Returns: KSearchResponse
Runs the given query against elastic search after substituting reporting parameters into its JSON, explicitly overriding the paging offset and page size rather than relying on "from"/"size" entries in params.
| Parameter | Description |
|---|---|
queryBean | the query to run, either a raw JSON query or a query-builder configuration |
from | the zero-based offset of the first result to return, or null to leave the query's own value |
size | the maximum number of results to return, or null to leave the query's own value |
params | the substitution parameters to apply, typically built by calling params(Request) |
preProcessQueryWithParams(String json, Map<String,Object> params)
Returns: String
Applies the full two-phase parameter substitution used before running a query: date, numeric and known string parameters first, then a generic pass that substitutes any remaining "$paramName" tokens found in params.
| Parameter | Description |
|---|---|
json | the query JSON (or query-builder JSON) containing substitution tokens |
params | the substitution parameters to apply, typically built by calling params(Request) |
preProcessQuery(String json, Map<String,Object> params)
Returns: String
Substitutes the well-known reporting parameters, such as date ranges, the current profile and organisation scoping, and the date aggregation interval, into a query's JSON, then evaluates any mvel template expressions the query contains. Does not substitute arbitrary "$paramName" tokens for other keys in params; use preProcessQueryWithParams for that.
| Parameter | Description |
|---|---|
json | the query JSON (or query-builder JSON) containing substitution tokens |
params | the substitution parameters to apply, typically built by calling params(Request) |
getQueryFieldNames(QueryBean queryBean)
Returns: List<String>
Extracts the field names selected by a query, read from its JSON "fields" or "stored_fields" element, without running the query.
| Parameter | Description |
|---|---|
queryBean | the query to inspect |
params(Request request)
Returns: Map<String,Object>
Builds the standard set of reporting parameters for the current request, using the common date range read from cookies or request params and no additional overrides. Equivalent to calling the four-argument overload with the common start and finish dates and no extra params.
| Parameter | Description |
|---|---|
request | the current request, used to read cookies and request parameters, or null if not running within a request |
params(Request request, Date startDate, Date endDate, Map<String,Object> params)
Returns: Map<String,Object>
Builds the full set of reporting parameters used to substitute into a query: the given date range and its lag (comparison) period, the current profile's identifying and organisation-scoping values, the current timezone, and any values found in the request's parameters and cookies. User-specific values are expensive to compute, so they are cached per profile within the request (or the current RequestContext when there is no request).
| Parameter | Description |
|---|---|
request | the current request, used to read cookies and request parameters, or null if not running within a request |
startDate | the start of the reporting date range |
endDate | the end (exclusive) of the reporting date range |
params | extra parameters to seed the result with before request params and cookies are added, or null |
findSupplierOrgIds(Profile currentUser)
Returns: List<Long>
The organisations the given user is permitted to view supplier data for, cached in the current root folder's attributes for the remainder of the request since it may be called many times per request.
| Parameter | Description |
|---|---|
currentUser | the profile to find applicable supplier organisations for |
findSupplierOrgIdsNoCache(Profile currentUser)
Returns: List<Long>
Finds the organisations the given user is permitted to view supplier data for, without using the per-request cache that findSupplierOrgIds maintains.
| Parameter | Description |
|---|---|
currentUser | the profile to find applicable supplier organisations for |
findReportingOrgIds(Profile currentUser)
Returns: List<Long>
The organisations the given user has reporting access to, either directly via the ReportingAccess role or as an administrator of the root organisation. Cached in the current root folder's attributes for the remainder of the request since it may be called many times per request.
| Parameter | Description |
|---|---|
currentUser | the profile to find reporting-accessible organisations for |
findReportingOrgIdsNoCache(Profile currentUser)
Returns: List<Long>
Finds the organisations the given user has reporting access to, without using the per-request cache that findReportingOrgIds maintains. Falls back to the root organisation if the user is an account administrator with no explicit ReportingAccess grants.
| Parameter | Description |
|---|---|
currentUser | the profile to find reporting-accessible organisations for |
findReportingOrgIds(Profile currentUser, Group group)
Returns: List<Long>
The organisations within which the given user has reporting access via membership of the given group, or via any group if group is null.
| Parameter | Description |
|---|---|
currentUser | the profile to find reporting-accessible organisations for |
group | restrict results to reporting-access grants held through this group, or null to allow any group |
findReportingOrgIds(Profile currentUser, List<Group> groups)
Returns: List<Long>
The organisations within which the given user has reporting access via membership of any of the given groups, or via any group if groups is null or empty.
| Parameter | Description |
|---|---|
currentUser | the profile to find reporting-accessible organisations for |
groups | restrict results to reporting-access grants held through one of these groups, or null/empty to allow any group |
findSelectedOrgIds(List<Long> directOrgs, Organisation adminOrg, String cookieName)
Returns: List<Long>
The organisations, from within directOrgs, that the current user has actually selected to view, read from the named cookie and expanded to include matching child organisations when org filter cookies are also set. Falls back to directOrgs unchanged if nothing valid is selected.
| Parameter | Description |
|---|---|
directOrgs | the organisations the user is permitted to view, used both as the fallback and to validate the selection |
adminOrg | the tenant organisation, used when expanding a selection against org filters |
cookieName | the name of the cookie holding the user's selected organisation IDs, such as "selectedOrg" or "supplierOrg" |
calcLagDate(Date dt, Lag lag)
Returns: Date
Shifts a date back by the given lag period to find the equivalent date in the historical comparison period. Only Lag.YEAR currently has an effect; other values leave the date unchanged.
| Parameter | Description |
|---|---|
dt | the date to shift |
lag | the lag period to shift by |
toReportBean(DirectoryNode rootDir, FileNode fn)
Returns: ReportBean
Parses a report's JSON descriptor file into a report bean, reading its HTML content either inline or, if the descriptor references a separate content file, from that file within the same directory.
| Parameter | Description |
|---|---|
rootDir | the directory the report descriptor and its content file live in |
fn | the report descriptor file, ending in .report.json |
getMetrics()
Returns: List<Metric>
All calculated metrics configured for the current tenant organisation, as loaded from the account's query configuration.
metric(String name)
Returns: Metric
Finds a configured metric by ID within the current tenant's query configuration.
| Parameter | Description |
|---|---|
name | the ID of the metric to find |
newCalcContext()
Returns: CalcContext
Creates a fresh calculation context for use with calcMetric, holding no cached attributes from any prior calculation.
calcMetric(Date startDate, Date endDate, Metric m)
Returns: BigDecimal
Calculates a metric's value over the given date range for the entity implied by its entity selection (the current tenant account, current organisation, current profile, or a specifically named org/profile), using a new calculation context.
| Parameter | Description |
|---|---|
startDate | the start of the period to calculate the metric over |
endDate | the end of the period to calculate the metric over |
m | the metric to calculate |
calcMetric(Date startDate, Date endDate, Metric m, CalcContext calcContext)
Returns: BigDecimal
Calculates a metric's value over the given date range for the entity implied by its entity selection, recording intermediate values and settings used during the calculation on the given calculation context.
| Parameter | Description |
|---|---|
startDate | the start of the period to calculate the metric over |
endDate | the end of the period to calculate the metric over |
m | the metric to calculate |
calcContext | the context to calculate within, used for caching control and to record calculation attributes |
calcMetric(BaseEntity sourceEntity, Date startDate, Date endDate, Metric m, CalcContext calcContext)
Returns: BigDecimal
Calculates a metric's value over the given date range, resolving the entity the metric applies to from the metric's entity selection and, where the selection is currentOrg or currentProfile, from sourceEntity.
| Parameter | Description |
|---|---|
sourceEntity | the org or profile currently in scope, used to resolve currentOrg/currentProfile entity selections |
startDate | the start of the period to calculate the metric over |
endDate | the end of the period to calculate the metric over |
m | the metric to calculate |
calcContext | the context to calculate within, used for caching control and to record calculation attributes |
getLag()
Returns: Lag
The historical comparison period used when calculating a lag (prior period) date range for a query, currently always a year. Used by params to derive lagStartDate and lagEndDate from the selected date range.
lookup(String lookupTableName, BaseEntity participant, Map<String,Object> vars)
Returns: MatchRow
Finds the most specific matching row in a named lookup table for the given participant, using the lookup table's own field-to-parameter mapping to derive match values from the participant (and any extra vars) before matching.
| Parameter | Description |
|---|---|
lookupTableName | the name of the lookup table to search |
participant | the entity to derive match parameters from |
vars | extra variables to make available when deriving match parameters, or null |
© 2025 Kademi Ltd