DataSeriesManager

Need help? Ask Kademi

Manages sales data series and the sales data records logged against them, and the points allocation sources that turn those records into reward points or debits. Covers creating and looking up series, categories and extra fields; recording, finding and aggregating individual sales data points; and running the points allocation engine, including a dry-run mode that writes a preview spreadsheet instead of issuing real points. Reached from server-side JS as the registered "dataSeriesManager" service.

Group: Managers

Implements: StartableService

Properties

Property	Returns	Description
allCategories	`List<SalesDataSeriesCategory>`	Finds all sales data series categories for the current tenant.
allSeries	`List<SalesDataSeries>`	Finds all sales data series for the current tenant.

Methods

`dryRunPreviewPath(SalesDataSeries series)`

Returns: Path

Path of the series' own dry-run preview spreadsheet - a plain, mechanic-owned file that never touches the reward service or any persisted entity. Keyed on the series' name rather than its numeric id, since the path is visible to admins (e.g. in the "view preview" link) and the name is the user-meaningful identifier.

Parameter	Description
`series`	a sales data series

`hasDryRunPreview(SalesDataSeries series)`

Returns: boolean

Checks whether the series' dry-run preview spreadsheet has actually been created, meaning at least one row has been recorded since it was last cleared.

Parameter	Description
`series`	a sales data series

`deleteDryRunPreview(SalesDataSeries series)`

Returns: void

Permanently discards every row in the series' dry-run preview spreadsheet.

Parameter	Description
`series`	the sales data series to clear the dry-run preview for

`createDryRunPreviewTable(SalesDataSeries series)`

Returns: void

Creates the series' dry-run preview spreadsheet (header row only), if it doesn't already exist. Called once from the single-threaded root map task of a points-allocation scan (see PointsAllocationMapReduceProcessable), before any records are processed - potentially concurrently, on separate threads - so no two batches can race to create the table themselves and each write a header row.

Parameter	Description
`series`	the sales data series, which must be in dry-run mode

`findDataSeriesContent(String seriesName)`

Returns: DataSeriesContent

This finds any content configuration for the named data series. The returned object has information to control the presentation of fields and the series as a whole

Parameter	Description
`seriesName`	- the name of the series to find content for

`findByIds(Collection<Long> ids)`

Returns: List<SalesDataRecord>

Looks up sales data records by id, batching the query in groups of 1000 to stay within database parameter limits.

Parameter	Description
`ids`	the record ids to look up; a null or empty collection returns an empty list

`countUnprocessedSalesRecs()`

Returns: long

Counts sales records across all series that have not yet had their reward points processed.

`countUnprocessedSalesRecs(Date startDate, Date endDate)`

Returns: long

Counts sales records across all series that have not yet had their reward points processed, restricted to a date range.

Parameter	Description
`startDate`	the earliest record date to include; may be null for no lower bound
`endDate`	the latest record date to include; may be null for no upper bound

`findEntitiesWithUnprocessedRecs()`

Returns: List<Long>

Finds the ids of entities (profiles or organisations) that have at least one unprocessed sales record in any series.

`countPointsAllocationsWithErrors()`

Returns: long

Counts points allocation records that recorded an error while processing, across the whole account with no date restriction.

`findPointsAllocationsWithErrors(SearchProperties searchProperties)`

Returns: List<PointsAllocation>

Finds points allocation records that recorded an error while processing.

Parameter	Description
`searchProperties`	paging and sorting options to apply to the search

`dataSeriesExtraFields(SalesDataSeries sds)`

Returns: List<ExtraField>

Parses the custom extra fields configured on a series' fieldset into ExtraField objects.

Parameter	Description
`sds`	the sales data series to read extra fields from; may be null, or have no fieldset, in which case an empty list is returned

`resetPointsAllocations(List<SalesDataRecord> records, boolean deleteSales)`

Returns: void

