To get full access to the Kademi Hub existing customers can login here, or new customers can register here.
Owns the journey/funnel engine: creates and stores Funnel (journey) definitions, matches inbound platform events against a Funnel's entry points and goals, creates and advances Lead records through a Funnel's nodes, and fires the lead lifecycle events (created, updated, closed, cancelled) that other apps listen for. Registered as an EventListener, it receives platform events such as email delivery, subscription, shopping cart and reward events and translates the relevant ones into FunnelEvent instances that drive journeys forward. Reached from Java via C(FunnelManager.class), and from the funnels admin UI and journey automations.
Group: Managers
Implements: EventListener
Properties
| Property | Returns | Description |
|---|---|---|
| currentAttributes | Map<String,Object> | A thread-local scratch map that is reset at the start of each funnel event and shared by the event's automation checks and node actions, so they can pass data to each other without threading it through method parameters. |
| funnelActionTypes | List<FunnelActionType> | The action types available for use in journey automations, collected from every active JourneyBuilderApplication. |
| funnels | Map<String,Funnel> | All funnels defined in the current tenant organisation, keyed by funnel repository name. |
| funnelTriggerTypes | List<FunnelTriggerType> | The trigger types available for use in journey automations, collected from every active JourneyBuilderApplication. |
| nonHiddenFunnels | Map<String,Funnel> | All funnels in the current tenant organisation whose "hidden to sales" flag is not set, sorted by name. |
| scoringFactorTypes | Map<String,EngagementScoringFactorType> | The engagement scoring factor types available for use in journeys, as registered with LeadScoringService. |
Methods
recreateEvent(String urn, Map<String,Serializable> properties) · registerListener(FunnelEventListener l) · getCurrentAttributes() · createJourney(String newName, String json) · getFunnelRepo(Organisation org, String name) · getFunnelRepo(String name) · findFunnelsInCategory(RepositoryCategory category) · getFunnel(Organisation org, String name) · getFunnel(Lead lead) · getLeadRoleDefs(Lead lead) · getLeadRoleDefs(Funnel funnel) · findLeadRoleDef(Funnel funnel, String roleKey) · getFunnel(String funnelName) · getFunnel(FunnelRepository r) · getFunnel(Branch b) · getFunnel(Long funnelId) · getFunnel(Branch b, boolean useCache) · getFunnelSource(Branch b) · save(Funnel funnel) · getFunnels() · onFunnelEvent(FunnelEvent funnelEvent) · onFunnelEvent(FunnelEvent funnelEvent, boolean throwExceptions) · calcRelativeToDate(Lead lead, Goal enteringGoal, Date defaultDate) · findExistingLeads(FunnelRepository funnel, Profile cust, String trackingId) · updateLead(Lead lead) · createLead(FunnelRepository funnelRepo, String source, Profile cust, String description, Profile assignedTo, Organisation assignedToOrg) · createLead(Funnel f, FunnelRepository funnelRepo, Profile cust, String initialGoal, Map<String,String> fieldsValues) · createLead(Funnel f, FunnelRepository funnelRepo, Profile cust, Profile assignedTo, String initialGoal, Lead sourceLead, Map<String,String> fieldsValues, Asset asset) · createLead(Funnel f, FunnelRepository funnelRepo, Profile cust, String initialGoal) · createLead(Funnel f, FunnelRepository funnelRepo, Profile cust, Profile assignedTo, String initialGoal) · createLead(Funnel f, FunnelRepository funnelRepo, Profile cust, Profile assignedTo, String initialGoal, Lead sourceLead) · findMatchingTester(Funnel funnel, Lead lead) · getAllFields(Funnel f) · findFields(Funnel f, int version) · extraFieldMeta(Funnel f, String fieldId) · findFieldValue(String fieldId, Lead lead, Funnel f) · loadRules(String source) · getScoringFactorTypes() · getEngagementScore(Lead lead) · calcEngagementScore(Lead lead) · recalcAllEngagementScores(Consumer<String> progressCallback) · recalcEngagementScores(FunnelRepository repo, Consumer<String> progressCallback) · countOfLeadsToStart(Funnel funnel, String startNode) · profilesToStart(Funnel funnel, String startNode) · startLeads(Funnel funnel, String startNode) · startLeads(Funnel funnel, String startNode, List<Long> startProfileIds) · getNonHiddenFunnels() · getFunnelExtraFields(String journeyName) · getFunnelTriggerTypes() · findAvailOutcomes(Task task) · getFunnelActionTypes() · setFieldValue(Lead leadToUpdate, String fieldName, Object value) · countActiveLeads(FunnelRepository funnelRepository)
recreateEvent(String urn, Map<String,Serializable> properties)
Returns: FunnelEvent
Rebuilds a FunnelEvent from a URN of the form "prefix:appId:objectId", by asking the app named in the URN to recreate the event for the given object id and properties. Used to reconstruct an event from a stored reference rather than replaying it live.
| Parameter | Description |
|---|---|
urn | the event reference; its second colon-separated part must be the source app id and its third part the object id |
properties | extra properties to attach to the recreated event |
registerListener(FunnelEventListener l)
Returns: void
Registers a listener that is notified of every FunnelEvent processed by this manager, in addition to the manager's own journey matching logic. Used by other apps to observe funnel activity without duplicating the event dispatch logic.
| Parameter | Description |
|---|---|
l | the listener to add |
getCurrentAttributes()
Returns: Map<String,Object>
A thread-local scratch map that is reset at the start of each funnel event and shared by the event's automation checks and node actions, so they can pass data to each other without threading it through method parameters.
createJourney(String newName, String json)
Returns: FunnelRepository
Creates a new journey (funnel) repository with the given name and stores the given JSON definition as its funnel.json file in the repository's live branch. Reports the creation to account telemetry.
| Parameter | Description |
|---|---|
newName | the name of the new journey repository |
json | the JSON definition of the journey to create |
getFunnelRepo(Organisation org, String name)
Returns: FunnelRepository
Finds a funnel repository by name within the given organisation.
| Parameter | Description |
|---|---|
org | the organisation to search |
name | the funnel repository name to match |
getFunnelRepo(String name)
Returns: FunnelRepository
Finds a funnel repository by name within the current tenant organisation.
| Parameter | Description |
|---|---|
name | the funnel repository name to match |
findFunnelsInCategory(RepositoryCategory category)
Returns: List<FunnelRepository>
Finds all funnel repositories in the current tenant organisation that belong to the given category. If category is null, the funnel repositories that have no category are returned instead.
| Parameter | Description |
|---|---|
category | the category to match, or null to find uncategorised funnels |
getFunnel(Organisation org, String name)
Returns: Funnel
Finds the Funnel with the given name in the given organisation.
| Parameter | Description |
|---|---|
org | the organisation to search |
name | the funnel name to match |
getFunnel(Lead lead)
Returns: Funnel
Finds the Funnel for the given lead's current branch, falling back to the funnel repository's trunk if the lead has no branch set. Uses the funnel cache, so this is efficient to call repeatedly while iterating over a list of leads.
| Parameter | Description |
|---|---|
lead | the lead whose funnel should be found; if null, null is returned |
getLeadRoleDefs(Lead lead)
Returns: List<LeadRoleDef>
The full list of lead participant roles available for the given lead's funnel: the 4 system roles implied by Lead's legacy profile / organisation / assignedToOrg / assignedToProfile fields, plus any custom roles configured on the funnel itself.
| Parameter | Description |
|---|---|
lead | the lead whose funnel's roles should be listed |
getLeadRoleDefs(Funnel funnel)
Returns: List<LeadRoleDef>
The full list of lead participant roles available for the given funnel: the 4 system roles implied by Lead's legacy fields, plus any custom roles configured on the funnel.
| Parameter | Description |
|---|---|
funnel | the funnel whose custom roles should be merged with the system roles; may be null |
findLeadRoleDef(Funnel funnel, String roleKey)
Returns: LeadRoleDef
Finds a single role, by key, from the combined system and custom role list for the given funnel.
| Parameter | Description |
|---|---|
funnel | the funnel to search, may be null |
roleKey | the role key to find |
getFunnel(String funnelName)
Returns: Funnel
Finds the Funnel with the given name in the current tenant organisation.
| Parameter | Description |
|---|---|
funnelName | the funnel name to match |
getFunnel(FunnelRepository r)
Returns: Funnel
Gets the Funnel for the trunk branch of the given funnel repository.
| Parameter | Description |
|---|---|
r | the funnel repository to load the funnel from; if null, null is returned |
getFunnel(Branch b)
Returns: Funnel
Gets the Funnel for the given branch, using the funnel cache.
| Parameter | Description |
|---|---|
b | the branch to load the funnel from |
getFunnel(Long funnelId)
Returns: Funnel
Finds the Funnel with the given funnel repository id in the current tenant organisation.
| Parameter | Description |
|---|---|
funnelId | the id of the funnel repository to load; if null, null is returned |
getFunnel(Branch b, boolean useCache)
Returns: Funnel
Gets the Funnel for the given branch, optionally reading the funnel cache instead of parsing the branch's funnel.json file directly.
| Parameter | Description |
|---|---|
b | the branch to load the funnel from |
useCache | true to use the funnel cache, false to force a fresh parse of the funnel definition |
getFunnelSource(Branch b)
Returns: String
Returns the raw JSON source of the funnel definition stored on the given branch. Intended for debugging rather than for regular use.
| Parameter | Description |
|---|---|
b | the branch to read the funnel definition from |
save(Funnel funnel)
Returns: void
Saves the given Funnel as JSON back to its own branch, as the current user.
| Parameter | Description |
|---|---|
funnel | the funnel to save; its branch is resolved from funnel.getBranch() |
getFunnels()
Returns: Map<String,Funnel>
All funnels defined in the current tenant organisation, keyed by funnel repository name.
onFunnelEvent(FunnelEvent funnelEvent)
Returns: void
Feeds a FunnelEvent into the journey engine: matches it against active funnels' entry points and existing leads, and advances any matching lead through its journey nodes. Any exception raised while processing an individual funnel is caught and logged rather than propagated.
| Parameter | Description |
|---|---|
funnelEvent | the event to process |
onFunnelEvent(FunnelEvent funnelEvent, boolean throwExceptions)
Returns: void
Feeds a FunnelEvent into the journey engine, as per onFunnelEvent(FunnelEvent), but lets the caller choose whether an exception raised while processing a funnel is propagated or just logged. Does nothing if the event, its organisation, or the funnels app is not active for that organisation. Notifies any registered FunnelEventListeners, checks automations for the event's related entity, then resolves the relevant leads (the lead already related to the event if there is one, otherwise every funnel whose entry points could match the event) and transitions each through its journey.
| Parameter | Description |
|---|---|
funnelEvent | the event to process; if null, this method does nothing |
throwExceptions | true to rethrow an exception raised while processing an individual funnel, false to log and continue with the next funnel |
calcRelativeToDate(Lead lead, Goal enteringGoal, Date defaultDate)
Returns: Date
Calculates the date that a goal's timeout should be measured from, by evaluating the goal's timeoutRelativeDateMVEL expression (an MVEL expression, or a kcode expression if it starts with the kcode template prefix). Returns defaultDate unchanged if the goal is null, has no relative-date expression, if a matching funnel tester is active for the lead, or if the expression evaluates to null.
| Parameter | Description |
|---|---|
lead | the lead the goal belongs to |
enteringGoal | the goal whose timeoutRelativeDateMVEL expression should be evaluated |
defaultDate | the date to fall back to if no relative date can be calculated |
findExistingLeads(FunnelRepository funnel, Profile cust, String trackingId)
Returns: List<Lead>
Finds existing, non-deleted leads for the given funnel repository that match the given customer profile and/or tracking id, in the current tenant organisation.
| Parameter | Description |
|---|---|
funnel | the funnel repository to search |
cust | the customer profile to match; may be null |
trackingId | the tracking id to match; optional, may be null |
updateLead(Lead lead)
Returns: Lead
Marks the lead as modified now, fires its update side effects (engagement score recalculation and lead-updated events), and saves it.
| Parameter | Description |
|---|---|
lead | the lead to update |
createLead(FunnelRepository funnelRepo, String source, Profile cust, String description, Profile assignedTo, Organisation assignedToOrg)
Returns: Lead
Creates a new lead in the given funnel repository, entering it at the funnel's default entry point. Throws an exception if the funnel repository's funnel could not be loaded.
| Parameter | Description |
|---|---|
funnelRepo | the funnel repository to create the lead in |
source | a free-text description of where the lead came from |
cust | the customer profile the lead is for; may be null |
description | a description to record against the lead |
assignedTo | the profile the lead should be assigned to; may be null |
assignedToOrg | the organisation the lead should be assigned to; may be null |
createLead(Funnel f, FunnelRepository funnelRepo, Profile cust, String initialGoal, Map<String,String> fieldsValues)
Returns: Lead
Creates a new lead in the given funnel, entering it at initialGoal (or the funnel's default entry point if initialGoal is blank), and sets the given field values on it.
| Parameter | Description |
|---|---|
f | the funnel to create the lead in |
funnelRepo | the funnel's repository |
cust | the customer profile the lead is for; may be null |
initialGoal | the node id to enter the lead at, or blank to use the funnel's default entry point |
fieldsValues | a map of field name to value to set on the new lead |
createLead(Funnel f, FunnelRepository funnelRepo, Profile cust, Profile assignedTo, String initialGoal, Lead sourceLead, Map<String,String> fieldsValues, Asset asset)
Returns: Lead
Creates a new lead in the given funnel, entering it at initialGoal (or the funnel's default entry point if initialGoal is blank), assigning it and linking it to a source lead and asset.
| Parameter | Description |
|---|---|
f | the funnel to create the lead in |
funnelRepo | the funnel's repository |
cust | the customer profile the lead is for; may be null |
assignedTo | the profile the lead should be assigned to; may be null |
initialGoal | the node id to enter the lead at, or blank to use the funnel's default entry point |
sourceLead | the lead this new lead was created from; may be null |
fieldsValues | a map of field name to value to set on the new lead |
asset | the asset associated with the lead's creation; may be null |
createLead(Funnel f, FunnelRepository funnelRepo, Profile cust, String initialGoal)
Returns: Lead
Creates a new lead in the given funnel, entering it at initialGoal (or the funnel's default entry point if initialGoal is blank).
| Parameter | Description |
|---|---|
f | the funnel to create the lead in |
funnelRepo | the funnel's repository |
cust | the customer profile the lead is for; may be null |
initialGoal | the node id to enter the lead at, or blank to use the funnel's default entry point |
createLead(Funnel f, FunnelRepository funnelRepo, Profile cust, Profile assignedTo, String initialGoal)
Returns: Lead
Creates a new lead in the given funnel, entering it at initialGoal (or the funnel's default entry point if initialGoal is blank), and assigns it.
| Parameter | Description |
|---|---|
f | the funnel to create the lead in |
funnelRepo | the funnel's repository |
cust | the customer profile the lead is for; may be null |
assignedTo | the profile the lead should be assigned to; may be null |
initialGoal | the node id to enter the lead at, or blank to use the funnel's default entry point |
createLead(Funnel f, FunnelRepository funnelRepo, Profile cust, Profile assignedTo, String initialGoal, Lead sourceLead)
Returns: Lead
Creates a new lead in the given funnel, entering it at initialGoal (or the funnel's default entry point if initialGoal is blank), assigns it, and links it to a source lead.
| Parameter | Description |
|---|---|
f | the funnel to create the lead in |
funnelRepo | the funnel's repository |
cust | the customer profile the lead is for; may be null |
assignedTo | the profile the lead should be assigned to; may be null |
initialGoal | the node id to enter the lead at, or blank to use the funnel's default entry point |
sourceLead | the lead this new lead was created from; may be null |
findMatchingTester(Funnel funnel, Lead lead)
Returns: FunnelTester
Finds the first funnel tester configured on the funnel whose match conditions apply to the given lead. Funnel testers are used to bypass normal timeout/due-date calculations while testing a journey.
| Parameter | Description |
|---|---|
funnel | the funnel whose testers should be searched |
lead | the lead to match against |
getAllFields(Funnel f)
Returns: List<Field>
The full list of fields available for use in this funnel: every field registered with FieldsService (version 1), plus any extra fields defined on the given funnel.
| Parameter | Description |
|---|---|
f | the funnel whose extra fields should be included; may be null |
findFields(Funnel f, int version)
Returns: List<Field>
The full list of fields available for use in this funnel at the given field version: every field registered with FieldsService for that version, plus, for version 1 only, any extra fields defined on the given funnel.
| Parameter | Description |
|---|---|
f | the funnel whose extra fields should be included; may be null |
version | the field version to look up (see FieldsService) |
extraFieldMeta(Funnel f, String fieldId)
Returns: ExtraField
Finds the metadata for an extra field, first checking the funnel's own extra field definitions and falling back to FunnelFieldsHelper's built-in field metadata.
| Parameter | Description |
|---|---|
f | the funnel whose extra fields should be searched |
fieldId | the field name to find metadata for |
findFieldValue(String fieldId, Lead lead, Funnel f)
Returns: Object
Evaluates the value of a field for the given lead: a kcode template, a registered Field, a FunnelFieldsHelper built-in field, or one of the funnel's extra fields, in that order.
| Parameter | Description |
|---|---|
fieldId | the field id, kcode expression, or field name to evaluate |
lead | the lead to evaluate the field against |
f | the lead's funnel, used to resolve extra fields |
loadRules(String source)
Returns: Rules
Parses a query builder rules definition from JSON source, via the funnel cache.
| Parameter | Description |
|---|---|
source | the JSON source of the rules to parse |
getScoringFactorTypes()
Returns: Map<String,EngagementScoringFactorType>
The engagement scoring factor types available for use in journeys, as registered with LeadScoringService.
getEngagementScore(Lead lead)
Returns: Float
The lead's already-calculated engagement score. Does not recalculate the score; use calcEngagementScore to compute a fresh value.
| Parameter | Description |
|---|---|
lead | the lead whose stored engagement score should be read |
calcEngagementScore(Lead lead)
Returns: Pair<Float,String>
Calculates the lead's engagement score from scratch, based on its funnel's scoring factors.
| Parameter | Description |
|---|---|
lead | the lead to calculate the engagement score for |
recalcAllEngagementScores(Consumer<String> progressCallback)
Returns: void
Recalculates the engagement scores of every active lead in every funnel in the current tenant organisation, reporting progress as it goes.
| Parameter | Description |
|---|---|
progressCallback | called with a human-readable progress message before each funnel repository is processed |
recalcEngagementScores(FunnelRepository repo, Consumer<String> progressCallback)
Returns: void
Recalculates the engagement scores of every active lead in the given funnel repository, reporting progress as it goes.
| Parameter | Description |
|---|---|
repo | the funnel repository whose leads' engagement scores should be recalculated |
progressCallback | called with a human-readable progress message before each lead is processed |
countOfLeadsToStart(Funnel funnel, String startNode)
Returns: int
Counts how many leads would be started if startLeads were called now for the given manual-initiation begin node, without actually creating any leads. Returns 0 if startNode is not a begin node leading to a ManualInitiationNode.
| Parameter | Description |
|---|---|
funnel | the funnel containing the begin node |
startNode | the id of the begin node to check |
profilesToStart(Funnel funnel, String startNode)
Returns: Set<Profile>
Finds which profiles would have a lead started for them if startLeads were called now for the given manual-initiation begin node, without actually creating any leads. Returns null if startNode is not a begin node leading to a ManualInitiationNode.
| Parameter | Description |
|---|---|
funnel | the funnel containing the begin node |
startNode | the id of the begin node to check |
startLeads(Funnel funnel, String startNode)
Returns: int
Starts a lead for every matching profile at the given manual-initiation begin node. Equivalent to calling startLeads(funnel, startNode, null).
| Parameter | Description |
|---|---|
funnel | the funnel containing the begin node |
startNode | the id of the begin node to start leads from |
startLeads(Funnel funnel, String startNode, List<Long> startProfileIds)
Returns: int
Starts a lead for every matching profile at the given manual-initiation begin node, optionally restricted to a specific set of profiles. Skips a profile if it already has an existing lead and the begin node only allows one lead per profile. Does nothing and returns 0 if startNode is not a begin node leading to a ManualInitiationNode.
| Parameter | Description |
|---|---|
funnel | the funnel containing the begin node |
startNode | the id of the begin node to start leads from |
startProfileIds | if given, only profiles whose id is in this list are started; null starts every matching profile |
getNonHiddenFunnels()
Returns: Map<String,Funnel>
All funnels in the current tenant organisation whose "hidden to sales" flag is not set, sorted by name.
getFunnelExtraFields(String journeyName)
Returns: List<ExtraField>
Finds the extra fields defined on the non-hidden funnel with the given name, in the current tenant organisation.
| Parameter | Description |
|---|---|
journeyName | the funnel name to match |
getFunnelTriggerTypes()
Returns: List<FunnelTriggerType>
The trigger types available for use in journey automations, collected from every active JourneyBuilderApplication.
findAvailOutcomes(Task task)
Returns: List<TaskOutcome>
Finds the possible outcomes for the task goal that the given task belongs to.
| Parameter | Description |
|---|---|
task | the task to find outcomes for; may be null |
getFunnelActionTypes()
Returns: List<FunnelActionType>
The action types available for use in journey automations, collected from every active JourneyBuilderApplication.
setFieldValue(Lead leadToUpdate, String fieldName, Object value)
Returns: void
Sets a field value on the lead, using the current Hibernate session. Equivalent to calling the static setFieldValue(leadToUpdate, fieldName, value, session).
| Parameter | Description |
|---|---|
leadToUpdate | the lead to update |
fieldName | the field name to set |
value | the value to set; if blank, this method does nothing |
countActiveLeads(FunnelRepository funnelRepository)
Returns: long
Counts the active (not closed, cancelled or deleted) leads in the given funnel repository.
| Parameter | Description |
|---|---|
funnelRepository | the funnel repository to count leads for |
© 2025 Kademi Ltd