@xeplr/workflow 1.0.1

package/index.js

@@ -0,0 +1,313 @@
+var path = require('path');
+var createApp = require('@xeplr/base-apis/express');
+var { up } = require('@xeplr/db').sqlMigrator;
+var { resolveConfig, registerApplication, getApplicationId, migrationsFor, ensureDatabaseFor } = require('@xeplr/db');
+var buildWorkflowRouter = require('./lib/router');
+var buildFlowsRouter = require('./lib/flowsRouter');
+var connectDb = require('./lib/db');
+var actionCatalog = require('./lib/actionCatalog');
+var envExposed = require('./lib/envExposed');
+var xcfgSetup = require('./db/xcfgSetup');
+
+/**
+ * Register workflow into a host app, or stand up its own.
+ *
+ *   // Embedded — mounted into a caller's existing Express app:
+ *   await registerWorkflow({
+ *     app: myExpressApp,
+ *     mountPath: '/workflow',
+ *     db: { name: 'xeplr_bi_workflow', connection: myDbConnectionString },
+ *     mtMembershipGate: myAlreadyBuiltGate    // omit → every route ungated
+ *   });
+ *
+ *   // Standalone — this package creates and starts its own app via
+ *   // @xeplr/base-apis' createApp (the only thing that ever builds an app
+ *   // here, embedded or standalone). See orchestration/standalone.js, which
+ *   // is exactly this call with its config sourced from development.env.
+ *   await registerWorkflow({ db: {...}, port: 19122, middleware: [...] });
+ *
+ * @param {object} config
+ * @param {import('express').Express} [config.app] - an existing Express app
+ *   to mount onto. Omit WITH config.port to have this package create and
+ *   start its own; omit BOTH to get the router back and mount it yourself.
+ *
+ *   That third mode is not a convenience — for some hosts it is the only
+ *   thing that works. @xeplr/base-apis' createApp registers a catch-all 404
+ *   AFTER the routes it was given, so anything app.use()'d afterwards sits
+ *   behind it and is never reached: the mount succeeds, and every path under
+ *   it answers 404. A host built that way has to hand the router in with its
+ *   own route map rather than bolt it on after.
+ * @param {object} config.db - { name, connection, mts? } — see lib/db.js.
+ *   Always required: workflow's own domain data is always its own
+ *   responsibility, however it's mounted.
+ * @param {string} [config.applicationId] - the PRODUCT mounting this
+ *   ('xeplr-bi', 'xeplr-erp'; 'xeplr-workflow' standalone). OPTIONAL: a host
+ *   normally calls registerApplication() once at its own startup and every
+ *   sub-product it mounts inherits that, so passing this again is only for a
+ *   host that prefers to be explicit.
+ *
+ *   It does NOT separate workflow's own data — config.db does that. Each host
+ *   gives workflow its own database (xeplr_bi_workflow, xeplr_erp_workflow),
+ *   which is the whole boundary, and is why none of these tables carries an
+ *   applicationId column.
+ *
+ *   What it IS for: xeplr_configs, the one store that cannot be split per
+ *   consumer because every app opens it. This mount writes movement metadata
+ *   there, and those rows are attributed by applicationId. So an identity has
+ *   to be registered by the time this is called — hence the throw below when
+ *   neither this nor a prior registerApplication() supplied one.
+ * @param {string} [config.mountPath='/workflow'] - only meaningful when this
+ *   package creates its own app; a host app's own app.use() call decides its
+ *   own mount path when embedding.
+ * @param {number} [config.port] - only used when creating a standalone app.
+ * @param {string} [config.appName='xeplr_workflow_api']
+ * @param {Function} [config.mtMembershipGate] - see lib/router.js
+ * @param {Function} [config.authMiddleware] - see lib/router.js
+ * @param {Function[]} [config.middleware] - only used when creating a
+ *   standalone app — passed straight to createApp.
+ * @param {object|false} [config.log] - only used when creating a standalone app.
+ * @returns {Promise<{ router: import('express').Router, flowsRouter: import('express').Router, app: import('express').Express, server?: import('http').Server }>}
+ *   `router` carries every route including the flows facade at
+ *   `<mount>/flows`. `flowsRouter` is that facade on its own, for a host that
+ *   would rather mount it somewhere else as well — see the note where it is
+ *   built.
+ */
+async function registerWorkflow(config) {
+  config = config || {};
+  if (!config.db) {
+    throw new Error('registerWorkflow: config.db is required — workflow owns its own domain data regardless of how it is mounted');
+  }
+  // WORKFLOW'S OWN TABLES CARRY NO applicationId. Each host supplies its own
+  // database (config.db), so that database is the boundary — a column holding
+  // one constant value in every row would buy nothing, which is the same
+  // reason xeplr_bi and the auth DBs do not have one either.
+  //
+  // The identity is still REQUIRED, because this mount also writes to
+  // xeplr_configs — the one store that genuinely is shared by every app and
+  // cannot be split per consumer (reference data, plus import_meta). Rows
+  // there are attributed by applicationId, so a mount that skipped this would
+  // quietly file its movement metadata under the package name instead of the
+  // product's.
+  //
+  // Inherited by default: a host registers itself once at boot and every
+  // sub-product it mounts picks it up with no further wiring. config
+  // .applicationId is accepted for a host that would rather be explicit, and
+  // is idempotent under the same value.
+  if (config.applicationId) registerApplication(config.applicationId);
+  if (!getApplicationId()) {
+    throw new Error(
+      'registerWorkflow: no application registered. Call registerApplication("<this-product>") ' +
+      'from @xeplr/db once at host startup (or pass config.applicationId). It attributes the ' +
+      'rows this mount writes to the SHARED xeplr_configs database; workflow\'s own tables are ' +
+      'separated by having their own database, not by this.');
+  }
+
+  await connectDb(config.db);
+
+  // ITS OWN TABLES, ITS OWN JOB — for the same reason config.db is required in
+  // both modes. This lived in orchestration/standalone.js, so a host that
+  // embedded workflow got a connection to a database with none of workflow's
+  // tables in it, and the first request failed on a missing relation.
+  //
+  // Idempotent, so a host that also runs them loses nothing by this.
+  //
+  // The migrator resolves its connection BY NAME from a registry that
+  // getConnection above does not populate, so the name has to be resolved
+  // explicitly first. Without this an embedded mount died on
+  // 'No resolved config for "WORKFLOW"' and the whole product silently did
+  // not appear — while every /workflow/* path still answered 401, because the
+  // host's auth middleware runs before routing and a missing route never got
+  // the chance to 404.
+  var migrationConnection = config.db.connectionName || 'workflow';
+  await resolveConfig(migrationConnection, config.db.connection);
+
+  // CREATE IT IF IT IS NOT THERE. Each host gives workflow its own database
+  // (xeplr_bi_workflow, xeplr_erp_workflow) — that separation is the entire
+  // isolation model, so pointing a host at a name that does not exist yet is
+  // the NORMAL first boot, not an error state. Without this it failed on
+  // "database does not exist" and every host had to run a manual createdb
+  // that nothing in the config hinted at. Same as @xeplr/email does.
+  var ensured = await ensureDatabaseFor(config.db.connection, config.db.name);
+  if (ensured.created) console.log('[workflow] created database ' + config.db.name);
+  // XEPLR_WORKFLOW_MIGRATIONS — a host adds its own tables or seed rows to
+  // workflow's database without editing this package. Same convention as
+  // every other xeplr library (see @xeplr/db's app-migrations.js); config
+  // .migrations lets an embedding host pass them directly instead, since a
+  // host that already has the paths in code should not have to route them
+  // back out through the environment.
+  var migrated = await up({
+    db: config.db.name,
+    dir: path.join(__dirname, 'migrations'),
+    extDir: config.migrations || migrationsFor('workflow'),
+    type: 'precede',
+    connectionName: migrationConnection
+  });
+  if (migrated.migrations.length) {
+    console.log('[workflow] ran ' + migrated.migrations.length + ' migrations');
+  }
+
+
+  // THE ACTION CATALOG, for the same reason the migrations above moved here.
+  // This lived only in orchestration/standalone.js, so an embedded host got a
+  // mounted product whose registry was empty: GET /actions answered 200 with
+  // an empty list, the step editor's Action dropdown drew nothing, and there
+  // was no error anywhere to explain why — the one failure mode the whitelist
+  // in lib/actionCatalog.js is otherwise careful to make loud.
+  //
+  // Idempotent (register() overwrites by name), so a host that somehow also
+  // registers them loses nothing.
+  //
+  // xeplr_configs is best-effort HERE and fail-fast in standalone, and the
+  // difference is deliberate: standalone owns its whole process and should
+  // refuse to boot half-configured, whereas failing a host's mount over one
+  // action that records movement metadata would take down a product that is
+  // otherwise entirely functional. The warning names what was lost.
+  try {
+    await xcfgSetup.ready();
+  } catch (err) {
+    console.warn('[workflow] xeplr_configs unavailable (' + err.message + ') — actions needing it are not offered');
+  }
+  var registered = actionCatalog.registerAll();
+  console.log('[workflow] registered ' + registered.length + ' actions: ' + registered.join(', '));
+
+  // Say out loud what step templates can read out of the environment. Silent
+  // by default (nothing exposed unless WORKFLOW_ENV_EXPOSED names it), so a
+  // line here means somebody opted in — and a list that accidentally names a
+  // secret is only catchable if it is visible somewhere.
+  envExposed.logExposure();
+
+  var router = buildWorkflowRouter(config);
+
+  // THE FLOWS FACADE, ALSO ON ITS OWN. It is already inside `router` at
+  // <mount>/flows, which is all most hosts need. This second, independent
+  // instance is for a host that wants to serve it from a path of its own —
+  // routes['/flows'] = flowsRouter, beside routes['/workflow'] = router —
+  // because the app designing the screens is not the app that mounted the
+  // workflow builder and should not have to reach through its URL space.
+  //
+  // Same builder, same config, and it gates itself, so the two mounts are
+  // interchangeable rather than merely similar. Mounting both is fine; they
+  // share nothing but the database.
+  var flowsRouter = buildFlowsRouter(config);
+
+  if (config.app) {
+    config.app.use(config.mountPath || '/workflow', router);
+    return { router: router, flowsRouter: flowsRouter, app: config.app };
+  }
+
+  // No app to mount onto and no port to listen on: the caller wants the
+  // router itself. See the note on config.app.
+  if (!config.port) return { router: router, flowsRouter: flowsRouter };
+
+  var mountPath = config.mountPath || '/workflow';
+  var routes = {};
+  routes[mountPath] = router;
+
+  var built = createApp(config.port, config.appName || 'xeplr_workflow_api', {
+    // Passed through, NOT defaulted here: undefined means createApp's own
+    // default, which is gated. Only reached in STANDALONE mode — an embedded
+    // mount returns above, and its host's own app already carries a gate.
+    auth: config.auth,
+    log: config.log,
+    middleware: config.middleware || [],
+    routes: routes
+  });
+
+  return { router: router, flowsRouter: flowsRouter, app: built.app, server: built.server };
+}
+
+// Env vars a HOST embedding workflow must supply — spread into the host's
+// env.required.js so a missing one fails at startup rather than at mount:
+//
+//   ...require('@xeplr/workflow').embedRequiredEnv,   // DB_WORKFLOW
+//
+// Named `embedRequiredEnv`, not `requiredEnv`, because it is not the same
+// list as this package's OWN standalone process needs (see env.required.js,
+// which uses DB_API for the very same database — a standalone deployment
+// names its own store, an embedded one is given a separate one by its host).
+// Two deployments, two questions, two lists.
+//
+// DB_WORKFLOW only: the SERVER login comes from the shared
+// XEPLR_DB_CONNECTION, and workflow never reads either itself — the host
+// passes both into registerWorkflow({ db }). This list exists so the host is
+// told what to pass before it boots.
+var embedRequiredEnv = [
+  'DB_WORKFLOW'
+];
+
+/**
+ * Resume a run parked on a 'wait' step. THE ENTIRE consumer-side contract for
+ * waiting — the caller never needs to know which run or step the key belongs
+ * to, because that lookup lives in workflow_resume_keys alone.
+ *
+ *   var { resumeByKey } = require('@xeplr/workflow');
+ *   await resumeByKey(key, { confirmedBy: userId });
+ *
+ * SERVER-SIDE, IN-PROCESS, DELIBERATELY. This is not something a browser
+ * calls. The host's own route — the activation link's landing route, the
+ * confirm button's POST — does its own work (activate the account, record the
+ * approval) and then calls this in the same request. The key travels out
+ * bound into that route's URL via `{resumeKey}` and comes back to the host,
+ * never to workflow's own HTTP surface.
+ *
+ * That is the whole reason it is exported here rather than left as a route: a
+ * resume is a step in the host's transaction, not a separate thing a client
+ * is trusted to trigger.
+ *
+ * Throws with `err.code` set, which is what a host should branch on:
+ *
+ *   RESUME_KEY_INVALID    no live key — already used, unknown, or the run is
+ *                         gone. NORMAL for a host route that also serves
+ *                         users who never came from a workflow: catch it and
+ *                         carry on with your own work.
+ *   RESUME_KEY_NOT_READY  the key is real but its step has not parked yet
+ *                         (the action that delivers it is still running).
+ *                         Nothing is consumed — retry shortly.
+ *
+ * Requires registerWorkflow() to have run in this process: it is what
+ * connects workflow's database, and this reads through that same connection.
+ * Needs no ambient tenant context — the run carries its own mtIds and this
+ * re-enters them itself.
+ *
+ * @param {string} key    the value bound into the step as {resumeKey}
+ * @param {object} [output]  merged into the wait step's output, so later
+ *   steps can read it as {steps.<stepKey>.output.<name>}
+ * @param {object} [opts]
+ * @param {'success'|'failed'} [opts.status]  resolve the step as FAILED rather
+ *   than succeeded — from there the step's own `onError` decides, defaulting
+ *   to stopping the run. Omit for success, which is what every caller that
+ *   predates this means (an approval click, a confirmation link).
+ * @param {object} [opts.error]  recorded on the step run when status is
+ *   'failed'.
+ * @returns {Promise<{ runId: string, stepKey: string, status: string }>}
+ */
+async function resumeByKey(key, output, opts) {
+  return require('./lib/workflowRunner').resumeByKey(key, output, opts);
+}
+
+// REQUIRED ONLY IF YOU USE STEPS THAT CALL SOMETHING OUTSIDE THIS PROCESS —
+// today that is `job-run`. Kept as its own list, the same way @xeplr/email
+// separates `requiredEnv` (sending) from `templatesRequiredEnv` (the template
+// store): a host that only runs self-contained workflows is never made to
+// configure something it does not use.
+//
+// WORKFLOW_PUBLIC_URL is the base a CALLER can reach this service on, mount
+// path included — https://bi.example.com/workflow for an embedded mount. It is
+// what {resumeUrl} is built from, so a step can hand a job an address to
+// report back to.
+//
+// NOT DEFAULTED, and that is the point of it being here rather than having a
+// fallback: a wrong-but-present address gives a job somewhere to POST that
+// nothing is listening on, so the run waits forever on work that actually
+// finished. Unset, {resumeUrl} is null and job-run refuses by name before
+// starting anything.
+var callbackRequiredEnv = [
+  'WORKFLOW_PUBLIC_URL'
+];
+
+module.exports = {
+  registerWorkflow: registerWorkflow,
+  resumeByKey: resumeByKey,
+  embedRequiredEnv: embedRequiredEnv,
+  callbackRequiredEnv: callbackRequiredEnv
+};