Resets all available reward points for the given sales records, optionally deleting the sales records themselves, then refreshes the points balance for every entity affected.

Parameter	Description
`records`	the sales records to reset; records with no rewards issued yet are skipped
`deleteSales`	if true, delete each sales record after resetting its rewards; if false, clear its rewards-issued date instead

`resetPointsAllocations(SalesDataRecord rec, boolean deleteSale, boolean resetPointsBalance)`

Returns: void

Resets a sales record's reward points, optionally deleting the sales record and optionally refreshing the points balance for entities affected.

Parameter	Description
`rec`	the sales record to reset
`deleteSale`	if true, delete the sales record after resetting its rewards
`resetPointsBalance`	if true, refresh the points balance for every entity affected

`resetPointsAllocations(SalesDataRecord rec, boolean deleteSale, boolean resetPointsBalance, boolean createDebitForUsedPoints)`

Returns: void

Resets a sales record's reward points, optionally deleting the sales record, optionally refreshing the points balance for entities affected, and optionally creating a debit to claw back any points already used.

Parameter	Description
`rec`	the sales record to reset
`deleteSale`	if true, delete the sales record after resetting its rewards
`resetPointsBalance`	if true, refresh the points balance for every entity affected
`createDebitForUsedPoints`	if true, create a debit for any of the reset points that have already been used

`resetPointsAllocations(SalesDataRecord rec)`

Returns: void

Resets a sales record's reward points without deleting the record or refreshing the points balance.

Parameter	Description
`rec`	the sales record to reset

`resetSalesRecord(SalesDataRecord rec)`

Returns: void

Resets a sales record's own rewards, and unwinds any record-matcher activity it is involved in, whether as one of the records a match consumed (SOURCE) or as a record a match generated (DEST). For every such match group, every OTHER destination record the group produced (ie not rec itself) has its own rewards reset and is then deleted, and the group itself is deleted. rec is only ever reset, never deleted, since callers are typically resetting the record whose detail page they are viewing. Only unwinds one level of matching - if a destination record deleted here was itself later consumed as a source by a further match, that further match is left untouched.

Parameter	Description
`rec`	the sales record to reset

`resetPointsAllocations(SalesDataRecord rec, boolean deleteSales)`

Returns: void

Resets all available reward points for a sales record and deletes it; the points balance is not refreshed.

Parameter	Description
`rec`	the sales record to reset and delete
`deleteSales`	if true, delete the sales record after resetting its rewards

`resetListPointsAllocations(List<PointsAllocation> listPa, boolean deleteSales)`

Returns: void

Resets a list of points allocations, optionally deleting their sales records, then refreshes the points balance for every entity affected.

Parameter	Description
`listPa`	the points allocations to reset
`deleteSales`	if true, delete each allocation's sales record after resetting its rewards

`resetPointsAllocation(PointsAllocation pa, boolean deleteSales, boolean resetPointsBalance)`

Returns: void

Resets a single points allocation, optionally deleting its sales record, and optionally refreshing the points balance for the entities affected.

Parameter	Description
`pa`	the points allocation to reset
`deleteSales`	if true, delete the allocation's sales record after resetting its rewards
`resetPointsBalance`	if true, refresh the points balance for every entity affected

`resetPointsAllocation(PointsAllocation pa, boolean deleteSales)`

Returns: void

Resets a single points allocation and optionally deletes its sales record, without refreshing the points balance.

Parameter	Description
`pa`	the points allocation to reset
`deleteSales`	if true, delete the allocation's sales record after resetting its rewards

`processPointsAllocation(SalesDataSeries series, Consumer<String> progressCallback)`

Returns: void

Runs the full points allocation scan for a series: processes its record matchers, finds every sales record not yet allocated points, then processes each of the series' points allocation sources against them, refreshing the points balance for every entity affected once done (unless the series is in dry-run mode, in which case rows are written to the preview spreadsheet instead).

