To get full access to the Kademi Hub existing customers can login here, or new customers can register here.
Manages the lifecycle of background AsyncJob tasks across the platform: submitting new JS and map/reduce jobs to the queue, finding and searching existing jobs, restarting or cancelling them, and reading their logs and output. Reached from JS as the registered service "asyncJobManager". Most read methods are scoped to the current tenant organisation, and the write methods are used by both scheduled jobs (JsSchedule) and on-demand admin actions.
Group: Managers
Methods
searchInJob(AsyncJob asyncJob, String search) · updateJob(AsyncJob job) · cancel(AsyncJob asyncJob) · findActiveJobs() · findActiveJobs(SearchProperties searchProperties) · findActiveJobs(String searchText, SearchProperties searchProperties) · findJobs(Date fromDate, Date toDate) · findJobs(Date fromDate, Date toDate, SearchProperties searchProperties) · findJobs(String searchText, Date fromDate, Date toDate, SearchProperties searchProperties) · countJobs(Date fromDate, Date toDate, boolean activeOnly) · countJobs(String searchText, Date fromDate, Date toDate, boolean activeOnly) · sumJobDurationSecs(Date startDate, Date finishDate) · job(Long jobId) · findSchedules() · findSchedules(SearchProperties properties) · countSchedules() · getSchedule(Long id) · calcNextDueDate(JsSchedule sched) · getJsTimeUnit(String unit) · findJobByTaskName(String taskName) · findJobsByTaskName(String taskName) · findJobsByTaskName(String taskName, Date start, Date finish, SearchProperties props) · findJobsByProfile(Profile runProfile, String taskName) · findJobsByProfile(Profile runProfile, String taskName, Date start, Date finish, SearchProperties props) · runExport(String taskName, MapReduceExporter e) · restart(AsyncJob j) · findDescription(AsyncJob j) · isMapReduce(AsyncJob j) · runAsNew(AsyncJob j) · countOfIncompleteTasks() · countOfIncompleteRootTasks() · listAuditItems(AsyncJob j, SearchProperties props) · listJobLogs(AsyncJob job) · listJobLogs(AsyncJob job, String level) · newAsyncTask(String appId, String description, String jsFunction, Map<String,Serializable> params, Branch branch, Profile runBy, Profile runAs) · newMapReduceTask(String appId, String mapFn, String reduceFn, Map<String,Serializable> params, Branch branch, Profile runBy, Profile runAs) · newMapReduceTask(String appId, String mapFn, String reduceFn, Map<String,Serializable> params, String appHash, Profile runBy, Profile runAs) · newMapReduceTask(String appId, String mapFn, String reduceFn, String onMappedCompleteFn, Map<String,Serializable> params, String appHash, Profile runBy, Profile runAs) · newMapReduceTask(String appId, String mapFn, String reduceFn, String onMappedCompleteFn, Map<String,Serializable> params, String appHash, Profile runBy, Profile runAs, String taskName) · canAccessJob(AsyncJob j)
searchInJob(AsyncJob asyncJob, String search)
Returns: List<JobSearchHit>
Searches the given job's input, output and log lines, and recursively its sub jobs, for text matching the given search expression.
| Parameter | Description |
|---|---|
asyncJob | the job to search, including its sub jobs |
search | a search expression parsed by KSearchQuery, supporting must and must-not terms |
updateJob(AsyncJob job)
Returns: void
Saves the given job's current state to the database and flushes the change immediately.
| Parameter | Description |
|---|---|
job | the job to persist |
cancel(AsyncJob asyncJob)
Returns: void
Cancels the given job and, recursively, all of its sub jobs. Has no effect if the job is already cancelled or has already completed.
| Parameter | Description |
|---|---|
asyncJob | the job to cancel |
findActiveJobs()
Returns: List<AsyncJob>
Finds the root (non sub-job) jobs for the current tenant organisation that are still active, i.e. neither cancelled nor completed.
findActiveJobs(SearchProperties searchProperties)
Returns: List<AsyncJob>
Finds the root (non sub-job) jobs for the current tenant organisation that are still active, i.e. neither cancelled nor completed, with paging and sorting applied.
| Parameter | Description |
|---|---|
searchProperties | paging, sorting and filtering options, or null to use the defaults |
findActiveJobs(String searchText, SearchProperties searchProperties)
Returns: List<AsyncJob>
Finds the root (non sub-job) jobs for the current tenant organisation that are still active, i.e. neither cancelled nor completed, optionally filtered by search text.
| Parameter | Description |
|---|---|
searchText | free text to filter jobs by, or null to not filter |
searchProperties | paging, sorting and filtering options, or null to use the defaults |
findJobs(Date fromDate, Date toDate)
Returns: List<AsyncJob>
Finds the root (non sub-job) jobs for the current tenant organisation, active or not, that fall within the given date range.
| Parameter | Description |
|---|---|
fromDate | the earliest date to include, or null for no lower bound |
toDate | the latest date to include, or null for no upper bound |
findJobs(Date fromDate, Date toDate, SearchProperties searchProperties)
Returns: List<AsyncJob>
Finds the root (non sub-job) jobs for the current tenant organisation, active or not, that fall within the given date range, with paging and sorting applied.
| Parameter | Description |
|---|---|
fromDate | the earliest date to include, or null for no lower bound |
toDate | the latest date to include, or null for no upper bound |
searchProperties | paging, sorting and filtering options, or null to use the defaults |
findJobs(String searchText, Date fromDate, Date toDate, SearchProperties searchProperties)
Returns: List<AsyncJob>
Finds the root (non sub-job) jobs for the current tenant organisation, active or not, that fall within the given date range and optionally match the given search text.
| Parameter | Description |
|---|---|
searchText | free text to filter jobs by, or null to not filter |
fromDate | the earliest date to include, or null for no lower bound |
toDate | the latest date to include, or null for no upper bound |
searchProperties | paging, sorting and filtering options, or null to use the defaults |
countJobs(Date fromDate, Date toDate, boolean activeOnly)
Returns: Long
Counts the root jobs for the current tenant organisation within the given date range.
| Parameter | Description |
|---|---|
fromDate | the earliest date to include, or null for no lower bound |
toDate | the latest date to include, or null for no upper bound |
activeOnly | if true, only count jobs that are neither cancelled nor completed |
countJobs(String searchText, Date fromDate, Date toDate, boolean activeOnly)
Returns: Long
Counts the root jobs for the current tenant organisation within the given date range, optionally matching the given search text.
| Parameter | Description |
|---|---|
searchText | free text to filter jobs by, or null to not filter |
fromDate | the earliest date to include, or null for no lower bound |
toDate | the latest date to include, or null for no upper bound |
activeOnly | if true, only count jobs that are neither cancelled nor completed |
sumJobDurationSecs(Date startDate, Date finishDate)
Returns: long
Sums the effective duration, in seconds, of all root jobs for the current tenant organisation that were created within the given date range.
| Parameter | Description |
|---|---|
startDate | the earliest creation date to include, or null for no lower bound |
finishDate | the latest creation date to include (exclusive), or null for no upper bound |
job(Long jobId)
Returns: AsyncJob
Looks up a single job by its ID, refreshed from the database, scoped to the current tenant organisation.
| Parameter | Description |
|---|---|
jobId | the ID of the job to look up |
findSchedules()
Returns: List<JsSchedule>
Finds all scheduled jobs (JsSchedule) configured for the current tenant organisation.
findSchedules(SearchProperties properties)
Returns: List<JsSchedule>
Finds the scheduled jobs (JsSchedule) configured for the current tenant organisation, with paging and sorting applied.
| Parameter | Description |
|---|---|
properties | paging, sorting and filtering options, or null to use the defaults |
countSchedules()
Returns: Long
Counts the scheduled jobs (JsSchedule) configured for the current tenant organisation.
getSchedule(Long id)
Returns: JsSchedule
Looks up a single scheduled job (JsSchedule) by its ID, scoped to the current tenant organisation.
| Parameter | Description |
|---|---|
id | the ID of the schedule |
calcNextDueDate(JsSchedule sched)
Returns: Date
Calculates when the given schedule is next due to run, based on its configured interval and last run time. If the calculated date has already passed, it is pushed forward by one day to avoid returning a past due date.
| Parameter | Description |
|---|---|
sched | the schedule to calculate the next due date for |
getJsTimeUnit(String unit)
Returns: TimeUnit
Parses a time unit name, case insensitive, into the matching JsSchedule.TimeUnit enum constant.
| Parameter | Description |
|---|---|
unit | the time unit name, e.g. "days" or "hours" |
findJobByTaskName(String taskName)
Returns: AsyncJob
Finds the most recently created job with the given task name for the current tenant organisation.
| Parameter | Description |
|---|---|
taskName | the task name to search for |
findJobsByTaskName(String taskName)
Returns: List<AsyncJob>
Finds all jobs with the given task name for the current tenant organisation.
| Parameter | Description |
|---|---|
taskName | the task name to search for |
findJobsByTaskName(String taskName, Date start, Date finish, SearchProperties props)
Returns: List<AsyncJob>
Finds jobs with the given task name for the current tenant organisation, within the given date range, with paging and sorting applied.
| Parameter | Description |
|---|---|
taskName | the task name to search for |
start | the earliest date to include, or null for no lower bound |
finish | the latest date to include, or null for no upper bound |
props | paging, sorting and filtering options, or null to use the defaults |
findJobsByProfile(Profile runProfile, String taskName)
Returns: List<AsyncJob>
Finds all jobs with the given task name that were run as the given profile, for the current tenant organisation.
| Parameter | Description |
|---|---|
runProfile | the profile the jobs were run as |
taskName | the task name to search for |
findJobsByProfile(Profile runProfile, String taskName, Date start, Date finish, SearchProperties props)
Returns: List<AsyncJob>
Finds jobs with the given task name that were run as the given profile, for the current tenant organisation, within the given date range, with paging and sorting applied.
| Parameter | Description |
|---|---|
runProfile | the profile the jobs were run as |
taskName | the task name to search for |
start | the earliest date to include, or null for no lower bound |
finish | the latest date to include, or null for no upper bound |
props | paging, sorting and filtering options, or null to use the defaults |
runExport(String taskName, MapReduceExporter e)
Returns: long
Submits a map/reduce export task to the job queue for background execution and records a telemetry event for the export.
| Parameter | Description |
|---|---|
taskName | the task name to record against the created job |
e | the exporter implementation that performs the map and reduce steps |
restart(AsyncJob j)
Returns: void
Resets a job so it can run again: clears its cancelled, completed and taken dates, its warnings and output, and removes any AsyncJobStatus and sub jobs it had. This is not normally needed, since the processor already has an explicit check to prevent a completed job being run twice.
| Parameter | Description |
|---|---|
j | the job to reset |
findDescription(AsyncJob j)
Returns: String
Finds a human readable description of the given job by looking up its underlying processable implementation.
| Parameter | Description |
|---|---|
j | the job to describe |
isMapReduce(AsyncJob j)
Returns: boolean
Checks whether the given job's underlying processable implementation is a map/reduce task.
| Parameter | Description |
|---|---|
j | the job to check |
runAsNew(AsyncJob j)
Returns: AsyncJob
Creates a new job that copies the given job's task name, input, priority, run-as and run-by profiles and cluster version, ready to be picked up and executed. The new job has no parent, even if the original job did.
| Parameter | Description |
|---|---|
j | the job to copy |
countOfIncompleteTasks()
Returns: long
Counts the incomplete (so queued or running) jobs across the entire platform, not scoped to a tenant organisation.
countOfIncompleteRootTasks()
Returns: long
Counts the incomplete (so queued or running) root jobs, i.e. excluding sub jobs, across the entire platform, not scoped to a tenant organisation.
listAuditItems(AsyncJob j, SearchProperties props)
Returns: List<AuditItem>
Finds the audit items that were generated by the given job, matched by the job's organisation, task name and ID.
| Parameter | Description |
|---|---|
j | the job to find audit items for |
props | paging, sorting and filtering options, or null to use the defaults |
listJobLogs(AsyncJob job)
Returns: List<String>
Reads all of the log lines stored for the given job.
| Parameter | Description |
|---|---|
job | the job to read logs for |
listJobLogs(AsyncJob job, String level)
Returns: List<String>
Reads the log lines stored for the given job, optionally filtered to a minimum severity level.
| Parameter | Description |
|---|---|
job | the job to retrieve logs for |
level | the minimum severity to include: INFO, WARN or ERROR; INFO or null includes every line |
newAsyncTask(String appId, String description, String jsFunction, Map<String,Serializable> params, Branch branch, Profile runBy, Profile runAs)
Returns: AsyncJob
Submits a JS function as a background task to the job queue, to be executed asynchronously.
| Parameter | Description |
|---|---|
appId | the ID of the app the JS function belongs to |
description | a human readable description of the task, shown against the job |
jsFunction | the name of the JS function to invoke |
params | the parameters to pass to the JS function |
branch | the branch of the app to run the function in, or null to run the current live version in the tenant organisation |
runBy | the profile the job is recorded as run by, or the current user if null |
runAs | the profile the job's JS function executes as, or the current user if null |
newMapReduceTask(String appId, String mapFn, String reduceFn, Map<String,Serializable> params, Branch branch, Profile runBy, Profile runAs)
Returns: AsyncJob
Submits a JS map/reduce task to the job queue, resolving the given branch to its current head hash before delegating to the hash-based overload.
| Parameter | Description |
|---|---|
appId | the name of the app invoking the process |
mapFn | the name of the JS map function to invoke for each sub task |
reduceFn | the name of the JS reduce function to invoke once all sub tasks complete |
params | the parameters to pass to the map function |
branch | the branch of the app the functions will be run inside |
runBy | the profile the job is recorded as run by, or the current user if null |
runAs | the profile the job's JS functions execute as, or the current user if null |
newMapReduceTask(String appId, String mapFn, String reduceFn, Map<String,Serializable> params, String appHash, Profile runBy, Profile runAs)
Returns: AsyncJob
Submits a JS map/reduce task to the job queue, to be executed asynchronously across one sub task per mapped item.
| Parameter | Description |
|---|---|
appId | the name of the app invoking the process |
mapFn | the name of the JS map function to invoke for each sub task |
reduceFn | the name of the JS reduce function to invoke once all sub tasks complete |
params | the parameters to pass to the map function |
appHash | the hash of the repo to run the functions in, normally provided from controllerMappings.hash |
runBy | the profile the job is recorded as run by, or the current user if null |
runAs | the profile the job's JS functions execute as, or the current user if null |
newMapReduceTask(String appId, String mapFn, String reduceFn, String onMappedCompleteFn, Map<String,Serializable> params, String appHash, Profile runBy, Profile runAs)
Returns: AsyncJob
Submits a JS map/reduce task to the job queue, with an additional callback function invoked once all mapped sub tasks complete but before the reduce step runs.
| Parameter | Description |
|---|---|
appId | the name of the app invoking the process |
mapFn | the name of the JS map function to invoke for each sub task |
reduceFn | the name of the JS reduce function to invoke once all sub tasks complete |
onMappedCompleteFn | the name of the JS function to invoke once all mapped sub tasks complete, or null to skip this step |
params | the parameters to pass to the map function |
appHash | the hash of the repo to run the functions in, normally provided from controllerMappings.hash |
runBy | the profile the job is recorded as run by, or the current user if null |
runAs | the profile the job's JS functions execute as, or the current user if null |
newMapReduceTask(String appId, String mapFn, String reduceFn, String onMappedCompleteFn, Map<String,Serializable> params, String appHash, Profile runBy, Profile runAs, String taskName)
Returns: AsyncJob
Submits a JS map/reduce task to the job queue under an explicit task name, with an additional callback function invoked once all mapped sub tasks complete but before the reduce step runs.
| Parameter | Description |
|---|---|
appId | the name of the app invoking the process |
mapFn | the name of the JS map function to invoke for each sub task |
reduceFn | the name of the JS reduce function to invoke once all sub tasks complete |
onMappedCompleteFn | the name of the JS function to invoke once all mapped sub tasks complete, or null to skip this step |
params | the parameters to pass to the map function |
appHash | the hash of the repo to run the functions in, normally provided from controllerMappings.hash |
runBy | the profile the job is recorded as run by, or the current user if null |
runAs | the profile the job's JS functions execute as, or the current user if null |
taskName | the task name to record against the created job, defaults to "js-exec" if blank |
canAccessJob(AsyncJob j)
Returns: boolean
Checks whether the current user can access the given job: administrators can access any job, and any other user can access a job that has no run-by profile recorded, or one they ran themselves.
| Parameter | Description |
|---|---|
j | the job to check |
© 2025 Kademi Ltd