Docs Developer Site
Developer Docs Enonic Development Kit next Libraries Scheduler library

Scheduler library

Contents

Functions for creating and managing scheduled jobs.

Usage

Add the following to your build.gradle file:

dependencies {
  include xplibs.scheduler
}

Add the import statement to your code:

import schedulerLib from '/lib/xp/scheduler';

You are now ready to use the API.

Functions

get

Returns a scheduled job with the specified name.

Parameters

get() takes a single params object with these properties:

Name Type Description

name

string

Name of the job.

Returns

object : (ScheduledJob) Detail information for the job. Or null if the job could not be found.

Example

Obtains details of a scheduled job:
import {get as getJob} from '/lib/xp/scheduler';

const job = getJob({ name: 'myjob' });

if (job) {
  log.info('Job is found: %s', JSON.stringify(job, null, 4));
} else {
  log.info('Job not found');
}
Return value:
const expected = {
    name: 'myjob',
    descriptor: 'com.enonic.app.myapp:mytask',
    description: 'cron job description',
    enabled: true,
    config: {
        a: 1,
        b: 'value',
        c: {
            d: {
                e: 3.6,
                f: true
            }
        }
    },
    user: 'user:system:user',
    creator: 'user:system:creator',
    modifier: 'user:system:creator',
    createdTime: '2016-11-02T10:36:00Z',
    modifiedTime: '2016-11-02T10:36:00Z',
    lastRun: '2021-02-25T10:44:33.170079900Z',
    lastTaskId: 'task-id',
    schedule: {
        value: '* * * * *',
        type: 'CRON',
        timeZone: 'GMT+2:00'
    }
};

list

Returns the list of scheduled jobs.

Returns

Array : (ScheduledJob[]) List of all scheduled jobs.

Example

Obtains list of existing jobs:
import {list} from '/lib/xp/scheduler';

const jobs = list();
Return value:
const expected = [
  {
        name: 'job1',
        descriptor: 'appKey:task',
        description: 'job description',
        enabled: true,
        config: {
            a: 1
        },
        user: 'user:system:user',
        creator: 'user:system:creator',
        modifier: 'user:system:creator',
        createdTime: '2016-11-02T10:36:00Z',
        modifiedTime: '2016-11-02T10:36:00Z',
        lastRun: '2021-02-25T10:44:00.170079900Z',
        lastTaskId: 'task-id',
        schedule: {
            value: '* * * * *',
            timeZone: 'GMT+05:30',
            type: 'CRON'
        }
    },
    {
        name: 'job2',
        descriptor: 'appKey:task',
        description: 'job description',
        enabled: false,
        config: { },
        user: 'user:system:user',
        creator: 'user:system:creator',
        modifier: 'user:system:creator',
        createdTime: '2021-02-02T10:36:00Z',
        modifiedTime: '2021-02-02T10:36:00Z',
        schedule: {
            value: '2012-01-01T00:00:00Z',
            type: 'ONE_TIME'
        }
    }
];

create

Creates a scheduled job.

This function returns immediately.

Parameters

create() takes a single params object with these properties:

Name Type Description

name

string

Unique job name.

description

string

Optional. Job description.

descriptor

string

Descriptor of the task to be scheduled.

config

object

Optional. Config passed to the scheduled task.

schedule

Schedule

When the task runs.

user

string

Optional. Principal key of the user that submitted the task.

enabled

boolean

Whether the job is active.

Returns

object : (ScheduledJob) Detail information for the created job.

Example

import {create} from '/lib/xp/scheduler';

const simpleOneTimeJob = create({
    name: 'my-project',
    descriptor: 'appKey:task',
    enabled: true,
    schedule: {type: 'ONE_TIME', value: '2012-01-01T00:00:00.00Z'}
});

const extendedCronJob = create({
    name: 'myjob',
    descriptor: 'appKey:task',
    description: 'job description',
    user: 'user:system:user',
    enabled: true,
    config: {
        a: 1,
        b: 2,
        c: ['1', '2'],
        d: {
            e: {
                f: 3.6,
                g: true
            }
        }
    },
    schedule: {type: 'CRON', value: '* * * * 5', timeZone: 'GMT-2:00'}
});

// runs every five minutes, measured from the start of the previous run
const fixedRateJob = create({
    name: 'poll-feed',
    descriptor: 'appKey:task',
    enabled: true,
    schedule: {type: 'FIXED_RATE', value: 'PT5M'}
});

// runs once, then removes itself - the name is used for this occasion only
const requestId = '018f3c2a-6b1e-7a44-9c3d-5e2f1a0b8c71';

const ephemeralJob = create({
    name: `publish-${requestId}`,
    descriptor: 'appKey:publish',
    enabled: true,
    config: {contentId: 'e1f2a3b4-c5d6-4789-a012-3b4c5d6e7f80'},
    schedule: {type: 'ONE_TIME', value: '2038-01-01T00:00:00.00Z', deleteAfterRun: true}
});
Return value:
const expectedSimpleOneTimeJob = {
    name: 'my-project',
    descriptor: 'appKey:task',
    enabled: true,
    config: {},
    creator: 'user:system:creator',
    modifier: 'user:system:creator',
    createdTime: '2016-11-02T10:36:00Z',
    modifiedTime: '2016-11-02T10:36:00Z',
    schedule: {
        value: '2012-01-01T00:00:00Z',
        type: 'ONE_TIME'
    }
}