Parameter	Description
`series`	the sales data series to process
`progressCallback`	optional callback invoked with human-readable progress messages; may be null

`processPointsAllocation(PointsAllocationSource pas, List<SalesDataRecord> records, Consumer<String> progressCallback, Set<SalesDataRecord> processed)`

Returns: void

Processes a single points allocation source against a list of sales records, without capturing which entities' points balances need refreshing afterwards.

Parameter	Description
`pas`	the points allocation source to process
`records`	the sales records to consider
`progressCallback`	optional callback invoked with human-readable progress messages; may be null
`processed`	records that were included and processed are added to this set

`processPointsAllocation(PointsAllocationSource pas, List<SalesDataRecord> records, Consumer<String> progressCallback, Set<SalesDataRecord> processed, Map<Long,Set<Long>> entitiesRewards)`

Returns: void

Processes a single points allocation source against a list of sales records - skipping deleted sources, sources tied to an inactive promotion, and sources with no reward configured. For each included record, awards or debits points individually, or (in SUM allocation mode) accumulates the amount per participant and awards or debits the total once all records have been considered.

Parameter	Description
`pas`	the points allocation source to process
`records`	the sales records to consider
`progressCallback`	optional callback invoked with human-readable progress messages; may be null
`processed`	records that were included and processed are added to this set
`entitiesRewards`	entity-id to reward-ids map that captures which entities' balances need refreshing afterwards; may be null

`processSingleRecordPoints(SalesDataRecord r)`

Returns: void

Processes reward points for a single sales record against every non-deleted points allocation source with a reward on its series, then refreshes the points balance for entities affected (unless the series is in dry-run mode). Does nothing if the record is null or already has a rewards-issued date.

Parameter	Description
`r`	the sales record to process

`testPointsAllocation(PointsAllocationSource pas, SalesDataRecord r)`

Returns: PointsAllocationResult

Calculates what a points allocation source would award or debit for a sales record, without persisting anything or logging detail messages.

Parameter	Description
`pas`	the points allocation source to test
`r`	the sales record to test against

`testPointsAllocation(PointsAllocationSource pas, SalesDataRecord r, List<String> logs)`

Returns: PointsAllocationResult

Calculates what a points allocation source would award or debit for a sales record, without persisting anything, capturing the log messages produced while evaluating the source's rules.

Parameter	Description
`pas`	the points allocation source to test
`r`	the sales record to test against
`logs`	log messages produced while evaluating the source are appended here; may be null to skip capture

`createPointsAllocationSource(String name, String title, SalesDataSeries series, Reward reward)`

Returns: void

Creates a new points allocation source on a series, with the given reward.

Parameter	Description
`name`	the source's unique, path-safe name
`title`	the source's display title
`series`	the sales data series to create the source on
`reward`	the reward the source issues points against

`findPointsAllocationSource(Long id)`

Returns: PointsAllocationSource

Finds a points allocation source by id.

Parameter	Description
`id`	the points allocation source id

`findPointsAllocation(Long id)`

Returns: PointsAllocation

Finds a points allocation by id, for the current tenant.

Parameter	Description
`id`	the points allocation id

`pointsAllocations(SalesDataRecord salesDataRecord)`

Returns: List<PointsAllocation>

Finds all points allocations that were calculated from a sales record.

Parameter	Description
`salesDataRecord`	the sales record to find allocations for

`updateSalesRecord(SalesDataRecord record, FormContext rc)`

Returns: void

Updates a sales record's fields from posted form parameters and then refreshes its search index entry.

Parameter	Description
`record`	the sales record to update
`rc`	the form context to bind the posted parameters from

`salesRecordUpdated(SalesDataRecord sdr)`

Returns: void

Deprecated. Use salesDataRecordUpdated instead. Call this after updating properties on a sales data record so it can update the search index.

Parameter	Description
`sdr`	the sales record that was updated

`allocationType(String s)`

Returns: AllocationType

