To get full access to the Kademi Hub existing customers can login here, or new customers can register here.
Registers the sales data application, which lets an organisation record recurring or one-off amounts, such as sales figures, against profiles or other entities and group them into named data series. It provides the website and admin folders used to view, edit and upload series and records, drives points allocation and reward calculation from recorded sales, raises funnel trigger events, feeds sales records into search indexing and omni-search, and contributes profile tabs, portlets and menu items for the feature. Registered under the instance id "salesData".
Implements: ChildPageApplication, MenuApplication, BackupableApplication, SearchableApplication, ManageProfileApplication, PortletApplication, ComponentApplication, TemplatingApplication, DependentApplication, JourneyBuilderApplication, QueryApplication, TableUploadApplication, FieldProviderApplication, PromotionMechanicApplication, OmniSearchApplication
Properties
| Property | Returns | Description |
|---|---|---|
| allSalesDataSeries | List<SalesDataSeries> | All sales data series defined for the current organisation, resolved from the current root folder. |
| config | AppConfig | Configuration this application instance was initialised with, including its manifest and repository metadata. |
| dataSeriesAppIndexer | DataSeriesAppIndexer | The search indexer used to index sales data records, one indexer instance per application. |
| instanceId | String | Identifier this application is registered under with the application manager. |
| legacy | boolean | |
| metricTypes | List<MetricType> | The reporting metric types this application contributes, currently just the sum-of-sales-data metric. |
| promotionTypes | List<PromotionMechanicType> | The promotion mechanic types this application contributes, made available only when the installed version of the sales data app is an earlier, legacy version. |
| roles | List<Role> | The roles this application contributes to the platform's permission system: the sales data viewer and sales data editor roles. |
Methods
getInstanceId() · getConfig() · getAllSalesDataSeries() · getAllSalesDataRecords(SalesDataSeries series) · getSalesDataSeries(String name) · getDataSeriesExtraFields(String name) · insertDataPoint(SalesDataSeries series, BigDecimal amount, Date periodFrom, Date periodTo, BaseEntity attributedTo, Profile enteredBy, Date entered) · insertDataPoint(SalesDataSeries series, BigDecimal amount, Date periodFrom, Date periodTo, BaseEntity attributedTo, Profile enteredBy, Date entered, String productSku) · insertDataPoint(SalesDataSeries series, BigDecimal amount, Date periodFrom, Date periodTo, BaseEntity attributedTo, Date entered) · insertOrUpdateDataPoint(SalesDataSeries series, BigDecimal amount, Date periodFrom, Date periodTo, BaseEntity attributedTo, Date entered, Map<String,String> fields) · updateDataPoint(SalesDataRecord r, BigDecimal amount, Date entered) · deleteDataPoint(SalesDataRecord r) · findExistingBySkuAndSalesBy(SalesDataRecord rec) · findExistingBySkuAndSalesBy(SalesDataRecord rec, Date from, Date to) · findDataPoint(SalesDataSeries series, BaseEntity attributedTo, Date from, Date to, Map<String,String> fields) · findDataPoint(SalesDataSeries series, Date from, Date to, Map<String,String> fields) · getRoles() · getPointsAllocationForRecord(long salesDataRecordId) · processPointsAllocation(SalesDataSeries series, Consumer<String> progressCallback) · calculateAllocationPoints(PointsAllocationSource pas, SalesDataRecord r, Formatter f) · getDataSeriesAppIndexer() · dataSeriesHistogram(SalesDataSeries series, Date startDate, Date endDate, String groupBy, String aggregation, Profile forUser) · createSeries(String name, String title, Group salesByGroup) · getPromotionTypes() · getMetricTypes()
getInstanceId()
Returns: String
Identifier this application is registered under with the application manager.
getConfig()
Returns: AppConfig
Configuration this application instance was initialised with, including its manifest and repository metadata.
getAllSalesDataSeries()
Returns: List<SalesDataSeries>
All sales data series defined for the current organisation, resolved from the current root folder.
getAllSalesDataRecords(SalesDataSeries series)
Returns: List<SalesDataRecord>
Loads every record that has been recorded in the given series, regardless of period.
| Parameter | Description |
|---|---|
series | the series to load records for |
getSalesDataSeries(String name)
Returns: SalesDataSeries
Looks up a sales data series belonging to the current organisation by its unique name.
| Parameter | Description |
|---|---|
name | the series' unique name |
getDataSeriesExtraFields(String name)
Returns: List<ExtraField>
The extra, series-specific fields configured for the named sales data series, used to render custom field inputs when entering or editing a record.
| Parameter | Description |
|---|---|
name | the series' unique name |
insertDataPoint(SalesDataSeries series, BigDecimal amount, Date periodFrom, Date periodTo, BaseEntity attributedTo, Profile enteredBy, Date entered)
Returns: SalesDataRecord
Records a new sales data point in the given series, using a session obtained from the current thread. The record is saved immediately and a sales-data-updated funnel event is fired.
| Parameter | Description |
|---|---|
series | the series to add the record to |
amount | the amount recorded for this data point |
periodFrom | the start of the period the amount applies to |
periodTo | the end of the period the amount applies to |
attributedTo | the entity the sale is attributed to, such as a profile |
enteredBy | the profile who entered the record |
entered | the date and time the record was entered |
insertDataPoint(SalesDataSeries series, BigDecimal amount, Date periodFrom, Date periodTo, BaseEntity attributedTo, Profile enteredBy, Date entered, String productSku)
Returns: SalesDataRecord
Records a new sales data point against a specific product SKU, using a session obtained from the current thread. The record is saved immediately and a sales-data-updated funnel event is fired.
| Parameter | Description |
|---|---|
series | the series to add the record to, must not be null |
amount | the amount recorded for this data point |
periodFrom | the start of the period the amount applies to |
periodTo | the end of the period the amount applies to |
attributedTo | the entity the sale is attributed to, such as a profile |
enteredBy | the profile who entered the record |
entered | the date and time the record was entered |
productSku | the SKU of the product the sale relates to |
insertDataPoint(SalesDataSeries series, BigDecimal amount, Date periodFrom, Date periodTo, BaseEntity attributedTo, Date entered)
Returns: SalesDataRecord
Records a new sales data point using a session obtained from the current thread, with the entered-by profile defaulting to the currently logged in user. Delegates to the session-taking overload.
| Parameter | Description |
|---|---|
series | the series to add the record to |
amount | the amount recorded for this data point |
periodFrom | the start of the period the amount applies to |
periodTo | the end of the period the amount applies to |
attributedTo | the entity the sale is attributed to, such as a profile |
entered | the date and time the record was entered |
insertOrUpdateDataPoint(SalesDataSeries series, BigDecimal amount, Date periodFrom, Date periodTo, BaseEntity attributedTo, Date entered, Map<String,String> fields)
Returns: SalesDataRecord
Finds an existing record for the given series, entity and period and updates it, or inserts a new one if none exists. Any custom field values supplied are also applied to the record and the change is flushed immediately.
| Parameter | Description |
|---|---|
series | the series the record belongs to |
amount | the amount to set on the record |
periodFrom | the start of the period the amount applies to |
periodTo | the end of the period the amount applies to |
attributedTo | the entity the sale is attributed to, used to find an existing record |
entered | the date and time the record was entered |
fields | custom field name to value pairs to apply to the record; blank values are skipped |
updateDataPoint(SalesDataRecord r, BigDecimal amount, Date entered)
Returns: void
Updates the amount and entered date of an existing sales data record, using a session obtained from the current thread, and fires the sales-data-updated funnel event.
| Parameter | Description |
|---|---|
r | the record to update |
amount | the new amount for the record |
entered | the new entered date for the record |
deleteDataPoint(SalesDataRecord r)
Returns: void
Deletes a sales data record, using a session obtained from the current thread, and fires the sales-data-deleted funnel event.
| Parameter | Description |
|---|---|
r | the record to delete |
findExistingBySkuAndSalesBy(SalesDataRecord rec)
Returns: List<SalesDataRecord>
Finds other records that share the given record's product SKU and sales-attributed entity, regardless of period. Delegates to the period-bounded overload with no date restriction.
| Parameter | Description |
|---|---|
rec | the record whose SKU and sales-attributed entity to match on |
findExistingBySkuAndSalesBy(SalesDataRecord rec, Date from, Date to)
Returns: List<SalesDataRecord>
Finds other records that share the given record's product SKU and sales-attributed entity, within an optional period range.
| Parameter | Description |
|---|---|
rec | the record whose SKU and sales-attributed entity to match on |
from | the earliest period start to match, or null for no lower bound |
to | the latest period end to match, or null for no upper bound |
findDataPoint(SalesDataSeries series, BaseEntity attributedTo, Date from, Date to, Map<String,String> fields)
Returns: SalesDataRecord
Finds the first existing record for a series, entity and period that also matches the given custom field values, using a session obtained from the current thread.
| Parameter | Description |
|---|---|
series | the series to search in |
attributedTo | the entity the record must be attributed to |
from | the start of the period to search within |
to | the end of the period to search within |
fields | custom field name to value pairs the record must match |
findDataPoint(SalesDataSeries series, Date from, Date to, Map<String,String> fields)
Returns: SalesDataRecord
Finds the first existing record for a series and period, not restricted to any particular attributed entity, that matches the given custom field values, using a session obtained from the current thread.
| Parameter | Description |
|---|---|
series | the series to search in |
from | the start of the period to search within |
to | the end of the period to search within |
fields | custom field name to value pairs the record must match |
getRoles()
Returns: List<Role>
The roles this application contributes to the platform's permission system: the sales data viewer and sales data editor roles.
getPointsAllocationForRecord(long salesDataRecordId)
Returns: List<PointsAllocation>
Looks up the points allocations that were generated from a sales data record, using a session obtained from the current thread.
| Parameter | Description |
|---|---|
salesDataRecordId | the database id of the sales data record |
processPointsAllocation(SalesDataSeries series, Consumer<String> progressCallback)
Returns: void
Runs points allocation processing for every points allocation source configured on the series, delegating to DataSeriesManager. This is an expensive, potentially long-running operation over the series' records.
| Parameter | Description |
|---|---|
series | the series to process points allocation for |
progressCallback | callback invoked with progress messages as processing proceeds, may be null |
calculateAllocationPoints(PointsAllocationSource pas, SalesDataRecord r, Formatter f)
Returns: BigDecimal
Calculates how many points a single sales data record earns under a points allocation source, delegating to DataSeriesManager.
| Parameter | Description |
|---|---|
pas | the points allocation source defining the calculation rule |
r | the sales data record to calculate points for |
f | the formatter used to evaluate the allocation source's calculation |
getDataSeriesAppIndexer()
Returns: DataSeriesAppIndexer
The search indexer used to index sales data records, one indexer instance per application.
dataSeriesHistogram(SalesDataSeries series, Date startDate, Date endDate, String groupBy, String aggregation, Profile forUser)
Returns: KSearchResponse
Runs a date-histogram search over a series' records for the given period, aggregating the amount field by the requested aggregation type and optionally bucketed by a grouping field. Defaults the period to the current year to date when either bound is omitted, and restricts results to the organisations the given user has reporting access to, falling back to just their own records if they have none. This performs an Elasticsearch query and is relatively expensive.
| Parameter | Description |
|---|---|
series | the series to build the histogram over |
startDate | the start of the period to search, defaults to the start of the current year if null |
endDate | the end of the period to search, defaults to now if null |
groupBy | the field to sub-aggregate each histogram bucket by, or null for no grouping |
aggregation | the metric aggregation to apply to the amount field: sum, average, min, max, or a count if null or unrecognised |
forUser | the user to restrict results for, or null to search without a user-based restriction |
createSeries(String name, String title, Group salesByGroup)
Returns: SalesDataSeries
Creates and persists a new, enabled sales data series for the current organisation, attributed to profiles within a group, with dollar units and the sales-by-profile sales type.
| Parameter | Description |
|---|---|
name | the series' unique name |
title | the series' display title |
salesByGroup | the group whose profile members sales can be attributed to |
getPromotionTypes()
Returns: List<PromotionMechanicType>
The promotion mechanic types this application contributes, made available only when the installed version of the sales data app is an earlier, legacy version.
getMetricTypes()
Returns: List<MetricType>
The reporting metric types this application contributes, currently just the sum-of-sales-data metric.
© 2025 Kademi Ltd