@onify/flow-extensions 0.0.1

package/index.js

@@ -0,0 +1,330 @@
+import cronParser from 'cron-parser';
+import IOProperties from './src/IOProperties';
+import IOForm from './src/IOForm';
+import Connector from './src/Connector';
+import ServiceExpression from './src/ServiceExpression';
+import {InputOutput} from './src/IO';
+
+class FormatError extends Error {
+  constructor(elementId, err) {
+    super(`<${elementId}> ${err.message}`);
+    this.code = 'EFLOW_FORMAT';
+    this.output = {statusCode: 500};
+  }
+}
+
+export {
+  extensions,
+  extendFn,
+};
+
+function extensions(element, context) {
+  if (element.type === 'bpmn:Process') return new OnifyProcessExtensions(element, context);
+  return new OnifyElementExtensions(element, context);
+}
+
+class OnifyProcessExtensions {
+  constructor(bp, context) {
+    this.process = bp;
+    this.context = context;
+    this.extensions = getExtensions(bp, context);
+    this._activate();
+  }
+  _activate() {
+    const bp = this.process;
+    bp.on('process.enter', (elementApi) => {
+      try {
+        const result = this._onEnter(elementApi);
+        const environment = elementApi.environment;
+        environment.assignVariables(result);
+      } catch (err) {
+        elementApi.broker.publish('event', 'process.error', {
+          ...elementApi.content,
+          error: new FormatError(bp.id, err)
+        }, {mandatory: true, type: 'error'});
+      }
+    }, {consumerTag: '_onify-extension-on-enter'});
+  }
+  _onEnter(elementApi) {
+    const {format, properties} = this.extensions;
+    const result = {};
+
+    Object.assign(result, format.resolve(elementApi));
+    Object.assign(elementApi.content, result);
+
+    if (properties) {
+      Object.assign(result, properties.resolve(elementApi));
+      Object.assign(elementApi.content, result);
+    }
+
+    return result;
+  }
+}
+
+class OnifyElementExtensions {
+  constructor(activity, context) {
+    this.activity = activity;
+    this.context = context;
+    const {Service} = this.extensions = getExtensions(activity, context);
+    if (Service) {
+      activity.behaviour.Service = Service;
+    }
+  }
+  activate() {
+    const activity = this.activity;
+    const broker = activity.broker;
+    const formatQ = activity.broker.getQueue('format-run-q');
+
+    activity.on('enter', async (elementApi) => {
+      formatQ.queueMessage({routingKey: 'run.enter.format'}, {endRoutingKey: 'run.enter.complete'}, {persistent: false});
+
+      try {
+        var format = await this._onEnter(elementApi);
+      } catch (err) {
+        return broker.publish('format', 'run.enter.error', {error: err}, {persistent: false});
+      }
+
+      broker.publish('format', 'run.enter.complete', format, {persistent: false});
+    }, {consumerTag: '_onify-extension-on-enter'});
+
+    activity.on('activity.execution.completed', async (elementApi) => {
+      if (elementApi.fields.redelivered) return;
+
+      formatQ.queueMessage({routingKey: 'run.end.error'}, {endRoutingKey: 'run.end.complete'}, {persistent: false});
+
+      try {
+        var format = await this._onExecuted(elementApi);
+      } catch (err) {
+        return broker.publish('format', 'run.enter.error', {error: err}, {persistent: false});
+      }
+
+      broker.publish('format', 'run.end.complete', {...format}, {persistent: false});
+    }, {consumerTag: '_onify-extension-on-executed'});
+  }
+  deactivate() {
+    const broker = this.activity.broker;
+    broker.cancel('_onify-extension-on-enter');
+    broker.cancel('_onify-extension-on-executed');
+  }
+  async _onEnter(elementApi) {
+    const {format, properties, io, form} = this.extensions;
+
+    const result = {};
+    Object.assign(result, format.resolve(elementApi));
+    Object.assign(elementApi.content, result);
+
+    if (properties) {
+      Object.assign(result, {properties: properties.resolve(elementApi)});
+      Object.assign(elementApi.content, result);
+    }
+
+    if (io) {
+      if (io.input?.length) {
+        const input = await io.getInput(this.activity, elementApi);
+        Object.assign(result, {input});
+        Object.assign(elementApi.content, result);
+      }
+      if (io.output?.length) {
+        result.assignToOutput = true;
+      }
+    }
+
+    if (form) {
+      Object.assign(result, {form: form.resolve(elementApi)});
+    }
+
+    return result;
+  }
+  async _onExecuted(elementApi) {
+    const {properties, io} = this.extensions;
+
+    const result = {};
+    if (io?.output.length) {
+      const output = await io.getOutput(this.activity, elementApi);
+      Object.assign(result, {output});
+      Object.assign(elementApi.content, {output});
+    }
+
+    if (properties) {
+      const props = properties.resolve(elementApi);
+      Object.assign(result, {properties: props});
+      Object.assign(elementApi.content, {properties: props});
+    }
+
+    const {output, assignToOutput, resultVariable} = elementApi.content;
+
+    if (output === undefined || output === null) return result;
+
+    if (assignToOutput && typeof output === 'object') {
+      Object.assign(this.activity.environment.output, output);
+    } else if (resultVariable) {
+      elementApi.environment.output[resultVariable] = output;
+    }
+
+    return result;
+  }
+}
+
+function getExtensions(element, context) {
+  const result = {
+    format: element.type === 'bpmn:Process' ? new FormatProcess(element) : new FormatActivity(element),
+  };
+
+  const expression = element.behaviour.expression;
+  if (expression) result.Service = ServiceExpression;
+
+  const extensions = element.behaviour.extensionElements?.values;
+  if (!extensions) return result;
+
+
+  for (const ext of extensions) {
+    switch (ext.$type) {
+      case 'camunda:Properties':
+        if (ext.values?.length) result.properties = new IOProperties(element, ext);
+        break;
+      case 'camunda:InputOutput':
+        result.io = new InputOutput(element.id, ext, context);
+        break;
+      case 'camunda:FormData':
+        if (ext.fields?.length) result.form = new IOForm(element, ext);
+        break;
+      case 'camunda:Connector': {
+        const {connectorId, inputOutput} = ext;
+        const io = inputOutput && new InputOutput(`${element.id}/${ext.$type.toLowerCase()}`, inputOutput, context);
+        result.Service = Connector.bind(Connector, connectorId, io);
+        break;
+      }
+    }
+  }
+
+  return result;
+}
+
+class FormatActivity {
+  constructor(activity) {
+    this.activity = activity;
+    this.resultVariable = activity.behaviour.resultVariable || '_' + activity.id;
+
+    let timeCycles;
+    if (activity.eventDefinitions) {
+      for (const ed of activity.eventDefinitions.filter((e) => e.type === 'bpmn:TimerEventDefinition')) {
+        if (!('timeCycle' in ed)) continue;
+        timeCycles = timeCycles || [];
+        timeCycles.push(ed.timeCycle);
+      }
+    }
+    this.timeCycles = timeCycles;
+  }
+  resolve(elementApi) {
+    let user, groups, assigneeValue, description;
+    const activity = this.activity;
+    const {
+      documentation,
+      candidateUsers,
+      candidateGroups,
+      scheduledStart,
+      assignee,
+    } = activity.behaviour;
+
+    if (candidateUsers) user = resolveAndSplit(elementApi, candidateUsers);
+    if (candidateGroups) groups = resolveAndSplit(elementApi, candidateGroups);
+    if (assignee) assigneeValue = elementApi.resolveExpression(assignee);
+    if (documentation) description = documentation[0]?.text;
+
+    let expireAt;
+    let timeCycles = this.timeCycles;
+    if (timeCycles) {
+      for (const cycle of timeCycles) {
+        const cron = elementApi.resolveExpression(cycle);
+        if (!cron) continue;
+        const expireAtDt = cronParser.parseExpression(cron).next().toDate();
+        if (!expireAt || expireAtDt < expireAt) expireAt = expireAtDt;
+      }
+    }
+
+    return {
+      resultVariable: this.resultVariable,
+      ...(scheduledStart && activity.parent.type === 'bpmn:Process' ? {scheduledStart} : undefined),
+      ...(user?.length && {candidateUsers: user}),
+      ...(groups?.length && {candidateGroups: groups}),
+      ...(!elementApi.content.description && description && {description: elementApi.resolveExpression(description)}),
+      ...(expireAt && {expireAt}),
+      ...(assigneeValue && {assignee: assigneeValue}),
+    };
+  }
+}
+
+class FormatProcess {
+  constructor(bp) {
+    this.process = bp;
+  }
+  resolve(elementApi) {
+    let user, groups, description;
+    const bp = this.process;
+    const {
+      documentation,
+      candidateStarterUsers,
+      candidateStarterGroups,
+    } = bp.behaviour;
+
+
+    if (candidateStarterUsers) user = resolveAndSplit(elementApi, candidateStarterUsers);
+    if (candidateStarterGroups) groups = resolveAndSplit(elementApi, candidateStarterGroups);
+    if (documentation) description = documentation[0]?.text;
+
+    return {
+      resultVariable: this.resultVariable,
+      ...(user?.length && {candidateStarterUsers: user}),
+      ...(groups?.length && {candidateStarterGroups: groups}),
+      ...(!elementApi.content.description && description && {description: elementApi.resolveExpression(description)}),
+    };
+  }
+}
+
+function resolveAndSplit(elementApi, str) {
+  if (Array.isArray(str)) return str.filter(Boolean);
+  if (typeof str !== 'string') return;
+
+  const resolved = elementApi.resolveExpression(str);
+  if (Array.isArray(resolved)) return resolved.filter(Boolean);
+  if (typeof resolved !== 'string') return;
+
+  return resolved
+    .split(',')
+    .map((g) => g.trim && g.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+function extendFn(behaviour, context) {
+  if (behaviour.$type === 'bpmn:StartEvent' && behaviour.eventDefinitions) {
+    const timer = behaviour.eventDefinitions.find(({type, behaviour: edBehaviour}) => edBehaviour && type === 'bpmn:TimerEventDefinition');
+    if (timer && timer.behaviour.timeCycle) Object.assign(behaviour, {scheduledStart: timer.behaviour.timeCycle});
+  }
+
+  if (!Array.isArray(behaviour.extensionElements?.values)) return;
+
+  const inputOutput = behaviour.extensionElements.values.find((el) => el.$type === 'camunda:InputOutput');
+  const connector = behaviour.extensionElements.values.find((el) => el.$type === 'camunda:Connector');
+
+  if (inputOutput) registerIOScripts(behaviour.id, context, inputOutput.$type, inputOutput);
+  if (connector) registerIOScripts(behaviour.id, context, connector.$type, connector.inputOutput);
+}
+
+function registerIOScripts(parentId, context, type, ioBehaviour) {
+  if (!ioBehaviour) return;
+
+  const {inputParameters = [], outputParameters = []} = ioBehaviour;
+  for (const {$type, name, definition} of inputParameters.concat(outputParameters)) {
+    if (!definition) continue;
+    if (definition.$type !== 'camunda:Script') continue;
+
+    const filename = `${parentId}/${type}/${$type}/${name}`;
+
+    context.addScript(filename, {
+      id: filename,
+      scriptFormat: definition.scriptFormat,
+      ...(definition.value ? {body: definition.value}: undefined),
+      ...(definition.resource ? {resource: definition.resource}: undefined),
+    });
+  }
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@onify/flow-extensions",
+  "version": "0.0.1",
+  "description": "Onify Flow extensions",
+  "module": "index.js",
+  "main": "dist/index.js",
+  "sideEffects": false,
+  "directories": {
+    "test": "test"
+  },
+  "scripts": {
+    "test": "mocha",
+    "posttest": "npm run dist && eslint . --cache",
+    "prepare": "npm run dist",
+    "predist": "node -e \"fs.rmdirSync('./dist/src', {recursive: true});\"",
+    "dist": "babel index.js -d dist && babel src -d dist/src && babel test/helpers/FlowScripts.js -d dist/src",
+    "test:lcov": "c8 mocha -R dot && c8 report --reporter lcov && npm run posttest",
+    "cov:html": "c8 mocha -R dot && c8 report --reporter html"
+  },
+  "keywords": [
+    "onify",
+    "flow",
+    "bpmn",
+    "bpmn-engine",
+    "extensions"
+  ],
+  "author": {
+    "name": "Onify",
+    "url": "https://github.com/onify"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@aircall/expression-parser": "^1.0.4",
+    "@babel/cli": "^7.17.6",
+    "@babel/core": "^7.17.5",
+    "@babel/preset-env": "^7.16.11",
+    "@babel/register": "^7.16.9",
+    "bpmn-elements": "^7.0.0",
+    "bpmn-engine": "^13.0.0",
+    "bpmn-moddle": "^7.1.2",
+    "c8": "^7.11.0",
+    "camunda-bpmn-moddle": "^6.1.2",
+    "chai": "^4.3.6",
+    "chronokinesis": "^3.1.2",
+    "debug": "^4.3.3",
+    "eslint": "^7.32.0",
+    "mocha": "^9.2.1",
+    "mocha-cakes-2": "^3.3.0",
+    "moddle-context-serializer": "^2.0.0",
+    "nock": "^13.2.4"
+  },
+  "dependencies": {
+    "cron-parser": "^4.2.1"
+  },
+  "files": [
+    "src",
+    "index.js",
+    "dist/src",
+    "dist/index.js"
+  ],
+  "c8": {
+    "exclude": [
+      "dist",
+      "test",
+      ".mocharc.js",
+      "babel.config.js"
+    ]
+  }
+}

package/src/Connector.js

@@ -0,0 +1,48 @@
+class NotImplemented extends Error {
+  constructor(serviceId) {
+    super(`${serviceId} service function not found`);
+    this.code = 'EFLOW_NOT_IMPLEMENTED';
+    this.output = {statusCode: 501};
+  }
+}
+
+export default function Connector(connectorId, io, activity, executionMessage) {
+  if (!(this instanceof Connector)) return new Connector(connectorId, io, activity, executionMessage);
+  this.connectorId = connectorId;
+  this.io = io;
+  this.activity = activity;
+  this.executionMessage = executionMessage;
+}
+
+Connector.prototype.execute = async function execute(...args) {
+  const callback = args.pop();
+  args.push(formatCallback);
+
+  const activity = this.activity;
+  const io = this.io;
+  const environment = activity.environment;
+  const connectorId = this.connectorId;
+  const executionMessage = this.executionMessage;
+
+  const serviceFunction = environment.services[connectorId];
+  if (!serviceFunction) return callback(new NotImplemented(connectorId));
+
+  try {
+    const input = io && await io.getInput(activity, executionMessage);
+    await serviceFunction.call(activity, input, ...args);
+  } catch (err) {
+    return callback(err);
+  }
+
+  async function formatCallback(serviceErr, result) {
+    if (serviceErr) return callback(serviceErr);
+    if (!io?.output.length) return callback(null, result);
+
+    try {
+      const formattedResult = await io.getOutput(activity, {...executionMessage, ...result});
+      return callback(null, formattedResult);
+    } catch (err) {
+      return callback(err);
+    }
+  }
+};

package/src/IO.js

@@ -0,0 +1,181 @@
+export {
+  InputOutput,
+  IOBase,
+  IOMap,
+  IOList,
+  IOScript,
+};
+
+class InputOutput {
+  constructor(parentId, behaviour, context) {
+    this.parentId = parentId;
+    this.context = context;
+    const {inputParameters, outputParameters} = behaviour;
+    this.input = this._map(parentId, inputParameters, 'input', context);
+    this.output = this._map(parentId, outputParameters, 'output', context);
+  }
+  async getInput(activity, executionMessage) {
+    const input = this.input;
+    const values = await Promise.all(input.map((parm) => parm.getValue(activity, executionMessage)));
+    return values.reduce((result, parm) => Object.assign(result, parm), {});
+  }
+  async getOutput(activity, executionMessage) {
+    const output = this.output;
+    const values = await Promise.all(output.map((parm) => parm.getValue(activity, executionMessage)));
+    return values.reduce((result, parm) => Object.assign(result, parm), {});
+  }
+  _map(parentId, list, ioType, context) {
+    const mapped = [];
+    if (!list) return mapped;
+
+    for (const parm of list) {
+      const definition = parm.definition;
+      const type = definition && definition.$type;
+      switch (type) {
+        case 'camunda:Map': {
+          mapped.push(new IOMap(parm));
+          break;
+        }
+        case 'camunda:List': {
+          mapped.push(new IOList(parm));
+          break;
+        }
+        case 'camunda:Script': {
+          const id = `${parentId}/${ioType}/${type}/${parm.name}`;
+          const {scriptFormat, value, resource} = definition;
+
+          if (!value && !resource) break;
+
+          context.environment.scripts.register({
+            id,
+            type: parm.$type,
+            behaviour: {
+              scriptFormat,
+              ...(value ? {script: value} : undefined),
+              ...(resource ? {resource} : undefined),
+            },
+          });
+
+          mapped.push(new IOScript(parm, id));
+          break;
+        }
+        default: {
+          mapped.push(new IOBase(parm));
+        }
+      }
+    }
+
+    return mapped;
+  }
+}
+
+class IOBase {
+  constructor(parm) {
+    this.name = parm.name;
+    this.type = parm.definition && parm.definition.$type || 'string';
+    this.behaviour = parm;
+  }
+  getValue(activity, executionMessage) {
+    return {
+      [this.name]: activity.environment.resolveExpression(this.behaviour.value, executionMessage),
+    };
+  }
+}
+
+class IOMap extends IOBase {
+  constructor(parm) {
+    super(parm);
+  }
+  getValue(activity, executionMessage) {
+    const name = this.name;
+    const entries = this.behaviour.definition.entries;
+    if (!Array.isArray(entries)) return {[name]: {}};
+
+    const environment = activity.environment;
+
+    const result = {};
+    for (const {key, value} of entries) {
+      if (!key) continue;
+
+      const val = environment.resolveExpression(value, executionMessage);
+      if (key in result) {
+        if (val === undefined) continue;
+        const current = result[key];
+        if (Array.isArray(current)) {
+          current.push(val);
+        } else {
+          const items = result[key] = [];
+          if (current !== undefined) items.push(current);
+          items.push(val);
+        }
+      } else {
+        result[key] = val;
+      }
+    }
+
+    return {[name]: result};
+  }
+}
+
+class IOList extends IOBase {
+  constructor(parm) {
+    super(parm);
+  }
+  getValue(activity, executionMessage) {
+    const name = this.name;
+    const items = this.behaviour.definition?.items;
+
+    const result = [];
+    if (!Array.isArray(items)) return {[name]: result};
+
+    const environment = activity.environment;
+    for (const item of items) {
+      const val = environment.resolveExpression(item.value, executionMessage);
+      if (val !== undefined) result.push(val);
+    }
+
+    return {
+      [name]: result,
+    };
+  }
+}
+
+class IOScript extends IOBase {
+  constructor(parm, scriptId) {
+    super(parm);
+    this.id = scriptId;
+    this.script = true;
+  }
+  getValue(activity, executionMessage) {
+    const definition = this.behaviour.definition;
+    const name = this.name;
+    const environment = activity.environment;
+
+    const {fields, content, properties, ...rest} = executionMessage;
+    const scope = {
+      id: this.scriptId,
+      type: this.type,
+      name,
+      fields,
+      content,
+      properties,
+      environment: activity.environment,
+      logger: activity.logger,
+      resolveExpression,
+      ...rest,
+    };
+
+    const script = environment.scripts.getScript(definition.scriptFormat, {id: this.id});
+
+    return new Promise((resolve, reject) => {
+      return script.execute(scope, (err, result) => {
+        if (err) return reject(err);
+        resolve({[name]: result});
+      });
+    });
+
+    function resolveExpression(expression) {
+      return environment.resolveExpression(expression, scope);
+    }
+  }
+}

package/src/IOForm.js

@@ -0,0 +1,23 @@
+import IOProperties from './IOProperties.js';
+
+export default class IOForm {
+  constructor(activity, behaviour) {
+    this.activity = activity;
+    this.behaviour = behaviour;
+  }
+  resolve(elementApi) {
+    const form = {};
+    for (const field of this.behaviour.fields) {
+      const f = form[field.id] = {
+        ...field,
+        ...(field.label && {defaultValue: elementApi.resolveExpression(field.label)}),
+        ...(field.defaultValue && {defaultValue: elementApi.resolveExpression(field.defaultValue)}),
+      };
+      if (f.properties) {
+        f.properties = new IOProperties(this.activity, f.properties).resolve(elementApi);
+      }
+    }
+
+    return form;
+  }
+}

package/src/IOProperties.js

@@ -0,0 +1,15 @@
+export default class IOProperties {
+  constructor(activity, behaviour) {
+    this.activity = activity;
+    this.behaviour = behaviour;
+  }
+  resolve(elementApi) {
+    const properties = {};
+
+    for (const {id, name, value} of this.behaviour.values) {
+      properties[id || name] = elementApi.resolveExpression(value);
+    }
+
+    return properties;
+  }
+}

package/src/ServiceExpression.js

@@ -0,0 +1,13 @@
+export default function ServiceExpression(activity) {
+  if (!(this instanceof ServiceExpression)) return new ServiceExpression(activity);
+  this.activity = activity;
+  this.type = `${activity.type}:expression`;
+  this.expression = activity.behaviour.expression;
+}
+
+ServiceExpression.prototype.execute = function execute(executionMessage, callback) {
+  const serviceFn = this.activity.environment.resolveExpression(this.expression, executionMessage);
+  serviceFn.call(this.activity, executionMessage, (err, result) => {
+    callback(err, result);
+  });
+};