Jobs
Jobs in Keel allow you to execute tasks in the background away from your normal workflow. This can be incredibly useful if you have tasks that need to be executed on a regular basis or take longer than usual to run.
Jobs can be scheduled and run on a recurring, scheduled basis.
You can define a job in your schema.keel
file, and implement it just like a function. Job definitions are root level blocks, along with Models, Roles and APIs.
job EmailNewCustomerReport {
@schedule("0 6 * * 5")
}
This example defines a job called EmailNewCustomerReport
that is scheduled to run every Friday.
Running keel generate
in the CLI will create a new jobs file in a directory called ./jobs
. The file created for the job we created above will look something like this.
import { EmailNewCustomerReport } from "@teamkeel/sdk";
export default EmailNewCustomerReport(async (ctx) => {
// your code here
});
To implement this job, we can use the same generated APIs that are available to functions.
Jobs in Keel have a max execution time of 15 minutes (due to Lambda max execution times). Jobs that reach the max execution time will be marked as failed. This time will be longer in the future
Scheduled jobs
A scheduled job is a job that has a @schedule
attribute inside it. This attribute uses the AWS EventBridge cron expression format (opens in a new tab) to define the
schedule by which a job is executed. Scheduled jobs take no inputs.
job EmailNewCustomerReport {
@schedule("0 6 * * 5")
}
The example above executes the EmailNewCustomerReport
job at 6:00 every Friday.
Jobs may need to be executed on more than one schedule. Because of this, it is possible to define more than one @schedule
attribute for a job.
job EmailNewCustomerReport {
@schedule("0 0 7 ? * 1,2,3,4 *")
@schedule("0 6 * * 5")
}
The example above executes the EmailNewCustomerReport
job at 7:00 every Monday to Thursday but on Fridays it will execute it at 6:00.
Scheduled jobs can also take a @permission
attribute. If a job has both a permission and a schedule defined, they can be run both on the schedule and from the Keel console.
job EmailNewCustomerReport {
@schedule("0 6 * * 5")
@permission(roles: [Onboarding])
}
role Onboarding {
emails {
onboarding@example.com
}
}
Please note that even if a scheduled job has a permission defined, it still cannot take any inputs.
Manual jobs
A manual job is a job that can be executed from the Keel console. This type of job can accept inputs and requires specific permissions to be defined. This allows you to control which users in your system have the permission to execute them
job EmailNewCustomerReport {
inputs {
joinedSince Date?
deliveryEmail Text
}
@permission(roles: [Onboarding])
}
This example defines the EmailNewCustomerReport
as a manual job. It takes two inputs, joinedSince
an optional Date
and deliveryEmail
, a required String
.
It also declares permissions for users with the Onboarding
role, which means that only users who have been assigned that role will be able to execute them.
To execute a manual job, you will need to use the Keel console.
Jobs are available in the left menu on your console. Once you select the menu item, the jobs page will list all of the jobs defined within your project on one tab, and the job run history in another.
With the All Jobs
tab selected, you can see all of the jobs defined within your project, schedules that are defined for them, the date and time of the last run and the date and time of the next scheduled run, if any.
Clicking on a job row will display further details about that job.
With the Run history
tab selected, you can see all of the job runs that have been executed, along with the date and time of the last run, the status of the run and who executed it. Clicking
on a run row will display further details about the run. Job status's can be either Running
, Successful
or Failed
.
Within the Job Details
page, you can view any schedule that has been defined, next run details and the run history for that job.
Within the Run details
page, you can view the date and time of the run, it's status, how long it took to run the job, who ran it, links to the build that executed the job and a full trace of the run to enable debugging if something went wrong.
Permissions
Jobs that are specified with permissions can be run manually from the Keel console. Permissions can be defined using Roles, or using expressions.
The power of expressions allow us to make permissions rules that are very flexible. The example below shows how to use expressions within permissions to give global access. to executing a job.
job EmailNewCustomerReport {
@permission(expression: true)
}
Testing
To help you develop your jobs, Keel makes them available within tests.
import { jobs, actions, models, resetDatabase } from "@teamkeel/testing";
import { test, expect, beforeEach } from "vitest";
beforeEach(resetDatabase);
test("Test EmailNewCustomerReport updates new customer flag", async () => {
console.log("Test start")
await jobs.emailNewCustomerReport();
const res = await actions.getCustomer();
expect(res.reportSent).toBeTruthy();
});
Currently, you get 512MB of disk space by default when running a job.