Weekly report

Every Monday morning, gather last week’s numbers and email them to your team.

A weekly report is simple work that must happen on time, every week: count the sign-ups, the orders, and the revenue, then send the summary. Run it from a server’s crontab, and it’s skipped the week that server is down, or sent twice when two servers run it.

With Nelkap, the schedule lives with the workflow. Nelkap starts one run each Monday, whatever runs your app and however many instances it has. Each run gathers the numbers in steps, so a run cut off halfway goes on without counting again.

Write the workflow

nelkap/workflows/send-weekly-report.ts

import { sendReportEmail } from '../../lib/email';
import {
  countOrders,
  countSignups,
  startOfLastWeek,
  sumRevenue,
} from '../../lib/metrics';
import { nelkap } from '../client';

export async function sendWeeklyReport() {
  const weekStart = await nelkap.step.run('week start', () =>
    startOfLastWeek(new Date()).toISOString(),
  );

  const [signups, orders, revenue] = await Promise.all([
    nelkap.step.run('signups', () => countSignups(weekStart)),
    nelkap.step.run('orders', () => countOrders(weekStart)),
    nelkap.step.run('revenue', () => sumRevenue(weekStart)),
  ]);

  await nelkap.step.run('email', () =>
    sendReportEmail(
      { weekStart, signups, orders, revenue },
      `report_${weekStart}`,
    ),
  );
}

A scheduled run has no payload, so the workflow takes no argument:

1. It works out when last week started. The date is a step, so every call of the run reports on the same week, even one that picks up after midnight.
2. It counts the sign-ups, the orders, and the revenue side by side, as three steps saved on their own.
3. It emails the report, with an idempotency key built from the week, so the email goes out once even if a crash cuts the step off before it’s saved.

Replace the functions from lib with your own queries and your email provider.

Schedule

Register the workflow with its schedule:

nelkap/index.ts

import { nelkap } from './client';
import { sendWeeklyReport } from './workflows/send-weekly-report';

nelkap.registerWorkflows([
  {
    name: 'sendWeeklyReport',
    handler: sendWeeklyReport,
    cron: '0 9 * * 1',
  },
]);

export { nelkap, sendWeeklyReport };

0 9 * * 1 starts a run every Monday at 9:00 UTC. Once your app has registered it, nothing else in your code starts the report. See Schedules to write your own.

Test it

You don’t have to wait for Monday. Start a run from any server code of your app:

await nelkap.run(sendWeeklyReport);

It runs the same workflow, and the report goes out within a minute.

View the runs

Filter your project’s runs by the workflow: each Monday shows one run, with Cron as its trigger. Open one to see the week it covered, the three counts, and the email.

If Nelkap couldn’t start runs for a while, the Mondays missed meanwhile give a single run, so your team never gets a pile of reports at once.

Going further

• Record the week’s conversion rate with step.score, to chart it week after week.
• Send each customer their own report: list them in a step, and start a run for each one. See Fan-out.