Scheduler Provider

The Scheduler provider allows you to schedule functions to be run at a specified time in the future, or to recur based on an interval. It also supports scheduling operations using CRON expressions.

How it works

When you call the startAt function on the Scheduler, the Vonage Cloud Runtime platform creates a job with the details you provided. If you provided an ID that will be used, otherwise one will be generated for you. This ID is how you can cancel the job if needed using the cancel function.

The Scheduler provider operates with a minimum of one minute's precision. For example, a job scheduled to start at 10:01 will start within that minute, between 10:01:00 and 10:01:59.

When the job's invocation time is reached, your application will get a request to the callback you specified. You will have 30 seconds to respond to this request with a 200 status otherwise the request will be retried. Requests are retried 5 times before being abandoned.

Each request from the scheduler has a hash on the request's header under X-Neru-Scheduler-RequestHash. Using this hash you can make sure to handle incoming scheduler requests in case your application was not able to respond with a 200 status in time.

Functions

• startAt - this allows you to schedule your application to be called in the future after a specified time, or repeatedly at a given interval. See the code snippet here.
• cancel - this allows you to cancel an existing scheduled callback using the schedule ID. See the code snippet here.
• get - this allows you to retrieve an existing scheduled job using the schedule ID. See the code snippet here.
• list - this allows you to retrieve the IDs for all existing scheduled jobs. See the code snippet here.

Initializing the Scheduler Provider

To use the Scheduler Provider you need to create an instance of the provider using a session:

const session = vcr.createSession();
const scheduler = new Scheduler(session);

Requests made from Vonage Cloud Runtime to your application via the Scheduler provider will contain the session information from the session which set up the scheduled callback, which means you can access state from the originating session using getSessionFromRequest to create a session object.

Use Case

For example, to use the Scheduler provider to send a one-off reminder text in five minutes after an incoming message:

app.post('/onMessage', async (req, res, next) => {
    try {
        const session = vcr.createSession();
        const scheduler = new Scheduler(session);

        const reminderTime = new Date(new Date().setMinutes(new Date().getMinutes() + 5)).toISOString();

        await scheduler.startAt({
            startAt: reminderTime,
            callback: 'textReminder',
            payload: {
                from: req.body.from,
            }
        });
    } catch (error) {
        next(error);
    }
});

After five minutes have passed the textReminder route will get called with the payload:

app.post('/textReminder', async (req, res, next) => {
    try {
        const session = vcr.createSession();
        const messaging = new Messages(session);

        const from = req.body.from;

        const to = { type: "sms", number: from };
        const vonageNumber = { type: "sms", number: "447000000000" }; 

        await messaging.sendText(
            vonageNumber,
            to,
            `Reminder from Vonage!`
        );

        res.sendStatus(200);
    } catch (error) {
        next(error);
    }
});

The Scheduler provider also supports using CRON to define the interval in which it calls the defined route. This time, the code triggers the defined route every 10 minutes past the hour for a day:

app.post('/onMessage', async (req, res, next) => {
    try {
        const session = vcr.createSession();
        const scheduler = new Scheduler(session);

        const nowDate = new Date();
        const endDate = new Date();
        endDate.setDate(endDate.getDate() + 1);

        await scheduler.startAt({
            startAt: nowDate.toISOString(),
            callback: 'textReminder',
            interval: {
                cron: '10 * * * *',
                until: {
                    date: endDate.toISOString(),
                    maxInvocations: 24
                }
            },
            payload: {
                from: req.body.from,
            }
        });
    } catch (error) {
        next(error);
    }
});