Parses a points allocation source allocation-type name (e.g. "INDIVIDUAL", "SUM") into its enum value.

Parameter	Description
`s`	the allocation type name

`newPointsAllocationSourceBuilder(SalesDataSeries series)`

Returns: PointsAllocationSourceBuilder

Creates a new fluent builder for configuring and creating a points allocation source on a series.

Parameter	Description
`series`	the sales data series the new points allocation source will belong to

`duplicatePointsAllocationSource(String name, String title, SalesDataSeries series, PointsAllocationSource fromPAS)`

Returns: void

Creates a new points allocation source on a series by copying the configuration of an existing one.

Parameter	Description
`name`	the new source's unique, path-safe name
`title`	the new source's display title
`series`	the sales data series to create the new source on
`fromPAS`	the existing points allocation source to copy configuration from

`calculateAllocationPoints(PointsAllocationSource pas, SalesDataRecord r)`

Returns: PointsAllocationResult

Calculates the points a points allocation source would award or debit for a sales record - via a configured points rule type if one is set, otherwise via the source's MVEL expression, otherwise falling back to the record's raw amount.

Parameter	Description
`pas`	the points allocation source to calculate points for
`r`	the sales record to calculate against

`calculateAllocationPoints(PointsAllocationSource pas, SalesDataRecord r, Formatter f)`

Returns: PointsAllocationResult

Calculates the points a points allocation source would award or debit for a sales record, using the given formatter to evaluate the source's MVEL expression if one is configured.

Parameter	Description
`pas`	the points allocation source to calculate points for
`r`	the sales record to calculate against
`f`	the formatter used to evaluate the MVEL expression and coerce its result to a number

`findPointsRecipient(SalesDataRecord rec, PointsAllocationSource source)`

Returns: BaseEntity

Resolves the entity a points allocation source would issue points to or debit points from for a sales record - the record's salesBy entity if the source has no recipient expression configured, otherwise the profile or organisation the source's recipient KCode expression resolves to.

Parameter	Description
`rec`	the sales record to resolve a recipient for
`source`	the points allocation source whose recipient rule is evaluated

`isAllocationPointsIncluded(PointsAllocationSource pas, SalesDataRecord r)`

Returns: boolean

Checks whether a sales record satisfies a points allocation source's inclusion rules - the connected promotion's status, date range and eligibility (if any), and then the source's configured points rule type or ignore expression.

Parameter	Description
`pas`	the points allocation source whose rules are evaluated
`r`	the sales record to check

`findMatchingSources(SalesDataSeries series, SalesDataRecord r)`

Returns: List<PointsAllocationSource>

Finds the non-deleted points allocation sources on a series whose inclusion rules match a sales record.

Parameter	Description
`series`	the sales data series whose points allocation sources are checked
`r`	the sales record to match against

`sum(SalesDataSeries series, BaseEntity attributedTo, Date startDate, Date endDate)`

Returns: BigDecimal

Sums a series' sales record amounts attributed to a single entity within a date range.

Parameter	Description
`series`	the sales data series to aggregate
`attributedTo`	the entity to filter records by
`startDate`	the earliest record date to include; may be null for no lower bound
`endDate`	the latest record date to include; may be null for no upper bound

`sum(SalesDataSeries series, Set<BaseEntity> attributedTo, Date startDate, Date endDate)`

Returns: BigDecimal

Sums a series' sales record amounts attributed to any of a set of entities within a date range.

Parameter	Description
`series`	the sales data series to aggregate
`attributedTo`	the entities to filter records by
`startDate`	the earliest record date to include; may be null for no lower bound
`endDate`	the latest record date to include; may be null for no upper bound

`sumByOrg(SalesDataSeries series, Organisation attributedTo, Date startDate, Date endDate)`

Returns: BigDecimal

Sums a series' sales record amounts attributed to a single organisation's sales team within a date range.