const expectedExtendedCronJob = {
    name: 'myjob',
    descriptor: 'appKey:task',
    description: 'job description',
    enabled: true,
    config: {
        a: 1,
        b: 2,
        c: ['1', '2'],
        d: {
            e: {
                f: 3.6,
                g: true
            }
        }
    },
    user: 'user:system:user',
    creator: 'user:system:creator',
    modifier: 'user:system:creator',
    createdTime: '2016-11-02T10:36:00Z',
    modifiedTime: '2016-11-02T10:36:00Z',
    schedule: {
        value: '* * * * 5',
        timeZone: 'GMT-02:00',
        type: 'CRON'
    }
}

modify

Modifies a job.

The previous task will be rescheduled, lastRun and lastTaskId properties will be cleaned.

Parameters

modify() takes a single params object with these properties:

Name Type Description

name

string

Unique job name.

editor

function

Editor callback. Receives the existing job as an editable object and returns it. See the example.

Returns

object : (ScheduledJob) Detail information for the modified job.

Example

import {modify} from '/lib/xp/scheduler';

const result = modify({
    name: 'myjob',
    editor: (edit) => {
        edit.descriptor = 'appKey:new-task';
        edit.description = 'new job description';
        edit.user = 'user:system:new-user';
        edit.enabled = false;
        edit.config = {
            a1: 3
        };
        edit.schedule = {type: 'CRON', value: '* * * * *', timeZone: 'GMT+5:30'};

        return edit;
    }
});
Return value:
const resultExpected = {
    name: 'myjob',
    descriptor: 'appKey:new-task',
    description: 'new job description',
    enabled: false,
    config: {
        a1: 3
    },
    user: 'user:system:new-user',
    creator: 'user:system:creator',
    modifier: 'user:system:modifier',
    createdTime: '2016-11-02T10:36:00Z',
    modifiedTime: '2021-02-25T10:44:33.170079900Z',
    schedule: {
        value: '* * * * *',
        timeZone: 'GMT+05:30',
        type: 'CRON'
    }
}

deleteJob

Deletes a scheduled job.

Renamed from delete to avoid the JavaScript reserved word. The old delete export is still available for backward compatibility.

Parameters

deleteJob() takes a single params object with these properties:

Name Type Description

name

string

Name of the job to delete.

Returns

boolean : true if deleted, false otherwise

Example

import {deleteJob} from '/lib/xp/scheduler';

const result = deleteJob({
    name: 'myjob'
});

if (result) {
    log.info('Job deleted');
} else {
    log.info('Job was not found');
}

Type Definitions

ScheduledJob

Type

object

Properties

Name Type Description

name

string

Job name.

description

string

Job description.

descriptor

string

Descriptor of the scheduled task.

config

object

Config passed to the scheduled task.

schedule

Schedule

When the task runs.

user

string

Principal key of the user that submitted the task.

enabled

boolean

Whether the job is active.

creator

string

Principal key of the user that created the task.

modifier

string

Principal key of the last user that modified the task.

createdTime

string

Time of the task creation.

modifiedTime

string

Time of the last task modification.

lastRun

string

Time of the last job run.

lastTaskId

string

Task id of the last job run.

Schedule

Properties

Name Type Description

value

string

Schedule value, in the format required by type.

type

string

Schedule type: CRON, ONE_TIME, or XPXP8.1.08.1.0 FIXED_RATE.

timeZone

string

Time zone of the cron schedule. Required when type is CRON; not applicable to the other types.

deleteAfterRun

boolean

XPXP8.1.08.1.0 Optional. Whether the job deletes itself once its task has been submitted. Only applicable when type is ONE_TIME. Defaults to false.

The three types take different value formats, and behave differently once the job has run:

CRON

A UNIX cron expression, run repeatedly at the calendar positions it names — '* * * * 5' for every minute on Fridays. timeZone decides which day and hour those positions fall on.

ONE_TIME

An ISO instant in UTC, run once. A time already in the past runs as soon as the job is created. The job stays afterwards, with lastRun recording that it is done, unless deleteAfterRun is set.

FIXED_RATE

XPXP8.1.08.1.0 An ISO-8601 duration — 'PT5M' for every five minutes — measured from when the previous run started, not from when it finished. Use it for work that should repeat at an interval rather than at a time of day, where '*/5 * * * *' would tie the job to the clock.

Fixed rate and long-running tasks

What FIXED_RATE guarantees:

  • The interval is between the starts of two runs, not the gap between them.

  • A run that overruns its interval delays the next one rather than overlapping it, and the delayed run starts once its predecessor finishes.

  • Periods missed while a run overruns are not replayed, so an overrunning run shifts every later run along with it.

  • The interval is not anchored to a wall-clock position and does not survive a restart or a move to another node — the next run may shift by up to one interval. Use CRON where a run has to land at a particular time.

Not overlapping is best effort, not a guarantee: two runs of the same job can still overlap when the cluster is partitioned, or when the record of the previous task is no longer available to be checked. A task that must never run concurrently with itself needs a lock of its own.

Self-deleting one-time jobs

XPXP8.1.08.1.0 A one-time job stays after it has run, so its name cannot be reused to run it a second time. Where the name is used for a single occasion — a publish request keyed by a uuid, say — that serves no purpose and the finished jobs only accumulate; deleteAfterRun deletes the job instead.

What it guarantees:

  • The job is deleted once a task has been submitted for it — not when that task finishes, and not if the run never started.

  • A job whose submission failed is kept, with the failure recorded, so nothing is lost silently.

  • Deletion never causes a repeat run: a job that cannot be deleted is recorded as run instead.

Contents

Contents