Facade for the reporting and metrics subsystem, covering saved queries, tables, metrics and the organisation and supplier filters used to scope a report to the current user. Delegates most of its work to QueryService and ApplicationManager. Registered in the templating data model and available to server-side JS as "queryManager", so most of its exported methods form the API a report template or JS controller uses to run a query, calculate a metric or resolve the currently selected organisations.

Group: Managers

---

Properties

---

Methods

getQueryParameters() · toReportBean(DirectoryNode rootDir, FileNode fn) · saveMetrics(List<Metric> metrics) · saveMetric(Metric m) · newMetricBuilder(String id, String metricTypeId) · deleteMetric(String metricId) · newCalcContext() · metric(String name) · calcMetric(Metric m) · calcMetric(Metric m, CalcContext cc) · calcMetric(Metric m, Date defaultStartDate, Date defaultEndDate, CalcContext calcContext) · calcMetric(Metric m, BaseEntity entity, Date defaultStartDate, Date defaultEndDate, CalcContext calcContext) · metricType(String id) · findApplicableMetrics(NamedObject source) · newRowsResult() · newRowsResult(List<String> headers) · getCommonStartDate() · getCommonFinishDate() · getLagStartDate() · getLagFinishDate() · getMetrics() · getMetricTypes() · getTables() · getTable(String name) · getQueriesConfig() · getQueries() · getLookupTables() · calcInterval(Date startDate, Date endDate) · queryParams() · queryParams(Date startDate, Date endDate) · queryParams(Date startDate, Date endDate, Map extraParams) · runQuery(String queryName) · runQuery(String queryName, Integer from, Integer pageSize) · runQuery(String queryName, Map<String,String> params) · runQuery(String queryName, Integer from, Integer pageSize, Map<String,String> params) · getAvailableSuppliers() · availableSuppliers(Profile user) · getSelectedSupplierIds() · selectedSupplierIds(Profile user) · getSelectedOrgIds() · selectedOrgIds(Profile user) · selectedOrgIDsStr() · getAvailableOrgIds() · availableOrgIds(Profile user) · getAvailableOrgs() · getAvailableOrgIds(Group group) · getAvailableOrgIds(List<Group> groups) · getSelectedOrgs() · getCurrentTeamOrg() · teamOrg(Profile user) · selectedOrgHasType(String orgType) · preProcessQuery(String json) · preProcessQuery2(String json) · preProcessQuery2(String json, Map<String,Object> params) · getParams() · saveTable(KCriteriaTable t) · getOrCreateReportParams() · getOrCreateReportParams(Function<ReportParams,T> callback) · enqueueQueryTableExport(String queryTableName, Date start, Date finish, List<Long> orgIds, Map<String,String> params) · exportTaskName(String queryTableName) · createDefaultQuery(String esFieldName, String operator, Object value) · createDefaultQuery(String esFieldName, String operator, Object value, boolean reverseRange) · findFieldOperatorsByType(String fieldType) · findActualFieldType(String fieldType) · processRows(String indexType, List<String> fields, List rows) · processRows(String indexType, List<String> fields, boolean defaultFieldsFormatting, List rows)

getQueryParameters()

Returns: List<QueryParameter>

The static and query-specific parameters that can be substituted into a query definition, such as startDate, endDate and the currently selected organisations. Sourced from the query service's static parameter list.

toReportBean(DirectoryNode rootDir, FileNode fn)

Returns: ReportBean

Reads a report definition file and converts it into a ReportBean describing its name, title and content. Wraps the underlying IOException as a RuntimeException.

saveMetrics(List<Metric> metrics)

Returns: void

Persists a batch of metric definitions. Does nothing, and logs a message, if the list is null or empty.

saveMetric(Metric m)

Returns: void

Persists a single metric definition. Does nothing, and logs a message, if the metric is null.

newMetricBuilder(String id, String metricTypeId)

Returns: MetricBuilder

Starts a new fluent builder for a metric of the given type, identified by the given id.

deleteMetric(String metricId)

Returns: void

Deletes the metric definition with the given id.

newCalcContext()

Returns: CalcContext

Creates a new, empty calculation context used to track recursion depth while calculating metrics.

metric(String name)

Returns: Metric

Looks up a metric definition by its name.

calcMetric(Metric m)

Returns: BigDecimal

Calculates the value of a metric using the common date range and no specific entity. This is an expensive operation, typically involving a search query against the underlying data.

calcMetric(Metric m, CalcContext cc)

Returns: BigDecimal

Calculates the value of a metric using the common date range and no specific entity. This is an expensive operation, typically involving a search query against the underlying data.

calcMetric(Metric m, Date defaultStartDate, Date defaultEndDate, CalcContext calcContext)

Returns: BigDecimal

Calculates the value of a metric for the given date range. The metric's own date mode may override the given dates, for example to use a constant range or the previous period instead. This is an expensive operation, typically involving a search query against the underlying data.

