Job

Job

Job superclass for all jobs. To add new job type you need to:

  1. Define job class which has to be single export from a node.js module. This module can be either in api/jobs folder (API job), or in a plugins/plugin/api/jobs folder (plugin job). Job name is assigned automatically to have the form of "[API or plugin name]:[job file name]".
  2. Schedule a job by running any of the following (replace 'api:clear' with your Job name from point 1 above):
    • require('api/parts/jobs').job('api:clear', {some: 'data'}).now() - to run the job ASAP.
    • require('api/parts/jobs').job('api:clear', {some: 'data'}).in(5) - to run the job in 5 seconds from now.
    • require('api/parts/jobs').job('api:clear', {some: 'data'}).once(new Date() or Date.now()) - to run the job on specified date.
    • require('api/parts/jobs').job('api:clear', {some: 'data'}).schedule("once in 2 hours") - to run the job on specified schedule, see https://bunkat.github.io/later/parsers.html#text for examples. NOTE! For most jobs, scheduling must be done either from master process, or from plugins.register("/master", ...) to eliminate multiple replacing on app start.
  3. Optionally set allowed concurrency (maximum running jobs of this type at any point in time) of the job by overriding getConcurrency method in your job class.
  4. Optionally allow the job to be divided by overriding divide in your job class. Resulted subjobs (or subs) will be run as separte jobs in parallel to improve performance.

There are 3 useful Job subclasses already implemented: ResourcefulJob is used when job requires some persistent resource to run on. Read - network connection, memory cache, etc. IPCJob which extends ResourcefulJob is used when resource needs to live in a separate from Countly master process. Example - push which runs a TransientJob which extends IPCJob is used when job shouldn't be saved in jobs collection with all status updates being run through IPC.

Constructor

new Job(name, data)

Description:

  • Create job instance

Source:
Parameters:
Name Type Description
name string

name of the job
data object

data about the job

Members

_id

Description:

  • Get job id

Source:

Get job id

canRun

Description:

  • Check if job is running

Source:

Check if job is running

channel

Description:

  • Get job channel

Source:

Get job channel

data

Description:

  • Get job data

Source:

Get job data

id

Description:

  • Get job id with fallback

Source:

Get job id with fallback

isAborted

Description:

  • Check if job was aborted

Source:

Check if job was aborted

isCompleted

Description:

  • Check if job is completed

Source:

Check if job is completed

name

Description:

  • Get job name

Source:

Get job name

next

Description:

  • Get next run time

Source:

Get next run time

scheduleObj

Description:

  • Get schedule object

Source:

Get schedule object

status

Description:

  • Get job status

Source:

Get job status

strict

Description:

  • Get strict schedule value

Source:

Get strict schedule value

Methods

_abort(err) → {Promise}

Description:

  • Abort job

Source:
Parameters:
Name Type Description
err Error

error with which to abort
Returns:

promise

Type
Promise

_finish(erropt) → {Promise}

Description:

  • Finish job

Source:
Parameters:
Name Type Attributes Description
err Error <optional>

error with which to finish
Returns:

promise

Type
Promise

(async) _replaceAll(next) → {object}

Description:

  • Replace all jobs

Source:
Parameters:
Name Type Description
next number

timestamp
Returns:

job data

Type
object

_run() → {Promise}

Description:

  • Internal run function for managing states

Source:
Returns:

promise

Type
Promise

_runWithRetries() → {Promise}

Description:

  • Run job with retry policy applied

Source:
Returns:

promise

Type
Promise

(async) _save(set) → {object}

Description:

  • Save job

Source:
Parameters:
Name Type Description
set boolean

if should update instead of creating
Returns:

job data

Type
object

cancel() → {Promise}

Description:

  • Override if job needs a graceful cancellation. Job is cancelled in two cases: 1. When server is restarted and last modification of the job was too long ago to consider it not running (becauseOfRestart = true). 2. When server was not running at the time strict job should have been run (becauseOfRestart = false).

Source:
Returns:

promise

Type
Promise

db() → {object}

Description:

  • Get database connection

Source:
Returns:

db

Type
object

getConcurrency() → {number}

Description:

  • Override if 0 doesn't work for this job: 0 = default = run jobs of this type on any number of servers, with any number of jobs running at the same time 1 ... N = run not more than N jobs of this time at the same time

Source:
Returns:

concurrency

Type
number

in(seconds) → {object}

Description:

  • Run job in providd amount of seconds

Source:
Parameters:
Name Type Description
seconds number

after how many seconds to run the job
Returns:

result of saving job

Type
object

now() → {object}

Description:

  • Run job now

Source:
Returns:

result of saving job

Type
object

once(date, strict) → {object}

Description:

  • Run job once

Source:
Parameters:
Name Type Description
date number | Date

date when to run
strict number

(optional) - maximum time in ms after scheduled date the job must be run, otherwise it'd be discarded
Returns:

result of saving job

Type
object

prepare() → {Promise}

Description:

  • Override if job needs a manager instance to run

Source:
Returns:

promise

Type
Promise

replace() → {object}

Description:

  • Replace existing job if, it exists

Source:
Returns:

self

Type
object

replaceAfter(next, queror) → {Promise}

Description:

  • Replace jobs that will run after provided timestamp

Source:
Parameters:
Name Type Description
next number

timestamp
queror function

function which modifies query request
Returns:

promise

Type
Promise

retryPolicy() → {RetryPolicy}

Description:

  • Override if default policy isn't good enough

Source:
Returns:

retry policy

Type
RetryPolicy

run()

Description:

  • Override in actual job class Takes 2 parameters omitted for the sake of ESLint: - db - db connection which must be used for this job in most cases, otherwise you're responsible for opening / closing an appropriate connection - done - function which must be called (when promise is not returned) when job processing is done with either no arguments or error string

Source:

schedule(schedule, strict, nextTime) → {object}

Description:

  • Schedule job

Source:
Parameters:
Name Type Description
schedule object

schedule object from later js
strict number

(optional) - maximum time in ms after each schedule occurrence date the job must be run, otherwise it'd be discarded
nextTime object

(optional) - next run time
Returns:

result of saving job

Type
object

(static) findMany(db, match) → {Promise}

Description:

  • Read multiple jobs

Source:
Parameters:
Name Type Description
db object

database connection
match object

query for jobs
Returns:

promise

Type
Promise

(static) insert(db, data) → {Promise}

Description:

  • Insert new job

Source:
Parameters:
Name Type Description
db object

database connection
data object

job document to insert
Returns:

promise

Type
Promise

(static) load(db, id) → {Promise}

Description:

  • Read job

Source:
Parameters:
Name Type Description
db object

database connection
id string

id of the job
Returns:

promise

Type
Promise

(static) update(db, match, update) → {Promise}

Description:

  • Update job

Source:
Parameters:
Name Type Description
db object

database connection
match object

query for job
update object

update query for job
Returns:

promise

Type
Promise

(static) updateAtomically(db, match, update, neoopt) → {Promise}

Description:

  • Update job atomically

Source:
Parameters:
Name Type Attributes Default Description
db object

database connection
match object

query for job
update object

update query for job
neo boolean <optional>
 true

should return new document
Returns:

promise

Type
Promise

(static) updateMany(db, match, update) → {Promise}

Description:

  • Update multiple jobs

Source:
Parameters:
Name Type Description
db object

database connection
match object

query for job
update object

update query for job
Returns:

promise

Type
Promise