Background processing

Aha! Builder applications can run work in the background. A job function executes asynchronously, off the main request, for long-running or non-blocking tasks such as processing an import, syncing external data, or sending a batch of email. Elle adds one when you describe work that should not make the user wait.

This reference documents how background jobs are defined and queued. Read it to understand what your applications can do behind the scenes, to review what Elle generated, or to ground an AI assistant in the specifics — reference this article with Elle or any LLM so it knows exactly how background jobs work in Aha! Builder.

Click any of the following links to skip ahead:

• Overview

• Queueing jobs

• Build it with Elle

Overview

A "job function" is a type of server function which executes asynchronously in the background. Jobs are useful for long-running or non-blocking work like sending emails, processing imports, or syncing external data.

import { server, db } from '@aha-app/builder-core';
import { orders } from '../db/schema';
import { eq } from 'drizzle-orm';

server.job('processOrder', async ({ orderId }) => {
  await db.update(orders).set({ status: 'processing' }).where(eq(orders.id, orderId));
  // ... perform expensive work
  await db.update(orders).set({ status: 'completed' }).where(eq(orders.id, orderId));
});

Top

Queueing jobs

Server jobs can only be triggered from other server functions using server.queueJob:

import { server, db } from '@aha-app/builder-core';

server.data('createOrder', async ({ items }) => {
  const [order] = await db.insert(orders).values({ items, status: 'pending' }).returning();
  server.queueJob('processOrder', { orderId: order.id });
  return order;
});

The arguments passed to server.queueJob will be serialized to JSON and made available to the job handler.

Top