Scheduler API

How it works
The Scheduler API gives apps the possibility of creating tasks that run in a defined schedule. It can be a one-time event or a recurring task. It uses agenda.js as backend, so schedule syntax and internal processes are all according to its documentation.
Detailed documentation on the API can be found in the Apps Engine's docs.
There's also an example app that can be used as a guide.
Permissions
As per the Permission System, the Schedule API needs the following permission in your app's manifest:
1
{
2
  permissions: [
3
    { "name":"scheduler" }
4
  ]
5
}
Copied!
How to use it
Registering job functions (processors)
To use the Scheduler API you'll need two things: the functions to be run as jobs (we call them processors) and the schedule in which they will be run on. This is configured in the app's extendConfiguration method. During the app's startup, the processors are registered to make them available for scheduling.
1
public async extendConfiguration(configuration: IConfigurationExtend) {
2
    configuration.scheduler.registerProcessors([
3
        {
4
            id: 'first',
5
            processor: async (jobData) => console.log(`[${ Date() }] this is a task`, jobData),
6
        },
7
    ]);
8
}
Copied!
The processor is an async function and can receive arguments (jobData). The arguments are passed during scheduling.
Starting a job
To trigger the registered processor as a job, you must provide the id of the processor, the type of job it will be and optionally an object (data) that will be passed to the processor as argument (jobData). Available types are RECURRING, making the job run in a interval, and ONETIME, making the job run only once (when). Starting a job can be done when running a slashcommand, for example:
1
// slashcommand class
2
public async executor(context: SlashCommandContext, read: IRead, modify: IModify): Promise<void> {
3
    // SCHEDULING A RECURRING TASK
4
    const task = {
5
      id: 'first',
6
      interval: '10 seconds',
7
      data: { test: true },
8
    };
9
    await modify.getScheduler().scheduleRecurring(task);
10
​
11
    // SCHEDULING ONETIME TASK
12
    const task = {
13
      id: 'first',
14
      when: '8 seconds',
15
    };
16
    await modify.getScheduler().scheduleOnce(task);
17
}
Copied!
There's also the possibility of triggering a job as soon as it gets registered, without the need for manual or automated triggering.
When you register your processor in the extendConfiguration method, you can pass a prop called startupSetting in the processor's object:
1
import { StartupType } from '@rocket.chat/apps-engine/definition/scheduler';
2
// ...
3
    configuration.scheduler.registerProcessors([
4
        {
5
            id: 'first',
6
            processor: async (jobData) => console.log(`[${ Date() }] this is a task`, jobData),
7
            startupSetting: {
8
              type: StartupType.ONETIME,
9
              when: '20 seconds',
10
              data: { test: true },
11
            }
12
        },
13
        {
14
            id: 'second',
15
            processor: async (jobData) => console.log(`[${ Date() }] this is a task`, jobData),
16
            startupSetting: {
17
              type: StartupType.RECURRING,
18
              interval: '20 seconds',
19
            }
20
        },
21
    ]);
Copied!
This indicates that you want that particular processor to be scheduled as soon as it gets registered. You can define the "immediate scheduling" as a recurring job (StartupType.RECURRING) or a one-time job (StartupType.ONETIME). You can also pass data using the data object. It will work just like when you schedule a task using the modify accessor.
(data) here is not something that's passed to the processor or function as a living object or executable code. This (data) is a static piece of data that are passed to the processor's first argument.
the signature of the processor function:
1
(jobContext: IJobContext, read: IRead, modify: IModify, http: IHttp, persis: IPersistence) => Promise<void>
Copied!
The first argument is the data object you're passing when actually scheduling the job; ([k: string]:any) . Rest are passed when the function is run.
Canceling a job
To stop a job, all you have to do is pass the id of the job you want to stop
1
    const jobId = 'first';
2
    await modify.getScheduler().cancelJob(jobId);
Copied!
It will stop the running job (if any).
Canceling all jobs from the app
To stop all the current running jobs from the app:
1
    await modify.getScheduler().cancelAllJobs();
Copied!

OAuth2 Client

NPM Package Support (Experimental)

Last modified 18d ago

Export as PDF

Copy link

Edit on GitHub

Contents

How it works

Permissions

How to use it

Registering job functions (processors)

Starting a job

Canceling a job

Canceling all jobs from the app