package/lib/actionCatalog.js

@@ -0,0 +1,193 @@
+// WHAT THIS PRODUCT CAN BIND TOGETHER.
+//
+// @xeplr/actions ships the actions; this file decides which of them THIS app
+// offers, and registers them once at startup (see bin/www). Whatever a workflow
+// step turns out to be, it will name one of these — so the registry is
+// populated before the first request rather than lazily.
+//
+// A deliberate WHITELIST rather than "register everything the package exports",
+// for two reasons. Some built-ins are more dangerous than others —
+// spawnProgram runs arbitrary executables — and offering one should be a
+// decision somebody made, visible in a diff, not a side effect of upgrading a
+// dependency. And several entries in that package are PLACEHOLDERS: modules
+// with a comment saying the implementation is pending and nothing else in them.
+// Registering one would put a name in the catalog, draw it in the step picker,
+// and fail at the moment somebody relied on it.
+//
+// So the list below is names this app WANTS, and readiness is checked against
+// the package rather than assumed. A name that is not ready yet stays in the
+// list, out of the catalog, and lands the day the package implements it.
+var actions = require('@xeplr/actions');
+var xcfgSetup = require('../db/xcfgSetup');
+
+// The keys on @xeplr/actions' `builtins`, not the action names — those are
+// kebab-case and assigned by the modules themselves (`dbFetch` registers as
+// `db-fetch`). Naming the export is what makes this list checkable.
+var WANTED = [
+  'dbFetch',
+  'dbPush',
+  'dbQuery',
+  // Calling a procedure is its own step now — it used to be reachable only by
+  // running a movement, which meant a procedure that returns nothing could not
+  // be run at all.
+  'dbProcedure',
+  'dbListTables',
+  'dbListViews',
+  'dbListProcedures',
+  'dbListColumns',
+  'fileMove',
+
+  // Email. The five inbound ones are what a workflow monitors a mailbox with;
+  // emailSend is also what a `wait` step uses to deliver its own resume link
+  // (see workflowRunner's mintResumeKey — the key is available to the step's
+  // own action as {resumeKey}).
+  //
+  // emailDelete is offered but worth knowing about: it is a permanent expunge,
+  // not a move to Trash. emailMove to a trash folder is the reversible one.
+  'emailRead',
+  'emailMove',
+  'emailDelete',
+  'emailDownloadEmail',
+  'emailDownloadAttachments',
+  'sendEmail'
+];
+
+// THIS APP'S OWN ACTIONS — not from @xeplr/actions, and not placeholders.
+//
+// Glue between two products, which is exactly why it is not in the shared
+// action library: @xeplr/actions must not learn what a job is. Registered the
+// same way and appearing in the same catalog, so the step editor needs no
+// notion that some actions come from here and some from there.
+var LOCAL = [
+  require('./actions/jobRun')
+];
+
+// REGISTERED BUT NOT OFFERED.
+//
+// An action a step can legitimately name, that no author should ever pick off
+// a palette. The registry must have it — the engine resolves a step's
+// actionName through the registry, so a step naming an unregistered action
+// cannot run at all — but catalog() leaves it out, because the only thing that
+// knows how to build one of these steps is the facade that owns them.
+//
+// `screen-show` is the case: a screens flow's steps are generated by
+// lib/flows.js from a design held in another app, and one dropped by hand onto
+// the ordinary workflow canvas would park its run forever — nothing outside
+// that facade knows how to show the screen or how to resume it. Hiding it is
+// not secrecy; it is not offering half of something.
+var HIDDEN = [
+  require('./actions/screenShow')
+];
+
+var HIDDEN_NAMES = HIDDEN.map(function(def) { return def.name; });
+
+// Needs the control-plane connection to record what moved where, so it is
+// registered separately once xcfgSetup has resolved.
+var WANTED_WITH_META = ['fileUpload'];
+
+// DELIBERATELY ABSENT: spawnProgram. It runs arbitrary executables, which is a
+// different kind of permission from "call an HTTP endpoint" — named here so
+// that leaving it out reads as a decision rather than an oversight.
+
+/** A module the registry will actually accept, as opposed to a placeholder. */
+function isReady(def) {
+  return Boolean(def && typeof def.execute === 'function' && def.name);
+}
+
+function offer(key, def, registered, skipped) {
+  if (!isReady(def)) { skipped.push(key); return; }
+  actions.register(def);
+  registered.push(def.name);
+}
+
+/**
+ * Registers this app's actions and returns their names.
+ *
+ * Idempotent — @xeplr/actions' register() overwrites by name, so calling this
+ * twice leaves the registry in the same state rather than doubling it.
+ */
+function registerAll() {
+  var registered = [];
+  var skipped = [];
+
+  WANTED.forEach(function(key) {
+    offer(key, actions.builtins[key], registered, skipped);
+  });
+
+  LOCAL.forEach(function(def) {
+    offer(def.name, def, registered, skipped);
+  });
+
+  // Same registration, no catalog entry — see HIDDEN.
+  HIDDEN.forEach(function(def) {
+    offer(def.name, def, registered, skipped);
+  });
+
+  WANTED_WITH_META.forEach(function(key) {
+    var entry = actions.builtins[key];
+    // Factory-shaped in some versions, a plain module in others. Both are
+    // handled rather than asserted, because which one it is is the package's
+    // business and not worth breaking a boot over.
+    //
+    // Guarded because reading xcfgSetup.metaStore THROWS when the
+    // control-plane connection was never established — which is a real state
+    // for an embedded host (see registerWorkflow, where xeplr_configs is
+    // best-effort). Losing one action to that is correct; losing the whole
+    // catalog, and with it every other action, is not.
+    try {
+      var def = typeof entry === 'function' ? entry({ metaKnex: xcfgSetup.metaStore }) : entry;
+      offer(key, def, registered, skipped);
+    } catch (err) {
+      console.warn('[actions] ' + key + ' could not be registered: ' + err.message);
+      skipped.push(key);
+    }
+  });
+
+  // Said out loud, once, at startup. A name silently missing from the picker is
+  // a bug somebody spends an afternoon on; a line in the boot log is not.
+  if (skipped.length) {
+    console.warn('[actions] not yet implemented in @xeplr/actions, so not offered: ' + skipped.join(', '));
+  }
+
+  return registered;
+}
+
+/**
+ * The catalog, as the UI needs it: name, description and the INPUT SCHEMA that
+ * describes what each one takes.
+ *
+ * The schema is the point. A step editor told separately what an action accepts
+ * is a second description of it, and the day the two disagree the form collects
+ * a field the action ignores. Sending the registry's own schema means the form
+ * is generated from the thing it is a form for.
+ *
+ * The EXECUTOR is not sent, and could not usefully be — it is a function, it
+ * would not survive JSON, and an endpoint that hands out executors is an
+ * endpoint that explains how to bypass itself.
+ */
+function catalog() {
+  return actions.list().filter(function(a) {
+    // HIDDEN is registered, so the engine can run a step that names it, and
+    // absent here, so no palette ever draws it. Filtered at the point the list
+    // leaves the process rather than by not registering it — the two questions
+    // ("can this run" and "should anyone pick it") have different answers.
+    return HIDDEN_NAMES.indexOf(a.name) === -1;
+  }).map(function(a) {
+    return {
+      name: a.name,
+      description: a.description,
+      inputSchema: a.inputSchema,
+      outputSchema: a.outputSchema
+    };
+  });
+}
+
+module.exports = {
+  registerAll: registerAll,
+  catalog: catalog,
+  isReady: isReady,
+  WANTED: WANTED,
+  WANTED_WITH_META: WANTED_WITH_META,
+  LOCAL: LOCAL,
+  HIDDEN: HIDDEN
+};

