@xeplr/workflow-engine 2.0.0 → 3.0.1

package/lib/triggers.js

@@ -0,0 +1,299 @@
+// TRIGGERS — WHAT STARTS A WORKFLOW, FOR EVERY KIND OF START.
+//
+// A workflow's `trigger` (0014) says what is supposed to start it. This module
+// is what acts on it: one registry of kinds, the same way actions are one
+// registry of steps. A kind is a name and up to three functions:
+//
+//   validate(trigger)  → the trigger normalised, or throws naming the problem
+//   due(trigger, from) → for a kind that fires on time: the next moment it is
+//                        due after `from` (Date), or null
+//   matches(trigger, event) → for a kind that fires on an event: whether this
+//                        event is the one it waits for
+//
+// Built in: manual and api (nothing to arm — someone or something calls the
+// run), schedule (a cron expression), and job (a job finished). Folder and
+// mailbox watchers are later kinds of the same registry; a host can register
+// its own with registerTrigger().
+//
+// THE SAME RULES FOR EVERY KIND:
+//   * only a PUBLISHED workflow fires; a draft never does
+//   * `enabled: false` switches a trigger off without losing it
+//   * a run is started with what fired it as `triggerData`, which steps read
+//     as {trigger.*} ({trigger.status}, {trigger.window.from}, {trigger.dueAt})
+//   * every fire and every skip is recorded on workflow_trigger_states, so
+//     "when did it last run, when is it next due, why did it not start" is a
+//     row, not a log search
+var { runWithMt } = require('@xeplr/db');
+var { generateId } = require('@xeplr/utils/lib/helpers');
+var parser = require('cron-parser');
+var db = require('./db');
+
+var KINDS = {};
+var JOB_ID_PATTERN = /^[A-Za-z0-9_-]{1,25}$/;
+var JOB_WHEN = ['success', 'failed', 'finished'];
+
+// A model validation error by NAME (as Objection's is), so the generic save
+// route answers it as one — 422 with the reason under `fields.trigger` —
+// rather than as a server error. status/code are for callers of the engine.
+function invalid(message) {
+  var err = new Error(message);
+  err.name = 'ValidationError';
+  err.type = 'ModelValidation';
+  err.data = { trigger: [{ message: message, keyword: 'trigger' }] };
+  err.statusCode = 400;
+  err.status = 400;
+  err.code = 'TRIGGER_INVALID';
+  return err;
+}
+
+/** Add (or replace) a kind of trigger. */
+function registerTrigger(kind, def) {
+  if (!kind || typeof kind !== 'string') throw new Error('registerTrigger: a kind name is required');
+  KINDS[kind] = Object.assign({ kind: kind }, def || {});
+}
+
+function kinds() { return Object.keys(KINDS); }
+
+function common(trigger) {
+  var out = { kind: trigger.kind };
+  if (trigger.enabled === false) out.enabled = false;
+  return out;
+}
+
+registerTrigger('manual', {
+  description: 'Someone presses Start.',
+  validate: common
+});
+
+registerTrigger('api', {
+  description: 'Another system starts it through the API.',
+  validate: common
+});
+
+registerTrigger('schedule', {
+  description: 'On a schedule — a cron expression, e.g. "0 9 * * 1" for Mondays at 9.',
+  validate: function(trigger) {
+    var cron = String(trigger.cron == null ? '' : trigger.cron).trim();
+    if (!cron) throw invalid('A schedule needs `cron`, e.g. "0 9 * * 1" (Mondays at 9:00).');
+    var opts = trigger.timezone ? { tz: String(trigger.timezone) } : undefined;
+    try { parser.parseExpression(cron, opts); } catch (e) {
+      throw invalid('"' + cron + '" is not a cron expression this can read: ' + e.message);
+    }
+    var out = common(trigger);
+    out.cron = cron;
+    if (trigger.timezone) out.timezone = String(trigger.timezone);
+    return out;
+  },
+  due: function(trigger, from) {
+    var opts = { currentDate: from };
+    if (trigger.timezone) opts.tz = trigger.timezone;
+    return parser.parseExpression(trigger.cron, opts).next().toDate();
+  }
+});
+
+registerTrigger('job', {
+  description: 'When a job finishes — successfully, with a failure, or either way.',
+  validate: function(trigger) {
+    var jobId = String(trigger.jobId == null ? '' : trigger.jobId).trim();
+    if (!jobId) throw invalid('A job trigger needs `jobId`: the job whose finish starts this workflow.');
+    if (!JOB_ID_PATTERN.test(jobId)) throw invalid('"' + jobId + '" is not a job id.');
+    var when = trigger.when == null ? 'success' : String(trigger.when);
+    if (JOB_WHEN.indexOf(when) === -1) {
+      throw invalid('`when` must be one of ' + JOB_WHEN.join(', ') + ' — got "' + when + '".');
+    }
+    var out = common(trigger);
+    out.jobId = jobId;
+    out.when = when;
+    return out;
+  },
+  matches: function(trigger, event) {
+    if (!event || event.jobId !== trigger.jobId) return false;
+    if (trigger.when === 'finished') return true;
+    return event.status === trigger.when;
+  }
+});
+
+/**
+ * A workflow's trigger, checked and normalised. null/undefined stays null
+ * ("started however it is called"). Throws a 400 naming the problem.
+ */
+function validate(trigger) {
+  if (trigger === null || trigger === undefined) return null;
+  if (typeof trigger !== 'object' || Array.isArray(trigger)) {
+    throw invalid('`trigger` must be an object such as { "kind": "schedule", "cron": "0 9 * * 1" }.');
+  }
+  var def = KINDS[trigger.kind];
+  if (!def) throw invalid('"' + trigger.kind + '" is not a kind of trigger. Kinds: ' + kinds().join(', ') + '.');
+  return def.validate ? def.validate(trigger) : common(trigger);
+}
+
+function isOn(workflow) {
+  return Boolean(workflow && workflow.status === 'published' && workflow.trigger &&
+    workflow.trigger.enabled !== false && KINDS[workflow.trigger.kind]);
+}
+
+function mtOf(row) {
+  return { mtId1: row.mtId1 || null, mtId2: row.mtId2 || null, mtId3: row.mtId3 || null, mtId4: row.mtId4 || null };
+}
+
+// ── the record of what each trigger did ─────────────────────────────────
+
+async function stateOf(workflowId) {
+  return db.model('WorkflowTriggerState').query().where({ workflowId: workflowId }).first();
+}
+
+async function writeState(workflow, patch) {
+  var State = db.model('WorkflowTriggerState');
+  var row = await stateOf(workflow.id);
+  var values = Object.assign({ kind: workflow.trigger ? workflow.trigger.kind : null }, patch);
+  if (row) return State.query().patchAndFetchById(row.id, values);
+  return State.query().insert(Object.assign({ id: generateId(), workflowId: workflow.id }, values));
+}
+
+/**
+ * Start a run because a trigger fired, inside the workflow's own tenant
+ * context. A run that cannot start (a required parameter nobody supplies, no
+ * steps) is recorded as a skip with the reason, never thrown at the caller —
+ * a finished job must not fail because a workflow after it is broken.
+ */
+async function fire(workflow, triggerData) {
+  var runner = require('./workflowRunner');
+  return runWithMt(mtOf(workflow), async function() {
+    try {
+      var run = await runner.startRun(workflow.id, {}, { trigger: workflow.trigger.kind, triggerData: triggerData });
+      await writeState(workflow, { lastFiredAt: new Date().toISOString(), lastRunId: run && run.id });
+      return { fired: true, runId: run && run.id };
+    } catch (err) {
+      await writeState(workflow, { lastSkippedAt: new Date().toISOString(), lastSkipReason: err.message });
+      return { fired: false, reason: err.message };
+    }
+  });
+}
+
+// ── event kinds: a job finished ─────────────────────────────────────────
+
+// A chain of jobs longer than this is a loop nobody drew on purpose.
+var MAX_DEPTH = 25;
+
+/**
+ * An event happened (today: a job finished). Every published, enabled
+ * workflow whose trigger is of `kind` and matches it starts, in the caller's
+ * tenant context — the event's own. Returns what each one did.
+ */
+async function emit(kind, event) {
+  var def = KINDS[kind];
+  if (!def || !def.matches) return [];
+  var rows = await db.model('Workflow').query()
+    .where({ status: 'published' })
+    .whereRaw("\"trigger\"->>'kind' = ?", [kind]);
+  var out = [];
+  for (var i = 0; i < rows.length; i++) {
+    var w = rows[i];
+    if (!isOn(w) || !def.matches(w.trigger, event)) continue;
+    var r = await fire(w, Object.assign({ kind: kind }, event));
+    out.push(Object.assign({ workflowId: w.id }, r));
+  }
+  return out;
+}
+
+// ── time kinds: the schedule tick ───────────────────────────────────────
+
+/**
+ * One pass over every timed trigger, across every tenant (a tick is a timer:
+ * there is no request and so no tenant — rows are picked unscoped and each
+ * run is started in its own workflow's context, as @xeplr/jobs' scheduler
+ * does).
+ *
+ * A trigger seen for the first time, or whose settings changed, is given its
+ * next due time and does not fire — so publishing a workflow never starts a
+ * run for a time that has already passed. A due one is CLAIMED by moving its
+ * due time forward with a conditional update; only the process whose update
+ * landed fires it, so two processes running the tick start it once.
+ *
+ * `now` is for tests; production passes nothing.
+ */
+async function tick(now) {
+  now = now || new Date();
+  var timed = kinds().filter(function(k) { return KINDS[k].due; });
+  if (!timed.length) return [];
+  var Workflow = db.model('Workflow');
+  var State = db.model('WorkflowTriggerState');
+  var rows = await Workflow.unscopedQuery()
+    .where({ status: 'published', isActive: true })
+    .whereRaw("\"trigger\"->>'kind' in (" + timed.map(function() { return '?'; }).join(',') + ')', timed);
+  var fired = [];
+  for (var i = 0; i < rows.length; i++) {
+    var w = rows[i];
+    if (!isOn(w)) continue;
+    var def = KINDS[w.trigger.kind];
+    var settings = JSON.stringify(w.trigger);
+    await runWithMt(mtOf(w), async function() {
+      var state = await stateOf(w.id);
+      if (!state || !state.nextDueAt || state.settings !== settings) {
+        await writeState(w, { settings: settings, nextDueAt: def.due(w.trigger, now).toISOString() });
+        return;
+      }
+      var dueAt = new Date(state.nextDueAt);
+      if (dueAt > now) return;
+      var next = def.due(w.trigger, now).toISOString();
+      var claimed = await State.query()
+        .where({ id: state.id, nextDueAt: state.nextDueAt })
+        .patch({ nextDueAt: next });
+      if (!claimed) return;
+      var r = await fire(w, { kind: w.trigger.kind, dueAt: dueAt.toISOString(), firedAt: now.toISOString() });
+      fired.push(Object.assign({ workflowId: w.id }, r));
+    });
+  }
+  return fired;
+}
+
+var _timer = null;
+
+/** Run the tick every `intervalMs` (default 30 s). The timer does not keep the process alive. */
+function startTicking(intervalMs) {
+  stopTicking();
+  var every = intervalMs || 30000;
+  var running = false;
+  _timer = setInterval(function() {
+    if (running) return;
+    running = true;
+    tick().catch(function(err) {
+      console.error('[workflow] trigger tick failed — no scheduled workflow is starting: ' + err.message);
+    }).finally(function() { running = false; });
+  }, every);
+  if (_timer.unref) _timer.unref();
+}
+
+function stopTicking() {
+  if (_timer) clearInterval(_timer);
+  _timer = null;
+}
+
+/** What a workflow's trigger is and what it last did — for a screen. */
+async function describe(workflow) {
+  var state = workflow ? await stateOf(workflow.id) : null;
+  return {
+    trigger: (workflow && workflow.trigger) || null,
+    on: isOn(workflow),
+    lastFiredAt: (state && state.lastFiredAt) || null,
+    lastRunId: (state && state.lastRunId) || null,
+    lastSkippedAt: (state && state.lastSkippedAt) || null,
+    lastSkipReason: (state && state.lastSkipReason) || null,
+    nextDueAt: (state && isOn(workflow) && state.nextDueAt) || null
+  };
+}
+
+module.exports = {
+  registerTrigger: registerTrigger,
+  kinds: kinds,
+  validate: validate,
+  isOn: isOn,
+  fire: fire,
+  emit: emit,
+  tick: tick,
+  startTicking: startTicking,
+  stopTicking: stopTicking,
+  describe: describe,
+  MAX_DEPTH: MAX_DEPTH,
+  JOB_WHEN: JOB_WHEN
+};