calcMetric(Metric m, BaseEntity entity, Date defaultStartDate, Date defaultEndDate, CalcContext calcContext)

Returns: BigDecimal

Calculates the value of a metric for a specific entity and date range. The metric's own date mode may override the given dates, for example to use a constant range or the previous period instead. This is an expensive operation, typically involving a search query against the underlying data.

metricType(String id)

Returns: MetricType

Looks up a registered metric type by its id.

findApplicableMetrics(NamedObject source)

Returns: List<Metric>

Finds the metrics applicable to a given source object, such as a reward or some other item which metrics can apply to. Looks the source up by its class name and object name in the configured queries.

newRowsResult()

Returns: RowsResult

Creates an empty rows result with no headers, useful as a default when a table query yields no data.

newRowsResult(List<String> headers)

Returns: RowsResult

Creates an empty rows result with the given column headers, useful as a default when a table query yields no data but the headers still need to be rendered.

getCommonStartDate()

Returns: Date

The start of the common reporting date range for the current request, typically resolved from a request parameter or cookie.

getCommonFinishDate()

Returns: Date

The end of the common reporting date range for the current request, typically resolved from a request parameter or cookie.

getLagStartDate()

Returns: Date

The common start date shifted back by the configured reporting lag, used where a metric or query should be evaluated on data that has had time to settle.

getLagFinishDate()

Returns: Date

The common finish date shifted back by the configured reporting lag, used where a metric or query should be evaluated on data that has had time to settle.

getMetrics()

Returns: List<Metric>

All configured metric definitions.

getMetricTypes()

Returns: List<MetricType>

All metric types registered by installed applications, which define the calculation behaviour available to metric definitions.

getTables()

Returns: List<Table>

All tables available for reporting: the configured tables, tables contributed by installed query applications, and a results table (plus one per aggregation) generated for each saved query that has fields or aggregations chosen. This is an expensive operation since it assembles tables from several sources on each call.

getTable(String name)

Returns: Table

Finds a table, by id, from the combined list returned by getTables. Logs a warning and returns null if no table with that id exists.

getQueriesConfig()

Returns: Queries

The raw queries configuration for the current account, including its tables, saved queries and lookup tables.

getQueries()

Returns: List<QueryBean>

The saved queries available for reporting, combining the configured queries with any contributed by installed query applications, sorted by name.

getLookupTables()

Returns: List<LookupTableBean>

The lookup tables configured for the current account, used to enrich or translate values in reports.

calcInterval(Date startDate, Date endDate)

Returns: String

Returns an appropriate date histogram aggregation interval (for example "day" or "month") for the given date range, chosen so the number of buckets stays reasonable.

queryParams()

Returns: Map<String,Object>

The current query parameters resolved from the current HTTP request, such as the selected date range and organisations.

queryParams(Date startDate, Date endDate)

Returns: Map<String,Object>

The current query parameters resolved from the current HTTP request, overriding the resolved date range with the given start and end dates.

queryParams(Date startDate, Date endDate, Map extraParams)

Returns: Map<String,Object>

The current query parameters resolved from the current HTTP request, overriding the resolved date range with the given start and end dates, and merging in the given extra parameters.

runQuery(String queryName)

Returns: KSearchResponse

Runs a saved query by name, using the query parameters resolved from the current HTTP request, with no paging applied. This is an expensive operation as it executes a search against the underlying index.

runQuery(String queryName, Integer from, Integer pageSize)

Returns: KSearchResponse

Runs a saved query by name, using the query parameters resolved from the current HTTP request, with the given paging. This is an expensive operation as it executes a search against the underlying index.

runQuery(String queryName, Map<String,String> params)

Returns: KSearchResponse

Runs a saved query by name, with no paging applied. The given parameters override the query parameters resolved from the current HTTP request. This is an expensive operation as it executes a search against the underlying index.

runQuery(String queryName, Integer from, Integer pageSize, Map<String,String> params)

Returns: KSearchResponse

Runs a saved query by name, with the given paging applied. The given parameters are added to the query parameters resolved from the current HTTP request, without overriding an already-resolved value. This is an expensive operation as it executes a search against the underlying index.

getAvailableSuppliers()

Returns: List<Organisation>

Finds the supplier organisations available to the current user, based on the SupplierFilter role.

availableSuppliers(Profile user)

Returns: List<Organisation>

Finds the supplier organisations available to the given user, based on the SupplierFilter role. This is an expensive operation, involving a lookup of the user's supplier organisation ids.

getSelectedSupplierIds()

Returns: List<Long>

The ids of the supplier organisations currently selected by the current user, sorted numerically.

selectedSupplierIds(Profile user)

Returns: List<Long>

The ids of the supplier organisations currently selected by the given user, sorted numerically. Selection is scoped to the supplier organisations available to the user via the SupplierFilter role.

getSelectedOrgIds()

Returns: List<Long>

The ids of the organisations currently selected by the current user for reporting, sorted numerically.

selectedOrgIds(Profile user)