Parameter	Description
`series`	the sales data series to aggregate
`attributedTo`	the organisation to filter records by
`startDate`	the earliest record date to include; may be null for no lower bound
`endDate`	the latest record date to include; may be null for no upper bound

`average(SalesDataSeries series, BaseEntity attributedTo, Date startDate, Date endDate)`

Returns: BigDecimal

Averages a series' sales record amounts attributed to a single entity within a date range.

Parameter	Description
`series`	the sales data series to aggregate
`attributedTo`	the entity to filter records by
`startDate`	the earliest record date to include; may be null for no lower bound
`endDate`	the latest record date to include; may be null for no upper bound

`count(SalesDataSeries series, BaseEntity attributedTo, Date startDate, Date endDate)`

Returns: long

Counts a series' sales records attributed to a single entity within a date range.

Parameter	Description
`series`	the sales data series to count records in
`attributedTo`	the entity to filter records by
`startDate`	the earliest record date to include; may be null for no lower bound
`endDate`	the latest record date to include; may be null for no upper bound

`minimum(SalesDataSeries series, BaseEntity attributedTo, Date startDate, Date endDate)`

Returns: BigDecimal

Finds the minimum sales record amount attributed to a single entity within a date range.

Parameter	Description
`series`	the sales data series to aggregate
`attributedTo`	the entity to filter records by
`startDate`	the earliest record date to include; may be null for no lower bound
`endDate`	the latest record date to include; may be null for no upper bound

`maximum(SalesDataSeries series, BaseEntity attributedTo, Date startDate, Date endDate)`

Returns: BigDecimal

Finds the maximum sales record amount attributed to a single entity within a date range.

Parameter	Description
`series`	the sales data series to aggregate
`attributedTo`	the entity to filter records by
`startDate`	the earliest record date to include; may be null for no lower bound
`endDate`	the latest record date to include; may be null for no upper bound

`createSeries(String name, String title, Group salesByGroup)`

Returns: SalesDataSeries

Creates a profile-attributed sales data series, with no website and no default aggregation type or auto-calculation.

Parameter	Description
`name`	the series' unique, path-safe name
`title`	the series' display title
`salesByGroup`	the group whose members can log sales against the series

`createSeries(String name, String title, Group salesByGroup, Website website, String defaultAgg, boolean autoCalculation)`

Returns: SalesDataSeries

Creates a profile-attributed sales data series.

Parameter	Description
`name`	the series' unique, path-safe name
`title`	the series' display title
`salesByGroup`	the group whose members can log sales against the series
`website`	the website the series belongs to; may be null
`defaultAgg`	the default aggregation type name (e.g. "SUM"); may be null or blank to leave unset
`autoCalculation`	if true, the series automatically calculates points allocations for new records

`createSeries(String name, String title, Group salesByGroup, Website website, String defaultAgg, boolean autoCalculation, SalesType salesType)`

Returns: SalesDataSeries

Creates a sales data series, attributed to profiles or organisations depending on the given sales type.

Parameter	Description
`name`	the series' unique, path-safe name
`title`	the series' display title
`salesByGroup`	the group whose members can log sales against the series
`website`	the website the series belongs to; may be null
`defaultAgg`	the default aggregation type name (e.g. "SUM"); may be null or blank to leave unset
`autoCalculation`	if true, the series automatically calculates points allocations for new records
`salesType`	whether the series is attributed to profiles or organisations

`findAggregationType(String aggregationType)`

Returns: AggregationType

Parses an aggregation type name (e.g. "sum", "AVERAGE") into its enum value, case-insensitively.

Parameter	Description
`aggregationType`	the aggregation type name; may be null or blank

`findSeriesByName(String name)`

Returns: SalesDataSeries

Alias for dataSeries(String) - finds a sales data series by name.

Parameter	Description
`name`	the series' unique name

`dataSeries(String name)`

Returns: SalesDataSeries

Finds a sales data series by name, for the current tenant.

