# scheduler

(plugins.scheduler)

## Overview

The `scheduler` plugin enables the creation and management of background jobs; it is meant for usage in headless clients, but it does work for other clients as well. It supports both cron-based schedules and custom intervals, allowing for versatile task automation.

The `addCronJob` method schedules tasks using cron expressions, with options for specifying start and end dates, and passing arguments. This method is ideal for periodic tasks such as running jobs at specific times or intervals.

For more custom scheduling, the `addJob` method allows tasks to be scheduled at a specific start date with options for repetition intervals, counts, and end dates. Additional arguments can be passed to provide further flexibility in task execution.

To monitor jobs, the `getCurrentJobNames` method retrieves active jobs, and `getLastRunJobName` provides the most recently executed job. The `removeJob` method simplifies job management by enabling the deletion of specific tasks.

For more information, refer to the [Scheduler API](https://docs.servoy.com/guides/develop/programming-guide/automation-and-scheduling/scheduler-api) section of the documentation.

## Methods Summarized

| Type                                                                           | Name                                                                                                                                                                 | Summary                                      |
| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| void                                                                           | [addCronJob(jobname, cronTimings, method)](#addcronjob-jobname-crontimings-method)                                                                                   | Adds a cron job to the scheduler.            |
| void                                                                           | [addCronJob(jobname, cronTimings, method, startDate)](#addcronjob-jobname-crontimings-method-startdate)                                                              | Adds a cron job to the scheduler.            |
| void                                                                           | [addCronJob(jobname, cronTimings, method, startDate, endDate)](#addcronjob-jobname-crontimings-method-startdate-enddate)                                             | Adds a cron job to the scheduler.            |
| void                                                                           | [addCronJob(jobname, cronTimings, method, startDate, endDate, arguments)](#addcronjob-jobname-crontimings-method-startdate-enddate-arguments)                        | Adds a cron job to the scheduler.            |
| void                                                                           | [addJob(jobname, startDate, method)](#addjob-jobname-startdate-method)                                                                                               | Adds a job to the scheduler.                 |
| void                                                                           | [addJob(jobname, startDate, method, repeatInterval)](#addjob-jobname-startdate-method-repeatinterval)                                                                | Adds a job to the scheduler.                 |
| void                                                                           | [addJob(jobname, startDate, method, repeatInterval, repeatCount)](#addjob-jobname-startdate-method-repeatinterval-repeatcount)                                       | Adds a job to the scheduler.                 |
| void                                                                           | [addJob(jobName, startDate, method, repeatInterval, repeatCount, endDate)](#addjob-jobname-startdate-method-repeatinterval-repeatcount-enddate)                      | Adds a job to the scheduler.                 |
| void                                                                           | [addJob(jobname, startDate, method, repeatInterval, repeatCount, endDate, arguments)](#addjob-jobname-startdate-method-repeatinterval-repeatcount-enddate-arguments) | Adds a job to the scheduler.                 |
| void                                                                           | [addJob(jobname, startDate, method, arguments)](#addjob-jobname-startdate-method-arguments)                                                                          | Adds a job to the scheduler.                 |
| [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array)     | [getCurrentJobNames()](#getcurrentjobnames)                                                                                                                          | Returns an array with the current jobs.      |
| [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string)   | [getLastRunJobName()](#getlastrunjobname)                                                                                                                            | Returns the last job run from the scheduler. |
| [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) | [removeJob(jobname)](#removejob-jobname)                                                                                                                             | Removes a job from the scheduler.            |

## Methods Detailed

### addCronJob(jobname, cronTimings, method)

Adds a cron job to the scheduler. A cron job must have at least one minute between each execution (otherwise it won't execute).

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **jobname** ;
* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **cronTimings** ;
* [Function](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/function) **method** ;

**Returns:** void

**Sample**

```js
// see: http://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/tutorial-lesson-06.html for more info
// add a job that runs every 20 minutes after the hour (0,20,40)
plugins.scheduler.addCronJob('20mins','0 0/20 * * * ?',method)
// add a job that runs every day at 23:30 between now and 5 days from now
var dateNow = new Date();
var date5Days = new Date(dateNow.getTime()+5*24*60*60*1000);
plugins.scheduler.addCronJob('23:30','0 30 23 ? * *',method,dateNow,date5Days)
```

### addCronJob(jobname, cronTimings, method, startDate)

Adds a cron job to the scheduler. A cron job must have at least one minute between each execution (otherwise it won't execute).

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **jobname** ;
* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **cronTimings** ;
* [Function](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/function) **method** ;
* [Date](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/date) **startDate** ;

**Returns:** void

**Sample**

```js
// see: http://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/tutorial-lesson-06.html for more info
// add a job that runs every 20 minutes after the hour (0,20,40)
plugins.scheduler.addCronJob('20mins','0 0/20 * * * ?',method)
// add a job that runs every day at 23:30 between now and 5 days from now
var dateNow = new Date();
var date5Days = new Date(dateNow.getTime()+5*24*60*60*1000);
plugins.scheduler.addCronJob('23:30','0 30 23 ? * *',method,dateNow,date5Days)
```

### addCronJob(jobname, cronTimings, method, startDate, endDate)

Adds a cron job to the scheduler. A cron job must have at least one minute between each execution (otherwise it won't execute).

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **jobname** ;
* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **cronTimings** ;
* [Function](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/function) **method** ;
* [Date](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/date) **startDate** ;
* [Date](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/date) **endDate** ;

**Returns:** void

**Sample**

```js
// see: http://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/tutorial-lesson-06.html for more info
// add a job that runs every 20 minutes after the hour (0,20,40)
plugins.scheduler.addCronJob('20mins','0 0/20 * * * ?',method)
// add a job that runs every day at 23:30 between now and 5 days from now
var dateNow = new Date();
var date5Days = new Date(dateNow.getTime()+5*24*60*60*1000);
plugins.scheduler.addCronJob('23:30','0 30 23 ? * *',method,dateNow,date5Days)
```

### addCronJob(jobname, cronTimings, method, startDate, endDate, arguments)

Adds a cron job to the scheduler. A cron job must have at least one minute between each execution (otherwise it won't execute).

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **jobname** ;
* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **cronTimings** ;
* [Function](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/function) **method** ;
* [Date](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/date) **startDate** ;
* [Date](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/date) **endDate** ;
* [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) **arguments** ;

**Returns:** void

**Sample**

```js
// see: http://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/tutorial-lesson-06.html for more info
// add a job that runs every 20 minutes after the hour (0,20,40)
plugins.scheduler.addCronJob('20mins','0 0/20 * * * ?',method)
// add a job that runs every day at 23:30 between now and 5 days from now
var dateNow = new Date();
var date5Days = new Date(dateNow.getTime()+5*24*60*60*1000);
plugins.scheduler.addCronJob('23:30','0 30 23 ? * *',method,dateNow,date5Days)
```

### addJob(jobname, startDate, method)

Adds a job to the scheduler.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **jobname** ;
* [Date](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/date) **startDate** ;
* [Function](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/function) **method** ;

**Returns:** void

**Sample**

```js
// add a job that runs at the given date (20 seconds in the future)
// and repeats that every 20 seconds for 40 times or the enddate is reached (0 for no repeats = just one call)
var startDate = new Date();
startDate.setTime(startDate.getTime()+20000);
var endDate = new Date(startDate.getTime()+100000);
plugins.scheduler.addJob('in20seconds',startDate,method,20000,40,endDate)
```

### addJob(jobname, startDate, method, repeatInterval)

Adds a job to the scheduler.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **jobname** ;
* [Date](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/date) **startDate** ;
* [Function](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/function) **method** ;
* [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) **repeatInterval** ms

**Returns:** void

**Sample**

```js
// add a job that runs at the given date (20 seconds in the future)
// and repeats that every 20 seconds for 40 times or the enddate is reached (0 for no repeats = just one call)
var startDate = new Date();
startDate.setTime(startDate.getTime()+20000);
var endDate = new Date(startDate.getTime()+100000);
plugins.scheduler.addJob('in20seconds',startDate,method,20000,40,endDate)
```

### addJob(jobname, startDate, method, repeatInterval, repeatCount)

Adds a job to the scheduler.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **jobname** ;
* [Date](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/date) **startDate** ;
* [Function](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/function) **method** ;
* [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) **repeatInterval** ms
* [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) **repeatCount** ;

**Returns:** void

**Sample**

```js
// add a job that runs at the given date (20 seconds in the future)
// and repeats that every 20 seconds for 40 times or the enddate is reached (0 for no repeats = just one call)
var startDate = new Date();
startDate.setTime(startDate.getTime()+20000);
var endDate = new Date(startDate.getTime()+100000);
plugins.scheduler.addJob('in20seconds',startDate,method,20000,40,endDate)
```

### addJob(jobName, startDate, method, repeatInterval, repeatCount, endDate)

Adds a job to the scheduler.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **jobName** ;
* [Date](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/date) **startDate** ;
* [Function](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/function) **method** ;
* [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) **repeatInterval** ms
* [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) **repeatCount** ;
* [Date](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/date) **endDate** ;

**Returns:** void

**Sample**

```js
// add a job that runs at the given date (20 seconds in the future)
// and repeats that every 20 seconds for 40 times or the enddate is reached (0 for no repeats = just one call)
var startDate = new Date();
startDate.setTime(startDate.getTime()+20000);
var endDate = new Date(startDate.getTime()+100000);
plugins.scheduler.addJob('in20seconds',startDate,method,20000,40,endDate)
```

### addJob(jobname, startDate, method, repeatInterval, repeatCount, endDate, arguments)

Adds a job to the scheduler.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **jobname** ;
* [Date](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/date) **startDate** ;
* [Function](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/function) **method** ;
* [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) **repeatInterval** ms
* [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) **repeatCount** ;
* [Date](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/date) **endDate** ;
* [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) **arguments** ;

**Returns:** void

**Sample**

```js
// add a job that runs at the given date (20 seconds in the future)
// and repeats that every 20 seconds for 40 times or the enddate is reached (0 for no repeats = just one call)
var startDate = new Date();
startDate.setTime(startDate.getTime()+20000);
var endDate = new Date(startDate.getTime()+100000);
plugins.scheduler.addJob('in20seconds',startDate,method,20000,40,endDate)
```

### addJob(jobname, startDate, method, arguments)

Adds a job to the scheduler.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **jobname** ;
* [Date](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/date) **startDate** ;
* [Function](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/function) **method** ;
* [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) **arguments** ;

**Returns:** void

**Sample**

```js
// add a job that runs at the given date (20 seconds in the future)
// and repeats that every 20 seconds for 40 times or the enddate is reached (0 for no repeats = just one call)
var startDate = new Date();
startDate.setTime(startDate.getTime()+20000);
var endDate = new Date(startDate.getTime()+100000);
plugins.scheduler.addJob('in20seconds',startDate,method,20000,40,endDate)
```

### getCurrentJobNames()

Returns an array with the current jobs.

**Returns:** [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) an array of job names currently scheduled for the client.

**Sample**

```js
plugins.scheduler.getCurrentJobNames()
```

### getLastRunJobName()

Returns the last job run from the scheduler.

**Returns:** [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) the name of the last job that was run by the scheduler.

**Sample**

```js
plugins.scheduler.getLastRunJobName();
```

### removeJob(jobname)

Removes a job from the scheduler.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **jobname** ;

**Returns:** [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) true if the job was successfully removed; false otherwise.

**Sample**

```js
// removes a job 'myjob' from the scheduler
plugins.scheduler.removeJob('myjob');
```

***