feat: add completion configuration support for ad-hoc subprocesses

Related to camunda/camunda-modeler#4850

Author: maff

src/contextProvider/zeebe/TooltipProvider.js

@@ -349,6 +349,18 @@ const TooltipProvider = {
       </div>
     );
   },
+  'group-adHocCompletion': (element) => {
+    const translate = useService('translate');
+
+    return (
+      <div>
+        {translate('Define the completion behavior of an ad-hoc subprocess. If no completion condition is set, it will be completed after all active elements have been completed. ')}
+        <a href="https://docs.camunda.io/docs/components/modeler/bpmn/ad-hoc" target="_blank" rel="noopener noreferrer" title={ translate('Ad-hoc subprocess documentation') }>
+          { translate('Learn more.') }
+        </a>
+      </div>
+    );
+  },
   'group-activeElements': (element) => {
     const translate = useService('translate');
 

src/provider/bpmn/BpmnPropertiesProvider.js

@@ -1,6 +1,7 @@
 import { Group } from '@bpmn-io/properties-panel';
 
 import {
+  AdHocCompletionProps,
   CompensationProps,
   DocumentationProps,
   ErrorProps,
@@ -195,6 +196,24 @@ function MultiInstanceGroup(element, injector) {
   return null;
 }
 
+function AdHocCompletionGroup(element, injector) {
+  const translate = injector.get('translate');
+  const group = {
+    label: translate('Completion'),
+    id: 'adHocCompletion',
+    component: Group,
+    entries: [
+      ...AdHocCompletionProps({ element })
+    ]
+  };
+
+  if (group.entries.length) {
+    return group;
+  }
+
+  return null;
+}
+
 function getGroups(element, injector) {
 
   const groups = [
@@ -205,6 +224,7 @@ function getGroups(element, injector) {
     LinkGroup(element, injector),
     MessageGroup(element, injector),
     MultiInstanceGroup(element, injector),
+    AdHocCompletionGroup(element, injector),
     SignalGroup(element, injector),
     EscalationGroup(element, injector),
     TimerGroup(element, injector)

src/provider/bpmn/properties/AdHocCompletionProps.js

@@ -0,0 +1,156 @@
+import { is, getBusinessObject } from 'bpmn-js/lib/util/ModelUtil';
+
+import {
+  CheckboxEntry,
+  isTextFieldEntryEdited,
+  TextFieldEntry,
+} from '@bpmn-io/properties-panel';
+
+import { createElement } from '../../../utils/ElementUtil';
+
+import { useService } from '../../../hooks';
+
+/**
+ * @typedef { import('@bpmn-io/properties-panel').EntryDefinition } Entry
+ */
+
+/**
+ * @returns {Array<Entry>} entries
+ */
+export function AdHocCompletionProps(props) {
+  const { element } = props;
+
+  if (!is(element, 'bpmn:AdHocSubProcess')) {
+    return [];
+  }
+
+  return [
+    {
+      id: 'completionCondition',
+      component: CompletionCondition,
+      isEdited: isTextFieldEntryEdited,
+    },
+    {
+      id: 'cancelRemainingInstances',
+      component: CancelRemainingInstances,
+      isEdited: (node) => node && !node.checked // the default value is true
+    },
+  ];
+}
+
+function CompletionCondition(props) {
+  const { element } = props;
+
+  const bpmnFactory = useService('bpmnFactory');
+  const debounce = useService('debounceInput');
+  const commandStack = useService('commandStack');
+  const translate = useService('translate');
+
+  const getValue = () => {
+    const expression = getBusinessObject(element).get('completionCondition');
+    return expression && expression.get('body');
+  };
+
+  const setValue = (value) => {
+    return commandStack.execute(
+      'element.updateModdleProperties',
+      updateFormalExpression(element, 'completionCondition', value, bpmnFactory)
+    );
+  };
+
+  return TextFieldEntry({
+    element,
+    id: 'completionCondition',
+    label: translate('Completion condition'),
+    getValue,
+    setValue,
+    debounce
+  });
+}
+
+function CancelRemainingInstances(props) {
+  const { element } = props;
+
+  const commandStack = useService('commandStack');
+  const translate = useService('translate');
+
+  const businessObject = getBusinessObject(element);
+
+  const getValue = () => {
+    return businessObject.get('cancelRemainingInstances');
+  };
+
+  const setValue = (value) => {
+    commandStack.execute('element.updateModdleProperties', {
+      element,
+      moddleElement: businessObject,
+      properties: {
+        cancelRemainingInstances: value,
+      },
+    });
+  };
+
+  return CheckboxEntry({
+    element,
+    id: 'cancelRemainingInstances',
+    label: translate('Cancel remaining instances'),
+    getValue,
+    setValue,
+  });
+}
+
+// helper ////////////////////////////
+
+// formal expression /////////////////
+
+/**
+ * updateFormalExpression - updates a specific formal expression
+ *
+ * @param {djs.model.Base} element
+ * @param {string} propertyName
+ * @param {string} newValue
+ * @param {BpmnFactory} bpmnFactory
+ */
+function updateFormalExpression(element, propertyName, newValue, bpmnFactory) {
+  const businessObject = getBusinessObject(element);
+  const expressionProps = {};
+
+  if (!newValue) {
+
+    // remove formal expression
+    expressionProps[propertyName] = undefined;
+
+    return {
+      element,
+      moddleElement: businessObject,
+      properties: expressionProps,
+    };
+  }
+
+  const existingExpression = businessObject.get(propertyName);
+  if (!existingExpression) {
+
+    // add formal expression
+    expressionProps[propertyName] = createElement(
+      'bpmn:FormalExpression',
+      { body: newValue },
+      businessObject,
+      bpmnFactory
+    );
+
+    return {
+      element,
+      moddleElement: businessObject,
+      properties: expressionProps,
+    };
+  }
+
+  // edit existing formal expression
+  return {
+    element,
+    moddleElement: existingExpression,
+    properties: {
+      body: newValue,
+    },
+  };
+}

src/provider/bpmn/properties/index.js

@@ -1,3 +1,4 @@
+export { AdHocCompletionProps } from './AdHocCompletionProps';
 export { CompensationProps } from './CompensationProps';
 export { DocumentationProps } from './DocumentationProps';
 export { ErrorProps } from './ErrorProps';

src/provider/zeebe/ZeebePropertiesProvider.js

@@ -4,6 +4,7 @@ import { findIndex } from 'min-dash';
 
 import {
   ActiveElementsProps,
+  AdHocCompletionProps,
   AssignmentDefinitionProps,
   BusinessRuleImplementationProps,
   CalledDecisionProps,
@@ -86,6 +87,7 @@ export default class ZeebePropertiesProvider {
       updateSignalGroup(groups, element);
       updateTimerGroup(groups, element, this._injector);
       updateMultiInstanceGroup(groups, element);
+      updateAdHocCompletionGroup(groups, element);
 
       // (3) remove message group when not applicable
       groups = removeMessageGroup(groups, element);
@@ -467,6 +469,25 @@ function updateMultiInstanceGroup(groups, element) {
   ];
 }
 
+// overwrite bpmn generic adHoc completion condition with zeebe-specific one
+function updateAdHocCompletionGroup(groups, element) {
+  const adHocCompletionGroup = findGroup(groups, 'adHocCompletion');
+  if (!adHocCompletionGroup) {
+    return;
+  }
+
+  adHocCompletionGroup.entries = replaceEntriesPreservingOrder(
+    adHocCompletionGroup.entries,
+    AdHocCompletionProps({ element })
+  );
+
+  // reorder groups to move active elements before adHoc completion
+  const activeElementsGroup = findGroup(groups, 'activeElements');
+  if (activeElementsGroup) {
+    reorderGroupsIfNecessary(groups, activeElementsGroup, adHocCompletionGroup);
+  }
+}
+
 // remove message group from Message End Event & Message Throw Event
 function removeMessageGroup(groups, element) {
   const messageGroup = findGroup(groups, 'message');
@@ -485,9 +506,28 @@ function findGroup(groups, id) {
   return groups.find(g => g.id === id);
 }
 
+/**
+ * Put groups into the defined order if necessary.
+ *
+ * @param {Group[]} groups
+ * @param {Group} firstGroup
+ * @param {Group} secondGroup
+ */
+function reorderGroupsIfNecessary(groups, firstGroup, secondGroup) {
+  const firstGroupIndex = groups.indexOf(firstGroup);
+  const secondGroupIndex = groups.indexOf(secondGroup);
+
+  if (firstGroupIndex === -1 || secondGroupIndex === -1 || firstGroupIndex <= secondGroupIndex) {
+    return;
+  }
+
+  groups[firstGroupIndex] = secondGroup;
+  groups[secondGroupIndex] = firstGroup;
+}
+
 /**
  * Replace entries with the same ID.
- *s
+ *
  * @param {Entry[]} oldEntries
  * @param {Entry[]} newEntries
  *
@@ -503,4 +543,45 @@ function replaceEntries(oldEntries, newEntries) {
     ...filteredEntries,
     ...newEntries
   ];
+}
+
+/**
+ * Replace entries with the same ID, preserving original order and adding new entries at the end.
+ *
+ * @param {Entry[]} oldEntries
+ * @param {Entry[]} newEntries
+ *
+ * @returns {Entry[]} combined entries
+ */
+function replaceEntriesPreservingOrder(oldEntries, newEntries) {
+  const indexedNewEntries = indexEntriesById(newEntries);
+  const indexedOldEntries = indexEntriesById(oldEntries);
+
+  const result = [];
+
+  // iterate original entries and replace with new ones if ID matches
+  oldEntries.forEach((oldEntry) => {
+    const newEntryIndex = indexedNewEntries[oldEntry.id];
+    if (newEntryIndex !== undefined) {
+      result.push(newEntries[newEntryIndex]);
+    } else {
+      result.push(oldEntry);
+    }
+  });
+
+  // append remaining new entries
+  newEntries.forEach((newEntry) => {
+    if (indexedOldEntries[newEntry.id] === undefined) {
+      result.push(newEntry);
+    }
+  });
+
+  return result;
+}
+
+function indexEntriesById(entries) {
+  return entries.reduce((index, entry, idx) => {
+    index[entry.id] = idx;
+    return index;
+  }, {});
 }