Parameter	Description
`name`	the series' unique name

`getAllSeries()`

Returns: List<SalesDataSeries>

Finds all sales data series for the current tenant.

`getAllCategories()`

Returns: List<SalesDataSeriesCategory>

Finds all sales data series categories for the current tenant.

`findCategoryByName(String name)`

Returns: SalesDataSeriesCategory

Finds a sales data series category by name, for the current tenant.

Parameter	Description
`name`	the category's unique name

`createCategory(String name, String title)`

Returns: SalesDataSeriesCategory

Creates a sales data series category for the current tenant.

Parameter	Description
`name`	the category's unique, path-safe name
`title`	the category's display title

`dataSeriesSalesType(String name)`

Returns: SalesType

Parses a sales type name (e.g. "SALES_ORG", "SALES_PROFILE") into its enum value.

Parameter	Description
`name`	the sales type name

`dataSeriesFrequency(String name)`

Returns: Frequency

Parses a series frequency name into its enum value.

Parameter	Description
`name`	the frequency name

`dataSeriesAggregationType(String name)`

Returns: AggregationType

Parses an aggregation type name into its enum value.

Parameter	Description
`name`	the aggregation type name

`isOrgSaleType(SalesDataSeries series)`

Returns: boolean

Checks whether a series is organisation-attributed.

Parameter	Description
`series`	the sales data series to check

`findRecord(long id)`

Returns: SalesDataRecord

Finds a sales data record by id, for the current tenant.

Parameter	Description
`id`	the sales data record id

`findRecords(SalesDataSeries series, Date from, Date to, String orderByField, Boolean asc)`

Returns: List<SalesDataRecord>

Finds a series' sales records within a date range, sorted by the given field.

Parameter	Description
`series`	the sales data series to find records in
`from`	the earliest record date to include; may be null for no lower bound
`to`	the latest record date to include; may be null for no upper bound
`orderByField`	the record field to sort by
`asc`	true to sort ascending, false to sort descending

`findRecords(SalesDataSeries series, BaseEntity baseEntity, Date from, Date to)`

Returns: List<SalesDataRecord>

Finds a series' sales records attributed to a single entity within a date range.

Parameter	Description
`series`	the sales data series to find records in
`baseEntity`	the entity to filter records by
`from`	the earliest record date to include; may be null for no lower bound
`to`	the latest record date to include; may be null for no upper bound

`findRecords(SalesDataSeries series, List<BaseEntity> baseEntities, Date from, Date to, String orderByField, Boolean asc)`

Returns: List<SalesDataRecord>

Finds a series' sales records attributed to any of a list of entities within a date range, sorted by the given field.

Parameter	Description
`series`	the series to filter by
`baseEntities`	the list of entities to match on
`from`	the earliest record date to include; may be null for no lower bound
`to`	the latest record date to include; may be null for no upper bound
`orderByField`	the record field to sort by
`asc`	true to sort ascending, false to sort descending

`sumRecords(SalesDataSeries series, BaseEntity baseEntity, Date from, Date to)`

Returns: BigDecimal

Sums a series' sales record amounts attributed to a single entity within a date range.

Parameter	Description
`series`	the sales data series to aggregate
`baseEntity`	the entity to filter records by
`from`	the earliest record date to include; may be null for no lower bound
`to`	the latest record date to include; may be null for no upper bound

`averageRecords(SalesDataSeries series, BaseEntity baseEntity, Date from, Date to)`

Returns: BigDecimal

Averages a series' sales record amounts attributed to a single entity within a date range.

Parameter	Description
`series`	the sales data series to aggregate
`baseEntity`	the entity to filter records by
`from`	the earliest record date to include; may be null for no lower bound
`to`	the latest record date to include; may be null for no upper bound

`countRecords(SalesDataSeries series, BaseEntity baseEntity, Date from, Date to)`

Returns: long