package/lib/workflowRunner.js

@@ -112,6 +112,36 @@ async function finishRun(run, status, error) {
  * the two can differ), params/item are the run's own, resumeKey is injected
  * separately, only for the specific step that needs it.
  */
+/**
+ * Resolve `{path}` bindings KEEPING TYPES: a string that is exactly one
+ * binding takes the bound value as it is (an object stays an object, a number
+ * a number); anything else is text, as interpolate makes it.
+ */
+function resolveTyped(value, context) {
+  if (value == null) return value;
+  if (typeof value === 'string') {
+    var whole = /^\{([^{}]+)\}$/.exec(value.trim());
+    if (whole) {
+      var v = getPath(context, whole[1].trim());
+      return v === undefined ? null : v;
+    }
+    return interpolateAll(value, context);
+  }
+  if (Array.isArray(value)) return value.map(function(v) { return resolveTyped(v, context); });
+  if (typeof value === 'object') {
+    var out = {};
+    Object.keys(value).forEach(function(k) { out[k] = resolveTyped(value[k], context); });
+    return out;
+  }
+  return value;
+}
+
+// What started a run, as {trigger.*} reads it — in bindings AND in the
+// conditions on arrows. A run started by hand has just its kind.
+function triggerOf(run) {
+  return run.triggerData || { kind: run.trigger || 'manual' };
+}
+
 async function buildContext(run) {
   var stepRuns = await db.model('WorkflowStepRun').query()
     .where({ runId: run.id })
@@ -124,6 +154,10 @@ async function buildContext(run) {
 
   return {
     params: run.params || {},
+    // WHAT STARTED THIS RUN (lib/triggers.js): a finished job's status,
+    // window and output, a schedule's due time. {trigger.*} in a binding or a
+    // condition. A run started by hand has just its kind.
+    trigger: triggerOf(run),
     item: run.item || null,
     steps: byKey,
     previous_step: previous ? { output: previous.output || {} } : {},
@@ -260,6 +294,8 @@ async function startRun(workflowId, params, opts) {
     // with, so a result can be explained") describe a run that never happened.
     params: resolved,
     trigger: opts.trigger || 'manual',
+    // What fired it, in full — read by steps as {trigger.*}.
+    triggerData: opts.triggerData || null,
     // WHO STARTED IT. Every caller already passes opts.user (the router hands
     // it req.user), and without this the column stayed null on every run —
     // which made "the runs I have not finished" an unanswerable question, and
@@ -344,8 +380,17 @@ async function executeFrom(workflow, steps, run, startStepKey) {
         input: resolvedValues,
         // resumeKey: a wait step's own key, for an action that hands it to
         // something in this same process rather than over a URL (a job
-        // started in-process reports back through jobChains.jobFinished).
-        system: { runId: run.id, stepId: step.id, stepKey: step.stepKey, resumeKey: resumeKey }
+        // started in-process reports back through jobs.jobFinished).
+        // trigger: what started the run, for an action that carries it on
+        // (job-run passes a job's period to the next job).
+        // resolveTyped: a binding that is the WHOLE value keeps its type
+        // ("{trigger.output.totalRows}" stays 7, "{trigger.window}" an object),
+        // for an action that passes values on rather than printing them
+        // (job-run's inputs and carry). Every other action takes `input`, as
+        // resolved above, unchanged.
+        system: { runId: run.id, stepId: step.id, stepKey: step.stepKey, resumeKey: resumeKey,
+          trigger: triggerOf(run), rawValues: step.values || {},
+          resolveTyped: function(value) { return resolveTyped(value, context); } }
       });
 
       if (result.status !== 'success') {
@@ -403,7 +448,7 @@ async function routeAfterStep(workflow, steps, run, step, output) {
     return { done: false, next: next };
   }
 
-  var row = { output: output, item: run.item, params: run.params };
+  var row = { output: output, item: run.item, params: run.params, trigger: triggerOf(run) };
 
   for (var i = 0; i < step.transitions.length; i++) {
     var t = step.transitions[i];
@@ -437,12 +482,12 @@ async function routeAfterStep(workflow, steps, run, step, output) {
  * `step.joinStep`.
  */
 async function handleFanOut(workflow, steps, run, step, t, output) {
-  var array = t.source ? getPath({ output: output, item: run.item, params: run.params }, t.source) : null;
+  var array = t.source ? getPath({ output: output, item: run.item, params: run.params, trigger: triggerOf(run) }, t.source) : null;
   if (!Array.isArray(array)) return false;
 
   var matches = [];
   array.forEach(function(el, idx) {
-    var elRow = { output: output, item: el, params: run.params };
+    var elRow = { output: output, item: el, params: run.params, trigger: triggerOf(run) };
     if (!t.condition || xf.evaluate(t.condition, elRow)) matches.push({ el: el, idx: idx });
   });
   if (!matches.length) return false;
@@ -452,7 +497,7 @@ async function handleFanOut(workflow, steps, run, step, t, output) {
     var m = matches[i];
     var itemKey = m.el && typeof m.el === 'object' ? (m.el.id || m.el.messageId || m.el.key) : null;
     var child = await db.model('WorkflowRun').query().insert(Object.assign({
-      id: uid(), workflowId: workflow.id, status: 'queued', params: run.params,
+      id: uid(), workflowId: workflow.id, status: 'queued', params: run.params, triggerData: run.triggerData || null,
       item: m.el, trigger: 'fanout', startedAt: new Date().toISOString()
     }, mtOf(run)));
     await db.model('WorkflowRunEdge').query().insert({
@@ -649,4 +694,5 @@ async function resumeByKey(key, output, opts) {
 // resolveParams and collectParams are exported for their own sake: they are
 // the pieces of the engine that are pure — rows in, a schema or a resolved
 // set out, or a throw — and testing them needs no database.
-module.exports = { startRun: startRun, resumeByKey: resumeByKey, resolveParams: resolveParams, collectParams: collectParams };
+module.exports = {
+  resolveTyped: resolveTyped, startRun: startRun, resumeByKey: resumeByKey, resolveParams: resolveParams, collectParams: collectParams };

package/migrations/0015_workflow_triggers.sql

@@ -0,0 +1,85 @@
+-- 0015_workflow_triggers.sql
+--
+-- TRIGGERS START RUNS — and a job finishing is one of them.
+--
+-- 0014 recorded what is supposed to start a workflow; nothing acted on it.
+-- lib/triggers.js now does, for every kind through one registry: a schedule,
+-- a job finishing, and later a folder or a mailbox. Three things here.
+--
+-- 1. WHAT FIRED A RUN, IN FULL. workflow_runs.trigger is the kind ('job',
+--    'schedule'); triggerData is what came with it — a finished job's status,
+--    period and output, a schedule's due time — read by steps as {trigger.*}.
+ALTER TABLE "workflow_runs" ADD COLUMN IF NOT EXISTS "triggerData" jsonb;
+
+-- 2. WHAT EACH TRIGGER LAST DID: when it fired and which run that was, when
+--    it is next due, and when and why it did not start a run (a required
+--    parameter nobody supplies, a workflow with no steps). One row per
+--    workflow, so "why did this not run last night" is a SELECT.
+--
+--    Its times are timestamptz: a due time is an instant, and a plain
+--    timestamp read back in another server timezone would fire hours off.
+--
+--    `settings` is the trigger as it was when nextDueAt was computed; a
+--    changed schedule is noticed by comparing it, and given a fresh due time
+--    rather than firing for one computed from the old expression.
+CREATE TABLE IF NOT EXISTS "workflow_trigger_states" (
+  "id" varchar(25) PRIMARY KEY,
+  "workflowId" varchar(25) NOT NULL,
+  "kind" varchar(32),
+  "settings" text,
+  "nextDueAt" timestamptz,
+  "lastFiredAt" timestamptz,
+  "lastRunId" varchar(25),
+  "lastSkippedAt" timestamptz,
+  "lastSkipReason" text,
+  "isActive" boolean DEFAULT true,
+  "mtId1" varchar(25),
+  "mtId2" varchar(25),
+  "mtId3" varchar(25),
+  "mtId4" varchar(25),
+  "recordCreatedDate" timestamp,
+  "recordModifiedDate" timestamp,
+  "recordCreatedBy" varchar(25),
+  "recordModifiedBy" varchar(25)
+);
+CREATE UNIQUE INDEX IF NOT EXISTS "workflow_trigger_states_workflow_unique" ON "workflow_trigger_states" ("workflowId");
+
+-- 3. JOB CHAINS BECOME ORDINARY WORKFLOWS.
+--
+-- A job's "After this job" rules used to be a hidden, locked workflow of
+-- kind 'job-chain' with two private actions and their own routes. It is now
+-- what it always was underneath: a workflow, triggered by the job finishing.
+--
+--   kind 'job-chain'           → 'workflow', with trigger
+--                                { kind: 'job', jobId, when: 'finished' }
+--                                (the decide step still routes on status)
+--   key 'job-chain-<jobId>'    → none; the trigger says which job
+--   'job-chain-decide' step    → 'decide' (a plain branching step)
+--   'job-chain-next' steps     → 'job-run', which carries the period on
+--   conditions on params.x     → trigger.x  (status, output, window, carry…)
+--   bindings {output.x} etc.   → {trigger.output.x}
+--
+-- A rule input of exactly "{window}" is dropped: job-run passes the finished
+-- job's period on by itself, as an object, which a binding would turn into
+-- text.
+UPDATE "workflow_steps" s
+   SET "actionName" = 'decide',
+       "values" = '{}'::jsonb,
+       "transitions" = replace(s."transitions"::text, '"params.', '"trigger.')::jsonb
+  FROM "workflows" w
+ WHERE w."id" = s."workflowId" AND w."kind" = 'job-chain' AND s."actionName" = 'job-chain-decide';
+
+UPDATE "workflow_steps" s
+   SET "actionName" = 'job-run',
+       "values" = regexp_replace(
+         (CASE WHEN s."values"->'inputs'->>'window' = '{window}'
+               THEN s."values" #- '{inputs,window}' ELSE s."values" END)::text,
+         '\{\s*(status|error|output|carry|window|jobId|given|used)\M', '{trigger.\1', 'g')::jsonb
+  FROM "workflows" w
+ WHERE w."id" = s."workflowId" AND w."kind" = 'job-chain' AND s."actionName" = 'job-chain-next';
+
+UPDATE "workflows"
+   SET "trigger" = jsonb_build_object('kind', 'job', 'jobId', substring("key" from 11), 'when', 'finished'),
+       "kind" = 'workflow',
+       "key" = NULL
+ WHERE "kind" = 'job-chain' AND "key" LIKE 'job-chain-%';

package/models/Workflow.js

@@ -27,9 +27,10 @@ class Workflow extends BaseModel {
         description: { type: ['string', 'null'], maxLength: 1000 },
         // [{ name, type, required, default, description, order }]
         params: { type: ['array', 'null'] },
-        // WHAT STARTS A RUN, as the designer recorded it — { kind, … }, one
-        // shape per kind (see migrations/0014). The engine does not arm
-        // anything from it yet; it is the intent the arming work will read.
+        // WHAT STARTS A RUN — { kind, … }, one shape per kind (migrations/0014),
+        // acted on by lib/triggers.js: manual, api, schedule, job, and any kind
+        // a host registers. Checked on every write (below), so a trigger that
+        // could never fire is refused when it is saved, not discovered later.
         trigger: { type: ['object', 'null'] },
         status: { type: 'string', maxLength: 20 },
         // WHAT THE BUILDER OFFERS, not what the engine does — 'workflow' (the
@@ -37,7 +38,7 @@ class Workflow extends BaseModel {
         // designed in another app entirely through the /flows facade and
         // read-only in this product's own builder). workflowRunner never reads
         // it. See migrations/0012 and 0013.
-        kind: { type: 'string', enum: ['workflow', 'jobs', 'screens', 'job-chain'] },
+        kind: { type: 'string', enum: ['workflow', 'jobs', 'screens'] },
         isActive: { type: 'boolean' },
         recordCreatedDate: { type: ['string', 'null'] },
         recordModifiedDate: { type: ['string', 'null'] },
@@ -50,6 +51,12 @@ class Workflow extends BaseModel {
   $beforeInsert() {
     super.$beforeInsert();
     if (!this.status) this.status = 'draft';
+    if (this.trigger !== undefined) this.trigger = require('../lib/triggers').validate(this.trigger);
+  }
+
+  $beforeUpdate(opt, ctx) {
+    super.$beforeUpdate(opt, ctx);
+    if (this.trigger !== undefined) this.trigger = require('../lib/triggers').validate(this.trigger);
   }
 
   static get relationMappings() {

package/models/WorkflowRun.js

@@ -24,6 +24,8 @@ class WorkflowRun extends BaseModel {
         // element this occurrence exists to process. See WorkflowRunEdge.
         item: { type: ['object', 'null'] },
         trigger: { type: ['string', 'null'], maxLength: 64 },
+        // What fired the run, in full (lib/triggers.js) — steps read it as {trigger.*}.
+        triggerData: { type: ['object', 'null'] },
         startedAt: { type: ['string', 'null'] },
         finishedAt: { type: ['string', 'null'] },
         durationMs: { type: ['integer', 'null'] },

package/models/WorkflowStep.js

@@ -49,6 +49,20 @@ class WorkflowStep extends BaseModel {
     super.$beforeInsert();
     if (!this.kind) this.kind = 'auto';
     if (!this.onError) this.onError = 'stop';
+    this.compileWhen();
+  }
+
+  $beforeUpdate(opt, ctx) {
+    super.$beforeUpdate(opt, ctx);
+    this.compileWhen();
+  }
+
+  // An arrow written as `when` ({ field, op, value }) gets its engine
+  // `condition` here, on every write — lib/conditions.js.
+  compileWhen() {
+    if (this.transitions !== undefined) {
+      this.transitions = require('../lib/conditions').compileTransitions(this.transitions, this.name || this.stepKey);
+    }
   }
 
   static get relationMappings() {

package/models/WorkflowTriggerState.js

@@ -0,0 +1,35 @@
+var { BaseModel } = require('@xeplr/db');
+
+// What a workflow's trigger last did — see 0015_workflow_triggers.sql and
+// lib/triggers.js. One row per workflow; written by the engine, never by a
+// document save.
+
+class WorkflowTriggerState extends BaseModel {
+  static get tableName() { return 'workflow_trigger_states'; }
+  static get idColumn() { return 'id'; }
+
+  static get jsonSchema() {
+    return {
+      type: 'object',
+      required: ['id', 'workflowId'],
+      properties: {
+        id: { type: 'string', maxLength: 25 },
+        workflowId: { type: 'string', maxLength: 25 },
+        kind: { type: ['string', 'null'], maxLength: 32 },
+        settings: { type: ['string', 'null'] },
+        nextDueAt: { type: ['string', 'null'] },
+        lastFiredAt: { type: ['string', 'null'] },
+        lastRunId: { type: ['string', 'null'], maxLength: 25 },
+        lastSkippedAt: { type: ['string', 'null'] },
+        lastSkipReason: { type: ['string', 'null'] },
+        isActive: { type: 'boolean' },
+        recordCreatedDate: { type: ['string', 'null'] },
+        recordModifiedDate: { type: ['string', 'null'] },
+        recordCreatedBy: { type: ['string', 'null'], maxLength: 25 },
+        recordModifiedBy: { type: ['string', 'null'], maxLength: 25 }
+      }
+    };
+  }
+}
+
+module.exports = WorkflowTriggerState;

package/models/index.js

@@ -12,6 +12,7 @@ var WorkflowRun = require('./WorkflowRun');
 var WorkflowStepRun = require('./WorkflowStepRun');
 var WorkflowResumeKey = require('./WorkflowResumeKey');
 var WorkflowRunEdge = require('./WorkflowRunEdge');
+var WorkflowTriggerState = require('./WorkflowTriggerState');
 
 module.exports = {
   Company: Company,
@@ -21,5 +22,6 @@ module.exports = {
   WorkflowRun: WorkflowRun,
   WorkflowStepRun: WorkflowStepRun,
   WorkflowResumeKey: WorkflowResumeKey,
-  WorkflowRunEdge: WorkflowRunEdge
+  WorkflowRunEdge: WorkflowRunEdge,
+  WorkflowTriggerState: WorkflowTriggerState
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/workflow-engine",
-  "version": "2.0.0",
+  "version": "3.0.1",
   "license": "MIT",
   "description": "The workflow engine — workflow's own database and tables, the action catalog, starting and resuming runs, and the flows facade. No HTTP: @xeplr/workflow-api puts the routes on top.",
   "main": "index.js",
@@ -45,5 +45,8 @@
   "devDependencies": {
     "@xeplr/jobs": "^2.3.0",
     "knex": "^3.3.0"
+  },
+  "dependencies": {
+    "cron-parser": "^4.9.0"
   }
 }