To get full access to the Kademi Hub existing customers can login here, or new customers can register here.
Definition of a recurring set of sales figures collected from participants, such as monthly revenue per dealer. A series says who reports (the sales group), how often (the frequency and period multiples), what units the numbers are in, and optionally which extra fields to capture alongside the amount. Each submission is stored as a SalesDataRecord against a profile or an organisation, depending on the sales type. A series can also drive points allocation sources, which award points from the figures reported, and record matchers, which generate derived records from matching sets. Reminders can be sent automatically when records are due.
Group: Database Entities
Implements: Serializable, Auditable, NamedObject
Properties
| Property | Returns | Description |
|---|---|---|
| auditOrg | Organisation | The organisation that audit entries for this series are filed against, which is the series' own organisation. |
| autoCalc | boolean | Whether levels for this series are recalculated automatically, ie whether the calculation mode is auto. |
| calcMode | String | How levels are calculated for this series: auto to recalculate automatically, dry-run to calculate without applying the result, and an empty value, the default, for manual calculation only. |
| category | SalesDataSeriesCategory | Optional category the series is filed under, used to group related series in the admin UI. Lazily loaded. |
| defaultAgg | AggregationType | How several records are combined into one figure when the series is summarised, such as SUM, AVERAGE, MIN or MAX. Null means no default has been chosen. |
| deletedBy | Profile | The profile that soft deleted the series. This doubles as the deleted flag: the standard lookups only return series where it is null. |
| deletedDate | Date | Date and time the series was soft deleted, or null if it is still in use. |
| dryRun | boolean | Whether level calculation for this series runs in dry-run mode, working out the results without applying them. |
| enabled | boolean | Whether the series is currently in use. A disabled series stops collecting and reminding, but keeps the records already reported. |
| fieldMetaData | Set<NvPair> | The extra field definitions for this series as name and metadata pairs, in no particular order. Null-safe alias for the fieldset's pairs, returning an empty set rather than null when there is no fieldset. |
| fieldNames | List<String> | The names of the extra fields captured against records in this series, in no particular order. Returns an empty list when the series has no fieldset. |
| fieldset | NvSet | Optional set of extra fields to capture alongside the amount on each record. Each pair's name is the field name and its value is a comma separated list of metadata keywords, drawn from required, numeric and options(...) with a comma separated list of choices in the brackets. For example a field named howHeard might have the value required,options(google,newspaper,friend or colleague). |
| fieldsetSortedByName | List<NvPair> | The series' extra field definitions sorted by field name, for a stable display order. Returns null, not an empty list, when the series has no fieldset. |
| frequency | Frequency | How often a figure is reported, from HOURLY through to ANNUAL. Combined with the period multiples to give the real interval, so WEEKLY with a multiple of two means fortnightly. |
| id | long | Unique database identifier for this series. |
| name | String | Path-safe identifier for the series, unique within the organisation and used as the lookup key and URL segment. A soft delete renames it by appending a timestamp, so a new series can reuse the name. |
| notes | String | Administrator notes describing the series, such as what participants are expected to report. Limited to 4000 characters. |
| objectName | String | The series' name, as the generic identifier used by code that handles any kind of named object. |
| orgBased | boolean | Whether figures in this series are attributed to organisations rather than to individual profiles, ie whether the sales type is SALES_ORG. |
| periodMultiples | Integer | How many of the frequency's periods make up one reporting period, so a value of three with a DAILY frequency means every three days. Defaults to one. |
| pointsAllocationSources | List<PointsAllocationSource> | The rules that turn records reported into this series into points awarded against rewards. May be null if the series does not award points, and includes soft deleted sources. |
| pointsAllocationSourcesSorted | List<PointsAllocationSource> | The series' points allocation rules sorted by name, with soft deleted ones filtered out. Returns null, not an empty list, when the series has no sources at all. |
| recordMatchers | List<RecordMatcher> | The rules that scan records in this series for matching sets and generate corresponding destination records. May be null if the series has none, and includes soft deleted matchers. |
| recordMatchersSorted | List<RecordMatcher> | The series' record matchers sorted by name, with soft deleted ones filtered out. Returns null, not an empty list, when the series has no matchers at all. |
| salesGroup | Group | The group whose members report into this series. Optional: a null value means anyone can be associated with records in the series. Lazily loaded. |
| salesType | SalesType | Whether figures are attributed to the reporting user (SALES_PROFILE) or to their organisation (SALES_ORG). This decides what a record's salesBy points at, so changing it on a live series changes how existing records line up. |
| title | String | Free-text display label for the series, shown to administrators and participants. Carries no uniqueness guarantee, unlike the name. |
| units | String | Label for the unit the reported amounts are measured in, such as a dollar sign or the word litres. Used for display only; it does not affect any calculation. Defaults to a dollar sign. |
| website | Website | Optional website used for context when the series sends emails, such as reminders, so links and branding resolve correctly. Lazily loaded. |
Methods
getId() · getName() · setName(String name) · getTitle() · setTitle(String title) · getUnits() · setUnits(String units) · getNotes() · setNotes(String notes) · setOrganisation(Organisation organisation) · getCalcMode() · setCalcMode(String calcMode) · getSalesGroup() · setSalesGroup(Group salesGroup) · isEnabled() · setEnabled(boolean enabled) · getFrequency() · setFrequency(Frequency frequency) · getPeriodMultiples() · setPeriodMultiples(Integer periodMultiples) · getSalesType() · setSalesType(SalesType salesType) · getPointsAllocationSources() · setPointsAllocationSources(List<PointsAllocationSource> pointsAllocationSources) · getRecordMatchers() · setRecordMatchers(List<RecordMatcher> recordMatchers) · getDeletedDate() · setDeletedDate(Date deletedDate) · getDeletedBy() · setDeletedBy(Profile deletedBy) · getWebsite() · setWebsite(Website website) · getFieldset() · setFieldset(NvSet fieldset) · getDefaultAgg() · setDefaultAgg(AggregationType defaultAgg) · getCategory() · setCategory(SalesDataSeriesCategory category) · createRecord() · getFieldMetaData() · getFieldNames() · isAvailableTo(Profile p) · getAuditOrg() · findFieldOrdinal(String name) · findFieldName(int pos) · pointsAllocationSource(String name) · recordMatcher(String name) · isOrgBased() · isAutoCalc() · isDryRun() · getObjectName() · getPointsAllocationSourcesSorted() · getRecordMatchersSorted() · getFieldsetSortedByName()
getId()
Returns: long
Unique database identifier for this series.
getName()
Returns: String
Path-safe identifier for the series, unique within the organisation and used as the lookup key and URL segment. A soft delete renames it by appending a timestamp, so a new series can reuse the name.
setName(String name)
Returns: void
Sets the path-safe name used to look the series up.
| Parameter | Description |
|---|---|
name | the series name to use |
getTitle()
Returns: String
Free-text display label for the series, shown to administrators and participants. Carries no uniqueness guarantee, unlike the name.
setTitle(String title)
Returns: void
Sets the free-text display label for the series.
| Parameter | Description |
|---|---|
title | the display title to use |
getUnits()
Returns: String
Label for the unit the reported amounts are measured in, such as a dollar sign or the word litres. Used for display only; it does not affect any calculation. Defaults to a dollar sign.
setUnits(String units)
Returns: void
Sets the label for the unit the reported amounts are measured in.
| Parameter | Description |
|---|---|
units | the units label to display |
getNotes()
Returns: String
Administrator notes describing the series, such as what participants are expected to report. Limited to 4000 characters.
setNotes(String notes)
Returns: void
Sets the administrator notes describing the series.
| Parameter | Description |
|---|---|
notes | the administrator notes to store |
setOrganisation(Organisation organisation)
Returns: void
Sets the account holder organisation this series belongs to.
| Parameter | Description |
|---|---|
organisation | the owning organisation |
getCalcMode()
Returns: String
How levels are calculated for this series: auto to recalculate automatically, dry-run to calculate without applying the result, and an empty value, the default, for manual calculation only.
setCalcMode(String calcMode)
Returns: void
Sets how levels are calculated for this series.
| Parameter | Description |
|---|---|
calcMode | auto, dry-run, or an empty value for manual calculation |
getSalesGroup()
Returns: Group
The group whose members report into this series. Optional: a null value means anyone can be associated with records in the series. Lazily loaded.
setSalesGroup(Group salesGroup)
Returns: void
Sets the group whose members report into this series, or opens it to anyone by passing null.
| Parameter | Description |
|---|---|
salesGroup | the reporting group, or null for no restriction |
isEnabled()
Returns: boolean
Whether the series is currently in use. A disabled series stops collecting and reminding, but keeps the records already reported.
setEnabled(boolean enabled)
Returns: void
Enables or disables collection for this series.
| Parameter | Description |
|---|---|
enabled | true to enable the series, false to disable it |
getFrequency()
Returns: Frequency
How often a figure is reported, from HOURLY through to ANNUAL. Combined with the period multiples to give the real interval, so WEEKLY with a multiple of two means fortnightly.
setFrequency(Frequency frequency)
Returns: void
Sets how often a figure is reported into this series.
| Parameter | Description |
|---|---|
frequency | the reporting frequency |
getPeriodMultiples()
Returns: Integer
How many of the frequency's periods make up one reporting period, so a value of three with a DAILY frequency means every three days. Defaults to one.
setPeriodMultiples(Integer periodMultiples)
Returns: void
Sets how many of the frequency's periods make up one reporting period.
| Parameter | Description |
|---|---|
periodMultiples | the number of periods per reporting interval |
getSalesType()
Returns: SalesType
Whether figures are attributed to the reporting user (SALES_PROFILE) or to their organisation (SALES_ORG). This decides what a record's salesBy points at, so changing it on a live series changes how existing records line up.
setSalesType(SalesType salesType)
Returns: void
Sets whether figures are attributed to the reporting user or to their organisation.
| Parameter | Description |
|---|---|
salesType | SALES_PROFILE to attribute to the user, SALES_ORG to attribute to their organisation |
getPointsAllocationSources()
Returns: List<PointsAllocationSource>
The rules that turn records reported into this series into points awarded against rewards. May be null if the series does not award points, and includes soft deleted sources.
setPointsAllocationSources(List<PointsAllocationSource> pointsAllocationSources)
Returns: void
Replaces the collection of points allocation rules held against the series.
| Parameter | Description |
|---|---|
pointsAllocationSources | the points allocation sources to hold against the series |
getRecordMatchers()
Returns: List<RecordMatcher>
The rules that scan records in this series for matching sets and generate corresponding destination records. May be null if the series has none, and includes soft deleted matchers.
setRecordMatchers(List<RecordMatcher> recordMatchers)
Returns: void
Replaces the collection of record matchers held against the series.
| Parameter | Description |
|---|---|
recordMatchers | the record matchers to hold against the series |
getDeletedDate()
Returns: Date
Date and time the series was soft deleted, or null if it is still in use.
setDeletedDate(Date deletedDate)
Returns: void
Sets the date and time the series was soft deleted.
| Parameter | Description |
|---|---|
deletedDate | the deletion timestamp to record |
getDeletedBy()
Returns: Profile
The profile that soft deleted the series. This doubles as the deleted flag: the standard lookups only return series where it is null.
setDeletedBy(Profile deletedBy)
Returns: void
Sets the profile recorded as having soft deleted the series, which also marks it as deleted.
| Parameter | Description |
|---|---|
deletedBy | the deleting profile, or null to undelete the series |
getWebsite()
Returns: Website
Optional website used for context when the series sends emails, such as reminders, so links and branding resolve correctly. Lazily loaded.
setWebsite(Website website)
Returns: void
Sets the website used for context when the series sends emails.
| Parameter | Description |
|---|---|
website | the website to use for email context |
getFieldset()
Returns: NvSet
Optional set of extra fields to capture alongside the amount on each record. Each pair's name is the field name and its value is a comma separated list of metadata keywords, drawn from required, numeric and options(...) with a comma separated list of choices in the brackets. For example a field named howHeard might have the value required,options(google,newspaper,friend or colleague).
setFieldset(NvSet fieldset)
Returns: void
Sets the extra fields captured alongside the amount on each record.
| Parameter | Description |
|---|---|
fieldset | the field definitions to capture against each record |
getDefaultAgg()
Returns: AggregationType
How several records are combined into one figure when the series is summarised, such as SUM, AVERAGE, MIN or MAX. Null means no default has been chosen.
setDefaultAgg(AggregationType defaultAgg)
Returns: void
Sets how several records are combined into one figure when the series is summarised.
| Parameter | Description |
|---|---|
defaultAgg | the default aggregation type to use |
getCategory()
Returns: SalesDataSeriesCategory
Optional category the series is filed under, used to group related series in the admin UI. Lazily loaded.
setCategory(SalesDataSeriesCategory category)
Returns: void
Files the series under a category, or removes it from one by passing null.
| Parameter | Description |
|---|---|
category | the category to file the series under |
createRecord()
Returns: SalesDataRecord
Creates a new, unsaved record for this series, ready to have its participant, period and amount set.
getFieldMetaData()
Returns: Set<NvPair>
The extra field definitions for this series as name and metadata pairs, in no particular order. Null-safe alias for the fieldset's pairs, returning an empty set rather than null when there is no fieldset.
getFieldNames()
Returns: List<String>
The names of the extra fields captured against records in this series, in no particular order. Returns an empty list when the series has no fieldset.
isAvailableTo(Profile p)
Returns: boolean
Whether the given profile is allowed to report into this series, which is true when the series has no sales group or the profile is a member of it.
| Parameter | Description |
|---|---|
p | the profile to test |
getAuditOrg()
Returns: Organisation
The organisation that audit entries for this series are filed against, which is the series' own organisation.
findFieldOrdinal(String name)
Returns: Integer
The one-based position of a named extra field within the series' fieldset, matching the order the fields are displayed in.
| Parameter | Description |
|---|---|
name | the extra field name to look up |
findFieldName(int pos)
Returns: String
The name of the extra field at the given one-based position within the series' fieldset.
| Parameter | Description |
|---|---|
pos | the one-based position of the field to look up |
pointsAllocationSource(String name)
Returns: PointsAllocationSource
Finds one of the series' points allocation rules by name, searching the already loaded collection rather than the database. Soft deleted sources are included in the search.
| Parameter | Description |
|---|---|
name | the points allocation source name to look for |
recordMatcher(String name)
Returns: RecordMatcher
Finds one of the series' record matchers by name, searching the already loaded collection rather than the database. Soft deleted matchers are included in the search.
| Parameter | Description |
|---|---|
name | the record matcher name to look for |
isOrgBased()
Returns: boolean
Whether figures in this series are attributed to organisations rather than to individual profiles, ie whether the sales type is SALES_ORG.
isAutoCalc()
Returns: boolean
Whether levels for this series are recalculated automatically, ie whether the calculation mode is auto.
isDryRun()
Returns: boolean
Whether level calculation for this series runs in dry-run mode, working out the results without applying them.
getObjectName()
Returns: String
The series' name, as the generic identifier used by code that handles any kind of named object.
getPointsAllocationSourcesSorted()
Returns: List<PointsAllocationSource>
The series' points allocation rules sorted by name, with soft deleted ones filtered out. Returns null, not an empty list, when the series has no sources at all.
getRecordMatchersSorted()
Returns: List<RecordMatcher>
The series' record matchers sorted by name, with soft deleted ones filtered out. Returns null, not an empty list, when the series has no matchers at all.
getFieldsetSortedByName()
Returns: List<NvPair>
The series' extra field definitions sorted by field name, for a stable display order. Returns null, not an empty list, when the series has no fieldset.
© 2025 Kademi Ltd