[FEAT] BpmnElementsRegistry API returns source/target for edges (#2522)

This will facilitate the implementation of "path-related" use cases.

Author: tbouffard

src/component/registry/bpmn-model-registry.ts

@@ -17,7 +17,8 @@
 import type BpmnModel from '../../model/bpmn/internal/BpmnModel';
 import type Shape from '../../model/bpmn/internal/shape/Shape';
 import type { Edge } from '../../model/bpmn/internal/edge/edge';
-import type { BpmnSemantic } from './types';
+import { Flow } from '../../model/bpmn/internal/edge/flows';
+import type { BpmnSemantic, EdgeBpmnSemantic } from './types';
 import { ShapeBpmnMarkerKind, ShapeUtil } from '../../model/bpmn/internal';
 import type { ShapeBpmnSubProcess } from '../../model/bpmn/internal/shape/ShapeBpmnElement';
 import ShapeBpmnElement from '../../model/bpmn/internal/shape/ShapeBpmnElement';
@@ -43,14 +44,19 @@ export class BpmnModelRegistry {
     this.onLoadCallback = callback;
   }
 
-  getBpmnSemantic(bpmnElementId: string): BpmnSemantic | undefined {
+  getBpmnSemantic(bpmnElementId: string): BpmnSemantic | EdgeBpmnSemantic | undefined {
     const element = this.searchableModel.elementById(bpmnElementId);
     if (!element) {
       return undefined;
     }
     const bpmnElement = element.bpmnElement;
     const isShape = bpmnElement instanceof ShapeBpmnElement;
-    return { id: bpmnElementId, name: bpmnElement.name, isShape: isShape, kind: bpmnElement.kind };
+    const semantic: BpmnSemantic = { id: bpmnElementId, name: bpmnElement.name, isShape: isShape, kind: bpmnElement.kind };
+    if (bpmnElement instanceof Flow) {
+      (<EdgeBpmnSemantic>semantic).sourceRefId = bpmnElement.sourceRefId;
+      (<EdgeBpmnSemantic>semantic).targetRefId = bpmnElement.targetRefId;
+    }
+    return semantic;
   }
 }
 

src/component/registry/types.ts

@@ -27,6 +27,14 @@ export interface BpmnSemantic {
   kind: BpmnElementKind;
 }
 
+/**
+ * Extended properties available when {@link BpmnSemantic.isShape} is `false`.
+ */
+export interface EdgeBpmnSemantic extends BpmnSemantic {
+  sourceRefId: string;
+  targetRefId: string;
+}
+
 /**
  * @category Custom Behavior
  */

test/integration/dom.bpmn.elements.test.ts

@@ -49,7 +49,7 @@ describe('Bpmn Elements registry - retrieve BPMN elements', () => {
         expect(bpmnElements).toHaveLength(2);
 
         expectStartEventBpmnElement(bpmnElements[0], { id: 'StartEvent_1', name: 'Start Event 1' });
-        expectSequenceFlowBpmnElement(bpmnElements[1], { id: 'Flow_2' });
+        expectSequenceFlowBpmnElement(bpmnElements[1], { id: 'Flow_2', source: 'Activity_1', target: 'EndEvent_1' });
       });
 
       it('Pass a single non existing id', async () => {
@@ -79,8 +79,8 @@ describe('Bpmn Elements registry - retrieve BPMN elements', () => {
         const bpmnElements = bpmnVisualization.bpmnElementsRegistry.getElementsByKinds(FlowKind.SEQUENCE_FLOW);
         expect(bpmnElements).toHaveLength(2);
 
-        expectSequenceFlowBpmnElement(bpmnElements[0], { id: 'Flow_1', name: 'Sequence Flow 1' });
-        expectSequenceFlowBpmnElement(bpmnElements[1], { id: 'Flow_2' });
+        expectSequenceFlowBpmnElement(bpmnElements[0], { id: 'Flow_1', name: 'Sequence Flow 1', source: 'StartEvent_1', target: 'Activity_1' });
+        expectSequenceFlowBpmnElement(bpmnElements[1], { id: 'Flow_2', source: 'Activity_1', target: 'EndEvent_1' });
       });
 
       it('No elements for this kind', async () => {

test/integration/helpers/semantic-with-svg-utils.ts

@@ -13,8 +13,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import type { BpmnElement } from '../../../src/component/registry';
-import type { ExpectedBaseBpmnElement } from '../../unit/helpers/bpmn-semantic-utils';
+import type { BpmnElement, EdgeBpmnSemantic } from '../../../src/component/registry';
+import type { ExpectedBaseBpmnElement, ExpectedFlowElement } from '../../unit/helpers/bpmn-semantic-utils';
 import { expectEndEvent, expectPool, expectSequenceFlow, expectServiceTask, expectStartEvent, expectTask } from '../../unit/helpers/bpmn-semantic-utils';
 import { expectSvgEvent, expectSvgPool, expectSvgSequenceFlow, expectSvgTask } from './html-utils';
 
@@ -28,8 +28,8 @@ export function expectEndEventBpmnElement(bpmnElement: BpmnElement, expected: Ex
   expectSvgEvent(bpmnElement.htmlElement);
 }
 
-export function expectSequenceFlowBpmnElement(bpmnElement: BpmnElement, expected: ExpectedBaseBpmnElement): void {
-  expectSequenceFlow(bpmnElement.bpmnSemantic, expected);
+export function expectSequenceFlowBpmnElement(bpmnElement: BpmnElement, expected: ExpectedFlowElement): void {
+  expectSequenceFlow(<EdgeBpmnSemantic>bpmnElement.bpmnSemantic, expected);
   expectSvgSequenceFlow(bpmnElement.htmlElement);
 }
 

test/unit/component/registry/bpmn-model-registry.test.ts

@@ -14,9 +14,10 @@
  * limitations under the License.
  */
 
+import type { EdgeBpmnSemantic } from '../../../../src/component/registry';
 import { BpmnModelRegistry } from '../../../../src/component/registry/bpmn-model-registry';
-import { expectLane, expectPool, expectSequenceFlow, expectStartEvent } from '../../helpers/bpmn-semantic-utils';
-import { laneInModel, poolInModel, sequenceFlowInModel, startEventInModel } from '../../helpers/bpmn-model-utils';
+import { expectAssociationFlow, expectLane, expectMessageFlow, expectPool, expectSequenceFlow, expectStartEvent } from '../../helpers/bpmn-semantic-utils';
+import { associationFlowInModel, laneInModel, messageFlowInModel, poolInModel, sequenceFlowInModel, startEventInModel } from '../../helpers/bpmn-model-utils';
 
 const bpmnModelRegistry = new BpmnModelRegistry();
 
@@ -29,13 +30,23 @@ describe('Bpmn Model registry', () => {
     expect(callback).toHaveBeenCalledTimes(1);
   });
 
-  it('search edge', () => {
-    bpmnModelRegistry.load(sequenceFlowInModel('seq flow id', 'seq flow name'));
-    const bpmnSemantic = bpmnModelRegistry.getBpmnSemantic('seq flow id');
-    expectSequenceFlow(bpmnSemantic, { id: 'seq flow id', name: 'seq flow name' });
+  it('search sequence flow', () => {
+    bpmnModelRegistry.load(sequenceFlowInModel('seq_flow_id', 'seq flow name', 'sourceRefId', 'targetRefId'));
+    const bpmnSemantic = <EdgeBpmnSemantic>bpmnModelRegistry.getBpmnSemantic('seq_flow_id');
+    expectSequenceFlow(bpmnSemantic, { id: 'seq_flow_id', name: 'seq flow name', source: 'sourceRefId', target: 'targetRefId' });
+  });
+  it('search message flow', () => {
+    bpmnModelRegistry.load(messageFlowInModel('msg_flow_id', 'msg flow name', 'sourceRefId', 'targetRefId'));
+    const bpmnSemantic = <EdgeBpmnSemantic>bpmnModelRegistry.getBpmnSemantic('msg_flow_id');
+    expectMessageFlow(bpmnSemantic, { id: 'msg_flow_id', name: 'msg flow name', source: 'sourceRefId', target: 'targetRefId' });
+  });
+  it('search association flow', () => {
+    bpmnModelRegistry.load(associationFlowInModel('association_flow_id', 'association flow name', 'sourceRefId', 'targetRefId'));
+    const bpmnSemantic = <EdgeBpmnSemantic>bpmnModelRegistry.getBpmnSemantic('association_flow_id');
+    expectAssociationFlow(bpmnSemantic, { id: 'association_flow_id', name: 'association flow name', source: 'sourceRefId', target: 'targetRefId' });
   });
 
-  it('search flownode', () => {
+  it('search flowNode', () => {
     bpmnModelRegistry.load(startEventInModel('start event id', 'start event name'));
     const bpmnSemantic = bpmnModelRegistry.getBpmnSemantic('start event id');
     expectStartEvent(bpmnSemantic, { id: 'start event id', name: 'start event name' });

test/unit/helpers/bpmn-model-utils.ts

@@ -16,7 +16,7 @@
 
 import type BpmnModel from '../../../src/model/bpmn/internal/BpmnModel';
 import { Edge } from '../../../src/model/bpmn/internal/edge/edge';
-import { MessageFlow, SequenceFlow } from '../../../src/model/bpmn/internal/edge/flows';
+import { AssociationFlow, MessageFlow, SequenceFlow } from '../../../src/model/bpmn/internal/edge/flows';
 import Shape from '../../../src/model/bpmn/internal/shape/Shape';
 import ShapeBpmnElement, {
   ShapeBpmnActivity,
@@ -44,14 +44,28 @@ export const buildEdgeId = (bpmnElementId: string): string => {
 
 const newSequenceFlow = (id: string, name: string, source: string, target: string): Edge => new Edge(buildEdgeId(id), new SequenceFlow(id, name, source, target));
 
-const newMessageFlow = (id: string, name: string, source: string, target: string): Edge => new Edge(buildEdgeId(id), new MessageFlow(id, name, source, target));
-
-export const sequenceFlowInModel = (id: string, name: string): BpmnModel => {
+const flowInModel = (factoryFunction: (id: string, name: string, source: string, target: string) => Edge, id: string, name: string, source: string, target: string): BpmnModel => {
   const bpmnModel = newBpmnModel();
-  bpmnModel.edges.push(newSequenceFlow(id, name, undefined, undefined));
+  bpmnModel.edges.push(factoryFunction(id, name, source, target));
   return bpmnModel;
 };
 
+export const sequenceFlowInModel = (id: string, name: string, source: string, target: string): BpmnModel => {
+  return flowInModel(newSequenceFlow, id, name, source, target);
+};
+
+const newMessageFlow = (id: string, name: string, source: string, target: string): Edge => new Edge(buildEdgeId(id), new MessageFlow(id, name, source, target));
+
+export const messageFlowInModel = (id: string, name: string, source: string, target: string): BpmnModel => {
+  return flowInModel(newMessageFlow, id, name, source, target);
+};
+
+const newAssociationFlow = (id: string, name: string, source: string, target: string): Edge => new Edge(buildEdgeId(id), new AssociationFlow(id, name, source, target));
+
+export const associationFlowInModel = (id: string, name: string, source: string, target: string): BpmnModel => {
+  return flowInModel(newAssociationFlow, id, name, source, target);
+};
+
 export const startEventInModel = (id: string, name: string): BpmnModel => {
   const bpmnModel = newBpmnModel();
   bpmnModel.flowNodes.push(newStartEvent('parentId', id, name));

test/unit/helpers/bpmn-semantic-utils.ts

@@ -14,20 +14,41 @@
  * limitations under the License.
  */
 
-import type { BpmnSemantic } from '../../../src/component/registry';
+import type { BpmnSemantic, EdgeBpmnSemantic } from '../../../src/component/registry';
 import { FlowKind, ShapeBpmnElementKind } from '../../../src/model/bpmn/internal';
 
 export interface ExpectedBaseBpmnElement {
   id: string;
   name?: string;
 }
 
-export function expectSequenceFlow(bpmnSemantic: BpmnSemantic, expected: ExpectedBaseBpmnElement): void {
+export interface ExpectedFlowElement extends ExpectedBaseBpmnElement {
+  source: string;
+  target: string;
+}
+
+const expectFlow = (bpmnSemantic: EdgeBpmnSemantic, expected: ExpectedFlowElement): void => {
   expect(bpmnSemantic.id).toEqual(expected.id);
   expect(bpmnSemantic.name).toEqual(expected.name);
   expect(bpmnSemantic.isShape).toBeFalsy();
+  expect(bpmnSemantic.sourceRefId).toEqual(expected.source);
+  expect(bpmnSemantic.targetRefId).toEqual(expected.target);
+};
+
+export const expectSequenceFlow = (bpmnSemantic: EdgeBpmnSemantic, expected: ExpectedFlowElement): void => {
   expect(bpmnSemantic.kind).toEqual(FlowKind.SEQUENCE_FLOW);
-}
+  expectFlow(bpmnSemantic, expected);
+};
+
+export const expectMessageFlow = (bpmnSemantic: EdgeBpmnSemantic, expected: ExpectedFlowElement): void => {
+  expect(bpmnSemantic.kind).toEqual(FlowKind.MESSAGE_FLOW);
+  expectFlow(bpmnSemantic, expected);
+};
+
+export const expectAssociationFlow = (bpmnSemantic: EdgeBpmnSemantic, expected: ExpectedFlowElement): void => {
+  expect(bpmnSemantic.kind).toEqual(FlowKind.ASSOCIATION_FLOW);
+  expectFlow(bpmnSemantic, expected);
+};
 
 function expectShape(bpmnSemantic: BpmnSemantic, expected: ExpectedBaseBpmnElement): void {
   expect(bpmnSemantic.id).toEqual(expected.id);