Minimum PostHog version: 1.25.0
Jobs are a way for app developers to schedule and run tasks asynchronously using a powerful scheduling API.
Jobs make possible use cases such as retrying failed requests, a key component of apps that export data out of PostHog.
Specifying jobs
To specify jobs, you should export a jobs
object mapping string keys (job names) to functions (jobs), like so:
export const jobs = {retryRequest: (request, meta) => {fetch(request.url, request.options)}}
Job functions can optionally take a payload as their first argument, which can be of any type. They can also access the meta
object, which is appended as an argument to all app functions, meaning that it will be the second argument in the presence of a payload, and the first (and only) argument in the absence of one.
Triggering a job
Jobs are accessed as jobs
via the meta
object. Triggering a job works as follows:
await jobs.retryRequest(request).runIn(30, 'seconds')await jobs.retryRequest(request).runNow()await jobs.retryRequest(request).runAt(new Date())
Having gotten a job function via its key from the jobs
object, calling the function with the desired payload will return another object with 3 functions that can be used to schedule your job. They are:
runNow
: Runs the job now, but does so asynchronouslyrunAt
: Takes a JavaScriptDate
object that specifies when the job should runrunIn
: Takes a duration as anumber
and a unit as astring
specifying in how many units of time to run this job (e.g. 1 hour)
Accepted values for the unit argument of
runIn
are: 'milliseconds', 'seconds', 'minutes', 'hours', 'days', 'weeks', 'months', 'quarters', and 'years'. The function will accept these in both singular (e.g. 'second') or plural (e.g. 'seconds') form.
All jobs return a promise that does not resolve to any value.
Full example
export const jobs = {continueSearchingForTheTeapot: async (request, meta) => {await lookForTheTeapot(request)}}async function lookForTheTeapot (request) {const res = await fetch(request.url)if (res.status !== 418) {await jobs.continueSearchingForTheTeapot(request).runIn(30, 'seconds')return}console.log('found the teapot!')}export async function processEvent (event, { jobs }) {const request = { url: 'https://www.google.com/teapot' }await lookForTheTeapot(request)return event}