Counts a series' sales records attributed to a single entity within a date range.

Parameter	Description
`series`	the sales data series to count records in
`baseEntity`	the entity to filter records by
`from`	the earliest record date to include; may be null for no lower bound
`to`	the latest record date to include; may be null for no upper bound

`findEntityForSeries(SalesDataSeries series, Profile user)`

Returns: BaseEntity

Calls findEntitiesForSeries and, if there is only one match, returns it. If there are multiple entities (i.e. the user is associated with multiple orgs for the series) then tries to match the currently selected team org, and returns that; otherwise defaults to returning the first entity found.

Parameter	Description
`series`	the sales data series to resolve an entity for
`user`	the user to resolve an entity for

`findEntitiesForSeries(SalesDataSeries series, Profile user)`

Returns: List<BaseEntity>

Finds the entities a user can log or view sales data for a series as - the user themselves for a profile-attributed series, or the organisations they hold a matching group membership in for an org-attributed series.

Parameter	Description
`series`	the sales data series to find entities for
`user`	the user to find entities for

`toRecordBeans(List<SalesDataRecord> recs)`

Returns: List<RecordBean>

Converts sales data records to their display bean form.

Parameter	Description
`recs`	the records to convert; may be null

`insertDataPoint(DataPoint dp)`

Returns: SalesDataRecord

Creates and persists a sales data record from a configured DataPoint, obtained from newDataPoint(). Fires the sales record created and updated events unless the data point was configured to suppress events.

Parameter	Description
`dp`	the configured data point to insert; must have a series, an attributedTo entity and an amount set

`salesDataRecordUpdated(SalesDataRecord sdr)`

Returns: void

Call this after updating a sales record's properties to persist it, update its search index entry and fire the sales-data and indexed-item-updated events.

Parameter	Description
`sdr`	the sales record that was updated

`deleteRecord(SalesDataRecord sdr)`

Returns: void

Deletes a sales data record and fires the sales-data and indexed-item-updated events.

Parameter	Description
`sdr`	the sales record to delete

`findDataRecords(SalesDataSeries series, BaseEntity attributedTo, Date from, Date to, Map<String,String> fields)`

Returns: List<SalesDataRecord>

Finds a series' sales records attributed to a single entity within a date range, additionally matching the given extra field values.

Parameter	Description
`series`	the sales data series to find records in
`attributedTo`	the entity to filter records by
`from`	the earliest record date to include; may be null for no lower bound
`to`	the latest record date to include; may be null for no upper bound
`fields`	extra field name/value pairs the record must match

`findDataRecords(SalesDataSeries series, Set<BaseEntity> attributedTo, Date from, Date to)`

Returns: List<SalesDataRecord>

Finds a series' sales records attributed to any of a set of entities within a date range.

Parameter	Description
`series`	the sales data series to find records in
`attributedTo`	the entities to filter records by
`from`	the earliest record date to include; may be null for no lower bound
`to`	the latest record date to include; may be null for no upper bound

`findDataPoint(SalesDataSeries series, BaseEntity attributedTo, Date from, Date to, Map<String,String> fields)`

Returns: SalesDataRecord

Finds the first (date-wise) sales record matching the given criteria.

Parameter	Description
`series`	the sales data series to find a record in
`attributedTo`	the entity to filter records by
`from`	the earliest record date to include; may be null for no lower bound
`to`	the latest record date to include; may be null for no upper bound
`fields`	extra field name/value pairs the record must match

`newDataPoint()`

Returns: DataPoint

Creates a new, unattached DataPoint builder; configure it and call save() (or pass it to insertDataPoint) to create the sales data record.

`createRandomTestData(SalesDataSeries series, BigDecimal avgAmount, Date startDate, Date endDate, long numRecords, OrgType orgType, Category skuCat)`

Returns: long

Creates random test data for the given series, using the current Hibernate session.

