feat: render annotation + association defined in "collaboration” (#3200)

The change involve introducing utility functions into tests to simplify the writing of code for setup and expectation in JSON parsing tests. Also fix some collaborators' documentation about the BPMN support.
process-analytics · Oct 23, 2024 · df835be · df835be
1 parent d82501b
commit df835be
Show file tree

Hide file tree

Showing 10 changed files with 427 additions and 90 deletions.
diff --git a/docs/contributors/bpmn-support-how-to.md b/docs/contributors/bpmn-support-how-to.md
@@ -231,7 +231,7 @@ Here are some tips to generate the SVG to be included in the documentation.
 
 ```SVG
   <svg viewBox="0 0 158.485 158.485" width="96" height="96" xmlns="http://www.w3.org/2000/svg">
-      <!-- the retreieved SVG code -->
+      <!-- the retrieved SVG code -->
   </svg>
 ```
 - Open the file in a SVG Editor (Inkscape for instance). 
@@ -244,4 +244,4 @@ Here are some tips to generate the SVG to be included in the documentation.
 ![SVG icon fits the viewBox](images/inkscape-result2.png)
 
 - Save
-- Eventually clean the SVG with tools like SVGGO: https://jakearchibald.github.io/svgomg/
+- Eventually clean the SVG with tools like `SVGGO`: https://jakearchibald.github.io/svgomg/
diff --git a/src/component/parser/json/converter/CollaborationConverter.ts b/src/component/parser/json/converter/CollaborationConverter.ts
@@ -15,7 +15,7 @@ limitations under the License.
 */
 
 import type { ConvertedElements } from './utils';
-import type { TGroup } from '../../../../model/bpmn/json/baseElement/artifact';
+import type { TGroup, TTextAnnotation } from '../../../../model/bpmn/json/baseElement/artifact';
 import type { TMessageFlow } from '../../../../model/bpmn/json/baseElement/baseElement';
 import type { TParticipant } from '../../../../model/bpmn/json/baseElement/participant';
 import type { TCollaboration } from '../../../../model/bpmn/json/baseElement/rootElement/collaboration';
@@ -26,7 +26,7 @@ import { MessageFlow } from '../../../../model/bpmn/internal/edge/flows';
 import ShapeBpmnElement from '../../../../model/bpmn/internal/shape/ShapeBpmnElement';
 import { ensureIsArray } from '../../../helpers/array-utils';
 
-import { buildShapeBpmnGroup } from './utils';
+import { buildShapeBpmnGroup, convertAndRegisterAssociationFlows } from './utils';
 
 /**
  * @internal
@@ -44,7 +44,9 @@ export default class CollaborationConverter {
   private parseCollaboration(collaboration: TCollaboration): void {
     this.buildParticipant(collaboration.participant);
     this.buildMessageFlows(collaboration.messageFlow);
+    convertAndRegisterAssociationFlows(this.convertedElements, collaboration.association);
     this.buildGroups(collaboration.group);
+    this.buildTextAnnotation(collaboration.textAnnotation);
   }
 
   private buildParticipant(bpmnElements: TParticipant[] | TParticipant): void {
@@ -63,4 +65,10 @@ export default class CollaborationConverter {
       shapeBpmnElement && this.convertedElements.registerFlowNode(shapeBpmnElement);
     }
   }
+
+  private buildTextAnnotation(bpmnElements: TTextAnnotation[] | TTextAnnotation): void {
+    for (const textAnnotation of ensureIsArray(bpmnElements)) {
+      this.convertedElements.registerFlowNode(new ShapeBpmnElement(textAnnotation.id, textAnnotation.text as string, ShapeBpmnElementKind.TEXT_ANNOTATION));
+    }
+  }
 }
diff --git a/src/component/parser/json/converter/ProcessConverter.ts b/src/component/parser/json/converter/ProcessConverter.ts
@@ -15,8 +15,8 @@ limitations under the License.
 */
 
 import type { ConvertedElements, RegisteredEventDefinition } from './utils';
