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)

Source:

Create job instance

Parameters:
Name Type Description
name string

name of the job

data object

data about the job

Members

_id

Source:

Get job id

canRun

Source:

Check if job is running

channel

Source:

Get job channel

data

Source:

Get job data

id

Source:

Get job id with fallback

isAborted

Source:

Check if job was aborted

isCompleted

Source:

Check if job is completed

name

Source:

Get job name

next

Source:

Get next run time

scheduleObj

Source:

Get schedule object

status

Source:

Get job status

strict

Source:

Get strict schedule value

Methods

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

Source:

Read multiple jobs

Parameters:
Name Type Description
db object

database connection

match object

query for jobs

Returns:

promise

Type
Promise

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

Source:

Insert new job

Parameters:
Name Type Description
db object

database connection

data object

job document to insert

Returns:

promise

Type
Promise

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

Source:

Read job

Parameters:
Name Type Description
db object

database connection

id string

id of the job

Returns:

promise

Type
Promise

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

Source:

Update job

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}

Source:

Update job atomically

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}

Source:

Update multiple jobs

Parameters:
Name Type Description
db object

database connection

match object

query for job

update object

update query for job

Returns:

promise

Type
Promise

_abort(err) → {Promise}

Source:

Abort job

Parameters:
Name Type Description
err Error

error with which to abort

Returns:

promise

Type
Promise

_finish(erropt) → {Promise}

Source:

Finish job

Parameters:
Name Type Attributes Description
err Error <optional>

error with which to finish

Returns:

promise

Type
Promise

(async) _replaceAll(next) → {object}

Source:

Replace all jobs

Parameters:
Name Type Description
next number

timestamp

Returns:

job data

Type
object

_run() → {Promise}

Source:

Internal run function for managing states

Returns:

promise

Type
Promise

_runWithRetries() → {Promise}

Source:

Run job with retry policy applied

Returns:

promise

Type
Promise

(async) _save(set) → {object}

Source:

Save job

Parameters:
Name Type Description
set boolean

if should update instead of creating

Returns:

job data

Type
object

cancel() → {Promise}

Source:

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).

Returns:

promise

Type
Promise

db() → {object}

Source:

Get database connection

Returns:

db

Type
object

getConcurrency() → {number}

Source:

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

Returns:

concurrency

Type
number

in(seconds) → {object}

Source:

Run job in providd amount of seconds

Parameters:
Name Type Description
seconds number

after how many seconds to run the job

Returns:

result of saving job

Type
object

now() → {object}

Source:

Run job now

Returns:

result of saving job

Type
object

once(date, strict) → {object}

Source:

Run job once

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}

Source:

Override if job needs a manager instance to run

Returns:

promise

Type
Promise

replace() → {object}

Source:

Replace existing job if, it exists

Returns:

self

Type
object

replaceAfter(next, queror) → {Promise}

Source:

Replace jobs that will run after provided timestamp

Parameters:
Name Type Description
next number

timestamp

queror function

function which modifies query request

Returns:

promise

Type
Promise

retryPolicy() → {RetryPolicy}

Source:

Override if default policy isn't good enough

Returns:

retry policy

Type
RetryPolicy

run()

Source:

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

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

Source:

Schedule job

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