Parameter	Description
`series`	the series to generate records for
`avgAmount`	the average record amount; individual record amounts are randomised around this average
`startDate`	the earliest date a generated record's period may fall on
`endDate`	the latest date a generated record's period may fall on
`numRecords`	the number of records to create; values of zero or less create nothing
`orgType`	when the series is org-attributed, restricts new/found participants to this org type; may be null
`skuCat`	when set, records are randomly attributed a SKU from products in this category; may be null

`findById(Long id)`

Returns: SalesDataSeries

Finds a sales data series by id, for the current tenant.

Parameter	Description
`id`	the series id; may be null

`findByName(String name)`

Returns: SalesDataSeries

Alias for dataSeries(String) - finds a sales data series by name.

Parameter	Description
`name`	the series' unique name

`productPrice(SalesDataRecord rec, String storeName)`

Returns: BigDecimal

Calculates the final unit price of a sales record's product SKU in a given store. Passes the record's salesBy property as the purchaser to the pricing manager, so this is not appropriate for team/org based calculations.

Parameter	Description
`rec`	the sales record whose product SKU is priced
`storeName`	the name of the store to price against

`productItemisedPrice(SalesDataRecord rec, String storeName)`

Returns: ItemisedPrice

Calculates the itemised unit price of a sales record's product SKU in a given store, for the record's salesBy entity as purchaser.

Parameter	Description
`rec`	the sales record whose product SKU is priced
`storeName`	the name of the store to price against

`getAppliesToOrgs(Profile p, List<Group> appliesToGroups)`

Returns: Set<Organisation>

Finds the organisations a profile holds a matching group membership in for every one of a list of groups.

Parameter	Description
`p`	the profile to check memberships for
`appliesToGroups`	the groups the profile must hold a membership in, all within the same organisation

`processPointsAllocationForParticipant(SalesDataSeries series, BaseEntity participant)`

Returns: void

Runs the points allocation scan for a single participant of a series: processes their record matchers, finds their sales records not yet allocated points, then processes each of the series' points allocation sources against them, refreshing their points balance once done (unless the series is in dry-run mode).

Parameter	Description
`series`	the sales data series to process
`participant`	the entity to process points allocation for

`submitPointsAllocationProcess()`

Returns: void

Enqueues a background map/reduce task to process points allocation for every series' unprocessed sales records.

`submitPointsAllocationProcessForSeries(SalesDataSeries series)`

Returns: void

Enqueues a background map/reduce task to process points allocation for a single series' unprocessed sales records.

Parameter	Description
`series`	the sales data series to process

`findSalesType(String salesType)`

Returns: SalesType

Parses a sales type name into its enum value.

Parameter	Description
`salesType`	the sales type name

`findPointsSources(Reward promotion)`

Returns: List<PointsAllocationSource>

Finds the points allocation sources connected to a promotion.

Parameter	Description
`promotion`	the promotion to find points allocation sources for

`findPointsRules(Reward promotion)`

Returns: List<PointsAllocationRule>

Finds the points allocation rules connected to a promotion.

Parameter	Description
`promotion`	the promotion to find points allocation rules for

`validateExtraFieldName(String fieldName, Narrative validationMessage)`

Returns: boolean

Validates a proposed extra field name, appending a reason to validationMessage if it is invalid.

Parameter	Description
`fieldName`	the proposed extra field name
`validationMessage`	a validation reason is appended here if the name is invalid

`newDataSeriesExtraFieldBuilder()`

Returns: DataSeriesExtraFieldBuilder

Creates a new fluent builder for adding a single extra field to a sales data series.

`newDataSeriesExtraFieldBuilderV2(SalesDataSeries series)`

Returns: DataSeriesExtraFieldBuilderV2

Creates a new builder for adding multiple extra fields to a sales data series in one fieldset update.

Parameter	Description
`series`	the sales data series to add extra fields to

To get full access to the Kademi Hub existing customers can login here, or new customers can register here.