Returns: List<Long>

The ids of the organisations currently selected by the given user for reporting, sorted numerically. Selection is scoped to the organisations the user has reporting access to.

selectedOrgIDsStr()

Returns: String

The raw, unparsed cookie value holding the selected organisation id(s), if any.

getAvailableOrgIds()

Returns: List<Long>

The internal ids of the organisations the current user has the ReportingAccess role on. This list is not expanded, so it does not include child organisations of those.

availableOrgIds(Profile user)

Returns: List<Long>

Returns the org IDs which the given user has reporting access on

getAvailableOrgs()

Returns: List<Organisation>

The organisations directly available to the current user, ie where the user has the ReportingAccess role on that org, sorted by formatted name. This is a non-expanded list, so it does not include child organisations. This is an expensive operation as it resolves each organisation id individually.

getAvailableOrgIds(Group group)

Returns: List<Long>

The internal ids of the organisations the current user has the ReportingAccess role on, restricted to the given group. This list is not expanded, so it does not include child organisations of those.

getAvailableOrgIds(List<Group> groups)

Returns: List<Long>

The internal ids of the organisations the current user has the ReportingAccess role on, restricted to the given groups. This list is not expanded, so it does not include child organisations of those.

getSelectedOrgs()

Returns: List<OrgData>

The organisation(s) currently selected by the current user, resolved as child organisations of the tenant's root organisation, excluding any that have been deleted.

getCurrentTeamOrg()

Returns: Organisation

The single organisation, of those currently selected by the current user, that should represent the user's team. Where multiple organisations are selected, the first resolved one is returned.

teamOrg(Profile user)

Returns: Organisation

The single organisation, of those currently selected by the given user, that should represent that user's team. Where multiple organisations are selected, the first resolved one is returned.

selectedOrgHasType(String orgType)

Returns: boolean

Checks whether any of the organisations currently selected by the current user has the given organisation type.

preProcessQuery(String json)

Returns: String

Substitutes query parameter values into a raw query JSON string, resolved from the current HTTP request. Superseded by preProcessQuery2, which should be used instead.

preProcessQuery2(String json)

Returns: String

Substitutes query parameter values, resolved from the current HTTP request, into a raw query JSON string. This improves on preProcessQuery and should be used instead: it handles simple parameter substitution and also handles parameters that resolve to lists.

preProcessQuery2(String json, Map<String,Object> params)

Returns: String

Substitutes the given query parameter values into a raw query JSON string. Handles simple parameter substitution and also handles parameters that resolve to lists.

getParams()

Returns: Map<String,Object>

The report query parameters resolved from the current HTTP request.

saveTable(KCriteriaTable t)

Returns: void

Persists a criteria table definition. Wraps the underlying IOException as a RuntimeException.

getOrCreateReportParams()

Returns: ReportParams

Returns the current thread-bound report parameters, creating and binding an empty set if none exist yet.

getOrCreateReportParams(Function<ReportParams,T> callback)

Returns: T

Runs the given callback with the current thread-bound report parameters, creating and binding an empty set first if none exist yet. If this call created the params, they are removed again once the callback returns.

enqueueQueryTableExport(String queryTableName, Date start, Date finish, List<Long> orgIds, Map<String,String> params)

Returns: long

Creates a QueryTableExporter task and submits it to the AsyncJobManager for background execution. Normally the date range and organisation ids should be resolved via this class's own methods; the params map may be provided in addition where the query table uses extended parameters.

exportTaskName(String queryTableName)

Returns: String

Builds the async job task name used to track a query table export, so its progress can be looked up later.

createDefaultQuery(String esFieldName, String operator, Object value)

Returns: QueryBuilder

Builds a default search query clause for a field, operator and value, using the standard operator handling for the field's type.

createDefaultQuery(String esFieldName, String operator, Object value, boolean reverseRange)

Returns: QueryBuilder

Builds a default search query clause for a field, operator and value, using the standard operator handling for the field's type, with the option to reverse the direction of a range comparison.

findFieldOperatorsByType(String fieldType)

Returns: List<String>

Finds the operators available for a field of the given type, for example the comparisons a date field supports versus a keyword field.

findActualFieldType(String fieldType)

Returns: String

Resolves the actual field type the query builder should use for a given declared field type.

processRows(String indexType, List<String> fields, List rows)

Returns: List<ProcessedHit>

Converts a list of raw search result rows into ProcessedHit objects, resolving any path-style fields (for example "assignedToProfileId/firstName") by joining to the related index and enriching the row with default field formatting. This is an expensive operation as it may execute additional search queries to fetch the joined data.

processRows(String indexType, List<String> fields, boolean defaultFieldsFormatting, List rows)

Returns: List<ProcessedHit>

Converts a list of raw search result rows into ProcessedHit objects, resolving any path-style fields (for example "assignedToProfileId/firstName") by joining to the related index. This is an expensive operation as it may execute additional search queries to fetch the joined data.