-import type { AssociationDirectionKind, BpmnEventKind } from '../../../../model/bpmn/internal';
-import type { TAssociation, TGroup, TTextAnnotation } from '../../../../model/bpmn/json/baseElement/artifact';
+import type { BpmnEventKind } from '../../../../model/bpmn/internal';
+import type { TGroup, TTextAnnotation } from '../../../../model/bpmn/json/baseElement/artifact';
 import type { TLane, TLaneSet } from '../../../../model/bpmn/json/baseElement/baseElement';
 import type { TFlowNode, TSequenceFlow } from '../../../../model/bpmn/json/baseElement/flowElement';
 import type { TActivity, TCallActivity, TSubProcess } from '../../../../model/bpmn/json/baseElement/flowNode/activity/activity';
@@ -36,7 +36,7 @@ import {
   ShapeBpmnSubProcessKind,
   ShapeUtil,
 } from '../../../../model/bpmn/internal';
-import { AssociationFlow, SequenceFlow } from '../../../../model/bpmn/internal/edge/flows';
+import { SequenceFlow } from '../../../../model/bpmn/internal/edge/flows';
 import ShapeBpmnElement, {
   ShapeBpmnIntermediateThrowEvent,
   ShapeBpmnIntermediateCatchEvent,
@@ -52,8 +52,9 @@ import { eventDefinitionKinds } from '../../../../model/bpmn/internal/shape/util
 import { ensureIsArray } from '../../../helpers/array-utils';
 import { BoundaryEventNotAttachedToActivityWarning, LaneUnknownFlowNodeReferenceWarning } from '../warnings';
 
-import { buildShapeBpmnGroup } from './utils';
+import { convertAndRegisterAssociationFlows, buildShapeBpmnGroup } from './utils';
 
+// semantically speaking, TTextAnnotation is not a FlowNode, but it is an Artifact
 type FlowNode = TFlowNode | TActivity | TReceiveTask | TEventBasedGateway | TTextAnnotation;
 
 type BpmnSemanticType = keyof TProcess;
@@ -182,7 +183,7 @@ export default class ProcessConverter {
 
     // flows
     this.buildSequenceFlows(process.sequenceFlow);
-    this.buildAssociationFlows(process.association);
+    convertAndRegisterAssociationFlows(this.convertedElements, process.association);
   }
 
   private buildFlowNodeBpmnElements(
@@ -395,13 +396,6 @@ export default class ProcessConverter {
     }
   }
 
-  private buildAssociationFlows(bpmnElements: TAssociation[] | TAssociation): void {
-    for (const association of ensureIsArray(bpmnElements)) {
-      const direction = association.associationDirection as unknown as AssociationDirectionKind;
-      this.convertedElements.registerAssociationFlow(new AssociationFlow(association.id, undefined, association.sourceRef, association.targetRef, direction));
-    }
-  }
-
   private getSequenceFlowKind(sequenceFlow: TSequenceFlow): SequenceFlowKind {
     if (this.defaultSequenceFlowIds.includes(sequenceFlow.id)) {
       return SequenceFlowKind.DEFAULT;

diff --git a/src/component/parser/json/converter/utils.ts b/src/component/parser/json/converter/utils.ts
@@ -14,14 +14,16 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-import type { GlobalTaskKind, ShapeBpmnEventDefinitionKind } from '../../../../model/bpmn/internal';
-import type { Flow, AssociationFlow, MessageFlow, SequenceFlow } from '../../../../model/bpmn/internal/edge/flows';
-import type { TGroup } from '../../../../model/bpmn/json/baseElement/artifact';
+import type { AssociationDirectionKind, GlobalTaskKind, ShapeBpmnEventDefinitionKind } from '../../../../model/bpmn/internal';
+import type { Flow, MessageFlow, SequenceFlow } from '../../../../model/bpmn/internal/edge/flows';
+import type { TAssociation, TGroup } from '../../../../model/bpmn/json/baseElement/artifact';
 import type { TEventDefinition, TLinkEventDefinition } from '../../../../model/bpmn/json/baseElement/rootElement/eventDefinition';
 import type { ParsingMessageCollector } from '../../parsing-messages';
 
 import { ShapeBpmnElementKind } from '../../../../model/bpmn/internal';
+import { AssociationFlow } from '../../../../model/bpmn/internal/edge/flows';
 import ShapeBpmnElement from '../../../../model/bpmn/internal/shape/ShapeBpmnElement';
+import { ensureIsArray } from '../../../helpers/array-utils';
 import { GroupUnknownCategoryValueWarning } from '../warnings';
 
 export type RegisteredEventDefinition = (Pick<TEventDefinition, 'id'> & Pick<TLinkEventDefinition, 'source' | 'target'>) & {
@@ -133,3 +135,10 @@ export const buildShapeBpmnGroup = (
 interface CategoryValueData {
   value?: string;
 }
+
+export const convertAndRegisterAssociationFlows = (convertedElements: ConvertedElements, bpmnElements: TAssociation[] | TAssociation): void => {
+  for (const association of ensureIsArray(bpmnElements)) {
+    const direction = association.associationDirection as unknown as AssociationDirectionKind;
+    convertedElements.registerAssociationFlow(new AssociationFlow(association.id, undefined, association.sourceRef, association.targetRef, direction));
+  }
+};
diff --git a/...s__/bpmn-rendering/associations.and.annotations.06.defined.in.collaboration.png b/...s__/bpmn-rendering/associations.and.annotations.06.defined.in.collaboration.png
diff --git a/test/fixtures/bpmn/model-complete-semantic.bpmn b/test/fixtures/bpmn/model-complete-semantic.bpmn
@@ -19,6 +19,10 @@
 
     <!-- Groups -->
     <semantic:group id="Group_0_in_collaboration" categoryValueRef="CategoryValue_0" />
+
+    <!-- Text Annotations and Associations -->
+    <semantic:textAnnotation id="text_annotation_in_collaboration_1" text="Text Annotation in collaboration" />
+    <semantic:association id="association_in_collaboration_1" sourceRef="participant_3_id" targetRef="text_annotation_in_collaboration_1" />
   </semantic:collaboration>
 
   <!-- Event Definition -->
@@ -1933,6 +1937,9 @@
         <dc:Bounds x="1030" y="1210" width="102" height="23" />
         <bpmndi:BPMNLabel/>
       </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="shape_text_annotation_in_collaboration_1" bpmnElement="text_annotation_in_collaboration_1">
+        <dc:Bounds x="2300" y="300" width="200" height="25" />
+      </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="shape_Group_0_in_collaboration" bpmnElement="Group_0_in_collaboration">
         <dc:Bounds x="3190" y="80" width="600" height="400" />
         <bpmndi:BPMNLabel/>
@@ -2001,6 +2008,8 @@
         <di:waypoint x="1069" y="1106" />
         <di:waypoint x="1080" y="1210" />
       </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="edge_association_in_collaboration_1" bpmnElement="association_in_collaboration_1">
+      </bpmndi:BPMNEdge>
 
       <!-- 2nd process -->
       <bpmndi:BPMNShape id="shape_participant_2_id" bpmnElement="participant_2_id" isHorizontal="true">

diff --git a/test/integration/mxGraph.model.bpmn.elements.test.ts b/test/integration/mxGraph.model.bpmn.elements.test.ts
@@ -1437,6 +1437,13 @@ describe('mxGraph model - BPMN elements', () => {
           align: 'left',
         });
       });
+      it('text annotations in collaboration', () => {
+        expect('text_annotation_in_collaboration_1').toBeTextAnnotation({
+          label: 'Text Annotation in collaboration',
+          parentId: getDefaultParentId(),
+          align: 'left',
+        });
+      });
 
       it('groups', () => {
         expect('Group_0_in_collaboration').toBeGroup({
@@ -1515,6 +1522,10 @@ describe('mxGraph model - BPMN elements', () => {
       it('associations', () => {
         expect('association_id').toBeAssociationFlow({ parentId: 'participant_1_id', verticalAlign: 'bottom' });
       });
+
+      it('associations in collaboration', () => {
+        expect('association_in_collaboration_1').toBeAssociationFlow({ parentId: getDefaultParentId(), verticalAlign: 'bottom' });
+      });
     });
 
     it('Diagram with a not displayed pool (without shape) with elements', () => {