Quickstart

This gets one step running on your machine with fob-worker. You don't need an account for any of it. The example step flags invoices above an approval limit.

You'll need Node.js 18 or later and git.

1. Install the CLIs

npm install -g @finopsbricks/fob-worker @finopsbricks/fob-orc

2. Create a worker repo from the template

git clone https://github.com/finopsbricks/worker-template.git worker-acme
cd worker-acme
rm -rf .git && git init

Replace the template's placeholders with your organisation's short name (here acme). On macOS:

grep -rl '{{' . --include='*.js' --include='*.json' --include='*.md' | xargs sed -i '' \
  -e 's/{{ORG_NAME}}/acme/g' -e 's/{{LOCATION}}/acme/g' \
  -e 's/{{WORKER_NAME}}/worker-acme/g' -e 's/{{WORKER_DESCRIPTION}}/Worker for acme/g'

On Linux, use sed -i instead of sed -i ''. Then install:

cp .env.example .env
npm install

3. Write a step

A step is a file under src/steps/ that exports defineStep(). Create src/steps/IN1__check_invoices/IN1_01_check.js:

import { defineStep } from '@fob/lib-worker';
import { z } from 'zod';

export default defineStep({
  slug: 'IN1_01_check',
  name: 'Check invoices',
  description: 'Flags invoices above the approval limit',
  inputSchema: z.object({
    approval_limit: z.number().default(5000),
    invoices: z.array(z.object({ number: z.string(), amount: z.number() })).default([]),
  }),
  outputSchema: z.object({ checked: z.number(), above_limit: z.array(z.string()) }),
  execute: async (config) => {
    const above_limit = config.invoices
      .filter((invoice) => invoice.amount > config.approval_limit)
      .map((invoice) => invoice.number);
    return { checked: config.invoices.length, above_limit };
  },
});

4. Run it on your machine

Save a test config as a scenario, in .orchestrator/scenarios/IN1_01_check/two-invoices.json:

{
  "invoices": [
    { "number": "INV-1001", "amount": 1250 },
    { "number": "INV-1002", "amount": 7400 }
  ]
}

Then run the step with it:

fob-worker steps run IN1_01_check --scenario two-invoices

Output:
------------------------------------------------------------
{
  "checked": 2,
  "above_limit": [
    "INV-1002"
  ]
}

   Output saved: temp/IN1_01_check.json
Step completed successfully

Edit the step and run it again. That's the loop.

5. Run it on the Orchestrator

To run the station on a schedule and get a work record for every run, you need an account: sign up, create an organisation in the Orchestrator, and create an API key for the worker. Then describe the line and station as JSON files, push them with fob-orc, start the worker and trigger a run:

fob-orc lines push --all
fob-orc stations push --all
fob-worker procs start
fob-orc stations run IN1

The full walkthrough, with the .env values and station files, is in Get started (parts 5 and 6).