# AsyncJobManager

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.

Package: `io.milton.cloud.server.queue.impl`  
Group: Managers  

## Methods

### `searchInJob(AsyncJob asyncJob, String search)`

Returns: List<[JobSearchHit](JobSearchHit.md)>

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](AsyncJob.md)>

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](AsyncJob.md)>

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](AsyncJob.md)>

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](AsyncJob.md)>

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](AsyncJob.md)>

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](AsyncJob.md)>

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](AsyncJob.md)

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](JsSchedule.md)>

Finds all scheduled jobs (JsSchedule) configured for the current tenant organisation.

### `findSchedules(SearchProperties properties)`

Returns: List<[JsSchedule](JsSchedule.md)>

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](JsSchedule.md)

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](AsyncJob.md)

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](AsyncJob.md)>

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](AsyncJob.md)>

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](AsyncJob.md)>

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](AsyncJob.md)>

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](AsyncJob.md)

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](AuditItem.md)>

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](AsyncJob.md)

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](AsyncJob.md)

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](AsyncJob.md)

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](AsyncJob.md)

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](AsyncJob.md)

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 |