@xeplr/workflow-engine 3.1.0 → 3.2.1

package/README.md

@@ -105,6 +105,10 @@ host gives workflow is the boundary.
   first match wins (`@xeplr/expression-handler`); a blank condition is the
   catch-all; targets are a `stepKey`, `end_success` or `end_failed`. No match
   and no catch-all **fails the run**.
+- **Screens hand over to screens**: a flow's run view carries `previous` — what
+  every screen submitted earlier in the run, keyed by screen key, the saved row
+  as `values.id` (`lib/flows.js` `previousOf`). Read-only, built from the step
+  runs; nothing new is stored, and nothing is checked between screens.
 - **Letting a function decide**: a transition `{ decide: 'routeByAmount', targets?: [...] }`
   asks a function the app registered with `@xeplr/actions` under `event: 'decide'`
   where to go. It is called with `{ output, values (= output), params, item, trigger,
@@ -113,7 +117,8 @@ host gives workflow is the boundary.
   function, one written for another event, no answer, or an answer outside
   `targets` **fails the run**, naming the function. Functions registered with an
   `event` are screen functions, never steps: the action catalog leaves them out.
-- **Fan-out**: a matching `each` transition creates one child run per matching
+- **Fan-out**: a matching `each` transition goes through the list its `source`
+  names (`output.rows`, `item.lines`, `params.…`, `trigger.…`) and creates one child run per matching
   element (`item`), recorded in `workflow_run_edges`. With `joinStep` the parent
   waits and resumes at the join once all children are terminal (guarded by an
   atomic `waiting → running` patch); without it the parent finishes.
@@ -162,7 +167,9 @@ The same rules hold for every kind:
 - A trigger seen for the first time, or whose settings changed, is given its next due time and does **not** fire, so publishing never starts a run for a time already past.
 - A due trigger is **claimed** by a conditional update of its due time, so two processes running the tick start it once.
 
-**A host's own kinds.** `registerTrigger(kind, { validate, due?, matches? })`:
+**What a designer offers.** `triggers.catalog()` lists every kind as `{ kind, label, description, fields }`, where `fields` are the form's boxes (`{ name, label, placeholder?, help?, required?, options? }`). The API serves it at `GET /workflow/triggers`. A designer builds its trigger form from it, so it never offers a kind this engine refuses (one once offered "A file arrives", which no engine had).
+
+**A host's own kinds.** `registerTrigger(kind, { label?, description?, fields?, validate, due?, matches? })`:
 - a time kind gives `due(trigger, from)`, its next due `Date`;
 - an event kind gives `matches(trigger, event)`, and the host calls `triggers.emit(kind, event)` when the event happens.
 
@@ -180,6 +187,14 @@ The comparisons are the flows facade's: `=`, `!=`, `>`, `>=`, `<`, `<=`, `contai
 
 A bad `when` is refused when it is saved, naming the step and the arrow. That is how a screen of your own (and the jobs screen's "After this job") writes branches without knowing the node format.
 
+**An arrow the runner could not follow is refused when it is saved** (`checkArrow`, code `TRANSITION_INVALID`, naming the step and arrow):
+- `mode` is `single` (the default) or `each`;
+- an arrow needs a `target` (a step key, `end_success` or `end_failed`), unless it names a `decide` function;
+- an `each` arrow needs `source`, the list it goes through, starting with `output`, `item`, `params` or `trigger`;
+- an arrow either decides or goes through a list, not both, and `targets` is a list of step keys.
+
+Why: each of these used to save, and then the live run ended with "No transition matched". A designer once saved every `each` arrow without its `source`, so nothing ever fanned out.
+
 ## Jobs as steps and as triggers (`lib/jobs.js`)
 
 A job meets a workflow in two places, and both are ordinary workflows:

package/lib/conditions.js

@@ -62,11 +62,51 @@ function whenToCondition(when, where) {
 function compileTransitions(transitions, stepName) {
   if (!Array.isArray(transitions)) return transitions;
   return transitions.map(function(t, i) {
-    if (!t || typeof t !== 'object' || t.when === undefined) return t;
+    var where = (stepName ? 'Step "' + stepName + '"' : 'A step') + ', arrow ' + (i + 1);
+    checkArrow(t, where);
+    if (t.when === undefined) return t;
     var out = Object.assign({}, t);
-    out.condition = whenToCondition(t.when, (stepName ? 'Step "' + stepName + '"' : 'A step') + ', arrow ' + (i + 1));
+    out.condition = whenToCondition(t.when, where);
     return out;
   });
 }
 
-module.exports = { whenToCondition: whenToCondition, compileTransitions: compileTransitions };
+// What an arrow may be. Each of these used to save and then fail on the live
+// run instead: an "each" arrow without its list matched nothing, and the run
+// ended with "No transition matched" (workflowRunner's routeAfterStep).
+var ARROW_MODES = ['single', 'each'];
+var SOURCE_ROOTS = ['output', 'item', 'params', 'trigger'];
+
+function invalidArrow(message) {
+  var err = invalid(message);
+  err.code = 'TRANSITION_INVALID';
+  err.data = { transitions: [{ message: message, keyword: 'transition' }] };
+  return err;
+}
+
+/** Refuses an arrow the runner could not follow, naming the step and arrow. */
+function checkArrow(t, where) {
+  if (!t || typeof t !== 'object' || Array.isArray(t)) throw invalidArrow(where + ': an arrow must be an object such as { "target": "next-step" }.');
+  if (t.mode !== undefined && t.mode !== null && ARROW_MODES.indexOf(t.mode) === -1) {
+    throw invalidArrow(where + ': "' + t.mode + '" is not a kind of arrow. Kinds: ' + ARROW_MODES.join(', ') + '.');
+  }
+  if (t.decide !== undefined && t.decide !== null) {
+    if (typeof t.decide !== 'string' || !t.decide.trim()) throw invalidArrow(where + ': `decide` names a registered function.');
+    if (t.mode === 'each') throw invalidArrow(where + ': an arrow either lets a function decide or goes through a list, not both.');
+    if (t.targets !== undefined && t.targets !== null &&
+        (!Array.isArray(t.targets) || t.targets.some(function(k) { return typeof k !== 'string' || !k; }))) {
+      throw invalidArrow(where + ': `targets` is a list of step keys.');
+    }
+    return;
+  }
+  if (typeof t.target !== 'string' || !t.target.trim()) throw invalidArrow(where + ': say where it goes (`target`): a step key, end_success or end_failed.');
+  if (t.mode === 'each') {
+    var source = typeof t.source === 'string' ? t.source.trim() : '';
+    if (!source) throw invalidArrow(where + ': an arrow for each item needs the list to go through (`source`), e.g. "output.rows".');
+    if (!FIELD_PATTERN.test(source) || SOURCE_ROOTS.indexOf(source.split('.')[0]) === -1) {
+      throw invalidArrow(where + ': "' + source + '" is not a list it can read. Start it with ' + SOURCE_ROOTS.join(', ') + ', e.g. "output.rows".');
+    }
+  }
+}
+
+module.exports = { whenToCondition: whenToCondition, compileTransitions: compileTransitions, checkArrow: checkArrow, ARROW_MODES: ARROW_MODES };

package/lib/flows.js

@@ -597,7 +597,9 @@ function runView(run, steps, stepRuns) {
     // the resolved input is kept (workflowRunner patches `input` as it parks)
     // — the step row holds the tokens, and a browser has nothing to resolve
     // them with.
-    given: {}
+    given: {},
+    // WHAT THE SCREENS BEFORE THIS ONE SAVED, by screen key — see previousOf.
+    previous: {}
   };
   if (!waiting) {
     if (run.status === 'failed' && run.error) view.error = run.error;
@@ -614,9 +616,43 @@ function runView(run, steps, stepRuns) {
     if (sr.stepKey !== waiting.stepKey) return;
     Object.assign(view.values, sr.output || {});
   });
+  view.previous = previousOf(steps, stepRuns, waiting);
   return view;
 }
 
+/**
+ * THE HAND-OVER BETWEEN SCREENS — what every screen submitted earlier in this
+ * run, keyed by the SCREEN's key:
+ *
+ *   { department_edit: { values: { id: "6f2a…", name: "Finance", … } } }
+ *
+ * A field on the next screen fills itself from it with a default of
+ * `{previous.department_edit.values.name}` (@xeplr/ui-factory). By screen and
+ * not by step, because the binding lives ON the screen, and a screen is the
+ * same form in every flow that shows it. `id` is the row that screen saved —
+ * part of the values, as it is of the row.
+ *
+ * Nothing is checked: a screen not reached on this run's branch is simply
+ * absent, and a binding to it comes out empty. A screen shown twice (a loop)
+ * hands over its latest. The step being shown now is not its own "previous".
+ */
+function previousOf(steps, stepRuns, waiting) {
+  var screenOf = {};
+  steps.forEach(function(st) {
+    if (st.actionName === SCREEN_ACTION && st.values && st.values.screen) screenOf[st.stepKey] = st.values.screen;
+  });
+  var out = {};
+  stepRuns.forEach(function(sr) {
+    if (sr.status !== 'success' || (waiting && sr.id === waiting.id)) return;
+    var screen = screenOf[sr.stepKey];
+    if (!screen) return;
+    var values = Object.assign({}, sr.output || {});
+    if (values.recordId !== undefined) { values.id = values.recordId; delete values.recordId; }
+    out[screen] = { values: values };
+  });
+  return out;
+}
+
 async function stepRunsOf(runId) {
   return db.model('WorkflowStepRun').query().where({ runId: runId }).orderBy('recordCreatedDate', 'asc');
 }
@@ -937,6 +973,7 @@ module.exports = {
   fail: fail,
   END_TARGETS: END_TARGETS,
   conditionToWhen: conditionToWhen,
+  previousOf: previousOf,
   toStepRows: toStepRows,
   validateFlow: validateFlow,
   runView: runView,

package/lib/triggers.js

@@ -54,6 +54,19 @@ function registerTrigger(kind, def) {
 
 function kinds() { return Object.keys(KINDS); }
 
+/**
+ * Every kind, as a designer offers it: { kind, label, description, fields }.
+ * `fields` is what the form asks for ({ name, label, placeholder?, help?,
+ * required?, options? }). A designer builds its trigger form from this rather
+ * than from its own list, so it never offers a kind this engine refuses.
+ */
+function catalog() {
+  return Object.keys(KINDS).map(function(k) {
+    var d = KINDS[k];
+    return { kind: k, label: d.label || k, description: d.description || '', fields: d.fields || [] };
+  });
+}
+
 function common(trigger) {
   var out = { kind: trigger.kind };
   if (trigger.enabled === false) out.enabled = false;
@@ -61,17 +74,26 @@ function common(trigger) {
 }
 
 registerTrigger('manual', {
+  label: 'Someone presses Start',
   description: 'Someone presses Start.',
+  fields: [],
   validate: common
 });
 
 registerTrigger('api', {
+  label: 'Another system calls it',
   description: 'Another system starts it through the API.',
+  fields: [],
   validate: common
 });
 
 registerTrigger('schedule', {
+  label: 'On a schedule',
   description: 'On a schedule — a cron expression, e.g. "0 9 * * 1" for Mondays at 9.',
+  fields: [
+    { name: 'cron', label: 'When', placeholder: '0 9 * * 1', help: 'Minute hour day month weekday', required: true },
+    { name: 'timezone', label: 'Time zone', placeholder: 'Asia/Kolkata', help: 'Empty: the server\'s' }
+  ],
   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).');
@@ -92,7 +114,14 @@ registerTrigger('schedule', {
 });
 
 registerTrigger('job', {
+  label: 'A job finishes',
   description: 'When a job finishes — successfully, with a failure, or either way.',
+  fields: [
+    { name: 'jobId', label: 'Job', placeholder: 'the job\'s id', required: true },
+    { name: 'when', label: 'When it', options: [
+      { value: 'success', label: 'succeeds' }, { value: 'failed', label: 'fails' }, { value: 'finished', label: 'finishes 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.');
@@ -286,6 +315,7 @@ async function describe(workflow) {
 module.exports = {
   registerTrigger: registerTrigger,
   kinds: kinds,
+  catalog: catalog,
   validate: validate,
   isOn: isOn,
   fire: fire,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/workflow-engine",
-  "version": "3.1.0",
+  "version": "3.2.1",
   "license": "MIT",
   "description": "The free workflow engine: runs, actions as steps, branching, waits, and triggers — manual, API, a schedule, a job finishing. No HTTP: @xeplr/workflow-api puts the routes on top.",
   "keywords": [