package/lib/actions/jobRun.js

@@ -0,0 +1,149 @@
+// job-run — START A JOB AND PARK UNTIL IT REPORTS BACK.
+//
+// The step behind an arrow on the "connect jobs" canvas. Everything it does is
+// two HTTP calls' worth of glue between two products that do not import each
+// other:
+//
+//   1. POST <jobsUrl>/jobs/<jobId>/trigger  { inputs, callbackUrl }
+//   2. return — the STEP does not finish here. It is a `wait` step, so the run
+//      parks, and @xeplr/jobs POSTs the outcome to callbackUrl when the
+//      occurrence reaches a terminal state, which resumes it.
+//
+// ── why it does not wait for the job ─────────────────────────────────────
+//
+// A movement runs for twenty minutes. Holding an await open across that would
+// tie a run's progress to one process staying alive, and a deploy in the
+// middle would lose it with nothing recording why. The resume key is a row in
+// a table: it survives a restart, and it is the same mechanism an emailed
+// approval link has always used.
+//
+// ── THIS IS TEMPORARY, AND SHOULD BE DELETED ─────────────────────────────
+//
+// Nothing here is about jobs except the URL shape and the field named
+// `callbackUrl`. The general form is @xeplr/actions' `http-request` (today a
+// placeholder) called from a wait step with `{resumeUrl}` bound into its body,
+// which would serve jobs, saved API calls and anything else that can honour
+// the callback contract. This exists so the jobs canvas can be finished
+// first; when http-request lands, a job step becomes a configuration of it and
+// this file goes away.
+//
+// It lives in xeplr-workflow rather than in @xeplr/actions deliberately: it is
+// glue between two products, and putting it in the shared action library would
+// teach that library what a job is.
+
+var CALLBACK_UNREACHABLE =
+  'This step starts a job and waits for it to report back, but WORKFLOW_PUBLIC_URL ' +
+  'is not set, so there is no address to give the job to call. Set it to the base ' +
+  'URL this service is reachable on (including any mount path — e.g. ' +
+  'https://bi.example.com/workflow) and run this again.';
+
+module.exports = {
+  name: 'job-run',
+  description: 'Run a saved job and wait for it to finish. The job reports its outcome back, ' +
+               'so the next step runs only once it has actually completed.',
+  requires: [],
+
+  inputSchema: [
+    { name: 'jobsUrl', type: 'string', required: true, order: 1,
+      description: 'Base URL of the jobs API — e.g. https://bi.example.com/api' },
+    { name: 'jobId', type: 'string', required: true, order: 2,
+      description: 'The job to run.' },
+    { name: 'callbackUrl', type: 'string', required: true, order: 3,
+      description: 'Where the job reports its outcome. Bind this to {resumeUrl} — the canvas ' +
+                   'does it for you; it is the address of this step\'s own resume key.' },
+    { name: 'inputs', type: 'object', order: 4, group: 'Advanced',
+      description: 'Values to override the job\'s saved inputs, for this run only. The job row ' +
+                   'is not changed. Commonly a window: { window: { from, to } }.' },
+    { name: 'timeoutMs', type: 'number', default: 30000, order: 5, group: 'Advanced',
+      description: 'How long to wait for the TRIGGER call to be accepted. Nothing to do with ' +
+                   'how long the job itself may run — that is the job\'s own timeout.' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+
+    // The binding resolved to nothing, which means WORKFLOW_PUBLIC_URL is
+    // unset (see workflowRunner's publicResumeUrl). Caught HERE, before the
+    // job is started, because the alternative is a job that runs perfectly for
+    // twenty minutes and then has nowhere to report to — leaving the step
+    // waiting forever on work that actually succeeded.
+    if (!input.callbackUrl) throw new Error(CALLBACK_UNREACHABLE);
+
+    // THE SAME CHECK FOR THE OTHER BINDING, and it needs its own message.
+    //
+    // The canvas fills jobsUrl with `{env.JOBS_API_URL}`, and the engine
+    // resolves an unknown binding to the EMPTY STRING rather than failing —
+    // so an unset (or unexposed) variable arrives here as '' and satisfies
+    // `required`, which only rejects null and undefined. Left alone that
+    // becomes fetch('/jobs/j1/trigger') and a "Failed to parse URL" nobody can
+    // trace back to an environment variable.
+    //
+    // Both halves are named because either one alone is the cause: the
+    // variable can be set and simply not listed in WORKFLOW_ENV_EXPOSED, which
+    // is exactly as invisible.
+    var jobsUrl = String(input.jobsUrl || '').trim();
+    if (!/^https?:\/\//i.test(jobsUrl)) {
+      throw new Error('This step needs the address of the jobs API and got ' +
+        (jobsUrl ? '"' + jobsUrl + '"' : 'nothing') + '. It is normally bound to ' +
+        '{env.JOBS_API_URL}, which resolves to an empty string unless JOBS_API_URL is set ' +
+        'AND named in WORKFLOW_ENV_EXPOSED — check both. It must be absolute, e.g. ' +
+        'https://bi.example.com/api');
+    }
+
+    var base = jobsUrl.replace(/\/+$/, '');
+    var url = base + '/jobs/' + encodeURIComponent(input.jobId) + '/trigger';
+
+    var controller = new AbortController();
+    var timer = setTimeout(function() { controller.abort(); }, input.timeoutMs || 30000);
+    if (timer.unref) timer.unref();
+
+    var res;
+    try {
+      res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          inputs: input.inputs || undefined,
+          callbackUrl: input.callbackUrl
+        }),
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+
+    // BUSY IS A FAILURE, NOT A WAIT.
+    //
+    // A job holds one lock and runs one at a time. Treating 409 as "try again
+    // shortly" would mean a chain that quietly continues past a movement that
+    // never ran, and the step after it aggregating a period nothing loaded.
+    // Failing here stops the run, which is what the step's own onError already
+    // defaults to.
+    if (res.status === 409) {
+      throw new Error('Job ' + input.jobId + ' is already running, so this step cannot start it. ' +
+        'Wait for the current run to finish, or schedule these so they do not overlap.');
+    }
+
+    if (!res.ok) {
+      var detail = await res.text().catch(function() { return ''; });
+      throw new Error('Could not start job ' + input.jobId + ' — the jobs API answered ' +
+        res.status + (detail ? ': ' + detail.slice(0, 300) : '') + '.');
+    }
+
+    var body = await res.json().catch(function() { return {}; });
+    var row = (body.dataArray && body.dataArray[0]) || {};
+
+    // WHAT THIS STEP KNOWS SO FAR — the handle, not the result.
+    //
+    // The occurrence's outcome arrives later, through the callback, and
+    // resumeByKey MERGES it over this. So a downstream binding of
+    // {steps.<key>.output.occurrenceId} works from the moment the job starts,
+    // and {steps.<key>.output.output.totalRows} works once it has finished.
+    return {
+      jobId: input.jobId,
+      occurrenceId: row.occurrenceId || null,
+      startedAt: new Date().toISOString(),
+      status: 'running'
+    };
+  }
+};