Merge pull request #77 from datasharingframework/issue/71-maintain-dsf-linter-improve-log-messages-and-review-bpmn-types

Issue/71 maintain dsf linter improve log messages and review bpmn types

Author: khalilmalla95

linter-core/pom.xml

@@ -101,6 +101,15 @@
             <version>2.22.0</version>
         </dependency>
 
+        <!-- Jakarta JAXB API 3.x+ (jakarta.xml.bind.*); required when Thymeleaf/Jackson
+        auto-registers jackson-module-jakarta-xmlbind (Java 11+ has no JAXB in the JDK).
+        Camunda's transitive jakarta.xml.bind-api 2.3.3 only exposes javax.xml.bind.*. -->
+        <dependency>
+            <groupId>jakarta.xml.bind</groupId>
+            <artifactId>jakarta.xml.bind-api</artifactId>
+            <version>4.0.2</version>
+        </dependency>
+
         <dependency>
             <groupId>org.jetbrains</groupId>
             <artifactId>annotations</artifactId>

linter-core/src/main/java/dev/dsf/linter/bpmn/BpmnEventLinter.java

@@ -1,6 +1,7 @@
 package dev.dsf.linter.bpmn;
 
 import dev.dsf.linter.output.item.BpmnElementLintItem;
+import dev.dsf.linter.util.bpmn.BpmnModelUtils;
 import dev.dsf.linter.util.bpmn.linters.*;
 import org.camunda.bpm.model.bpmn.instance.*;
 
@@ -193,8 +194,7 @@ public void lintStartEvent(
             File bpmnFile,
             String processId) {
 
-        if (!startEvent.getEventDefinitions().isEmpty()
-                && startEvent.getEventDefinitions().iterator().next() instanceof MessageEventDefinition) {
+        if (BpmnModelUtils.isMessageStartEvent(startEvent)) {
             BpmnStartEventLinter.lintMessageStartEvent(startEvent, issues, bpmnFile, processId, projectRoot);
         } else {
             BpmnStartEventLinter.lintGenericStartEvent(startEvent, issues, bpmnFile, processId, projectRoot);

linter-core/src/main/java/dev/dsf/linter/bpmn/BpmnFieldInjectionLinter.java

@@ -3,6 +3,8 @@
 import dev.dsf.linter.output.LinterSeverity;
 import dev.dsf.linter.output.LintingType;
 import dev.dsf.linter.output.item.*;
+import dev.dsf.linter.util.api.ApiVersion;
+import dev.dsf.linter.util.api.ApiVersionHolder;
 import dev.dsf.linter.util.resource.FhirResourceExtractor;
 import dev.dsf.linter.util.resource.FhirResourceLocator;
 import dev.dsf.linter.util.resource.FhirResourceParser;
@@ -47,11 +49,11 @@
  *
  * <h3>Field Value Type Validation</h3>
  * <ul>
- *   <li><strong>String Literal Requirement</strong>: Validates that field values are provided as
+ *   <li><strong>String Literal Requirement (API v1)</strong>: Validates that field values are provided as
  *       string literals rather than expressions, ensuring static configuration that can be validated
  *       at linting time</li>
- *   <li><strong>Expression Detection</strong>: Issues errors when field values are provided as
- *       expressions, which cannot be statically validated</li>
+ *   <li><strong>Expression Detection</strong>: For API v1, issues errors when field values are provided as
+ *       expressions. For API v2, expressions are allowed and further static validation of that field is skipped</li>
  * </ul>
  *
  * <h3>Profile Field Validation</h3>
@@ -312,12 +314,20 @@ private static void lintCamundaFields(ExtensionElements extensionElements,
                         "Field injection '" + fieldName + "' provided as string literal"));
             }
 
-            // expression? -> immediate error + skip further processing of this field
+            // expression: error for API v1; allowed for API v2 (skip static field validation)
             if (fv != null && fv.type == FieldValueType.EXPRESSION) {
-                issues.add(new BpmnElementLintItem(
-                        LinterSeverity.ERROR, LintingType.BPMN_FIELD_INJECTION_NOT_STRING_LITERAL,
-                        elementId, bpmnFile, processId,
-                        "Field injection '" + fieldName + "' is provided as expression, expected string literal")); //todo in api v2 is allowed
+                if (ApiVersionHolder.getVersion() == ApiVersion.V2) {
+                    issues.add(BpmnElementLintItem.success(
+                            elementId,
+                            bpmnFile,
+                            processId,
+                            "Field injection '" + fieldName + "' provided as expression (allowed for API v2)"));
+                } else {
+                    issues.add(new BpmnElementLintItem(
+                            LinterSeverity.ERROR, LintingType.BPMN_FIELD_INJECTION_NOT_STRING_LITERAL,
+                            elementId, bpmnFile, processId,
+                            "Field injection '" + fieldName + "' is provided as expression, expected string literal"));
+                }
                 continue;
             }
 
@@ -350,7 +360,7 @@ private static void lintCamundaFields(ExtensionElements extensionElements,
                     }
                 }
                 case "instantiatesCanonical" -> {
-                    checkInstantiatesCanonicalField(elementId, literal, bpmnFile, processId, issues, projectRoot);
+                    checkInstantiatesCanonicalField(elementId, literal, bpmnFile, processId, issues);
                     instantiatesVal = literal;
                 }
                 default -> issues.add(new BpmnElementLintItem(
@@ -515,15 +525,13 @@ public static void checkProfileField(
      * @param bpmnFile    the BPMN file under lint
      * @param processId   the identifier of the BPMN process containing the element
      * @param issues      the list of {@link BpmnElementLintItem} to which lint issues or success items will be added
-     * @param projectRoot the project root directory containing FHIR resources
      */
     public static void checkInstantiatesCanonicalField(
             String elementId,
             String literalValue,
             File bpmnFile,
             String processId,
-            List<BpmnElementLintItem> issues,
-            File projectRoot) {
+            List<BpmnElementLintItem> issues) {
 
         if (isEmpty(literalValue)) {
             issues.add(new BpmnElementLintItem(LinterSeverity.ERROR,

linter-core/src/main/java/dev/dsf/linter/bpmn/BpmnGatewayAndFlowLinter.java

@@ -177,7 +177,7 @@ public void lintInclusiveGateway(
         if (gateway.getOutgoing() != null && gateway.getOutgoing().size() > 1) {
             if (isEmpty(gateway.getName())) {
                 issues.add(BpmnElementLintItem.of(
-                        LinterSeverity.ERROR,
+                        LinterSeverity.WARN,
                         LintingType.BPMN_INCLUSIVE_GATEWAY_HAS_MULTIPLE_OUTGOING_FLOWS_BUT_NAME_IS_EMPTY,
                         elementId, bpmnFile, processId));
             } else {

linter-core/src/main/java/dev/dsf/linter/bpmn/BpmnModelLinter.java

@@ -46,6 +46,8 @@
  *   <li><strong>Process Count</strong>: Validates that each BPMN file contains exactly one process definition</li>
  *   <li><strong>History Time To Live</strong>: Warns if {@code camunda:historyTimeToLive} is not set</li>
  *   <li><strong>Process Executable</strong>: Validates that the process has {@code isExecutable="true"}</li>
+ *   <li><strong>Message Start Event</strong>: Validates that the process has at least one message start event
+ *       as a direct child (start events in subprocesses are not counted)</li>
  * </ul>
  *
  * <h3>Task Validation</h3>

linter-core/src/main/java/dev/dsf/linter/bpmn/BpmnProcessLinter.java

@@ -3,8 +3,10 @@
 import dev.dsf.linter.output.LinterSeverity;
 import dev.dsf.linter.output.LintingType;
 import dev.dsf.linter.output.item.BpmnElementLintItem;
+import dev.dsf.linter.util.bpmn.BpmnModelUtils;
 import org.camunda.bpm.model.bpmn.BpmnModelInstance;
 import org.camunda.bpm.model.bpmn.instance.Process;
+import org.camunda.bpm.model.bpmn.instance.StartEvent;
 
 import java.io.File;
 import java.util.Collection;
@@ -58,6 +60,12 @@
  *       which is required for the process to be deployable and executable by the process engine.</li>
  * </ul>
  *
+ * <h3>Message Start Event Validation</h3>
+ * <ul>
+ *   <li><strong>Message Start Requirement</strong>: Validates that the process has at least one message
+ *       start event as a direct child of the process element. Start events inside subprocesses are not counted.</li>
+ * </ul>
+ *
  * <h2>Usage Example</h2>
  * <pre>{@code
  * File projectRoot = new File("/path/to/project");
@@ -134,6 +142,7 @@ public record BpmnProcessLinter(File projectRoot) {
      *   <li>Process ID pattern</li>
      *   <li>History time to live attribute</li>
      *   <li>Executable flag</li>
+     *   <li>Message start event on process level (not in subprocesses)</li>
      *   <li>Version tag placeholder ({@code camunda:versionTag="#{version}"})</li>
      * </ul>
      * </p>
@@ -153,6 +162,7 @@ public String lintProcesses(BpmnModelInstance model, File bpmnFile, List<BpmnEle
         for (Process process : processes) {
             validateHistoryTimeToLive(process, bpmnFile, issues);
             validateProcessExecutable(process, bpmnFile, issues);
+            validateMessageStartEvent(process, bpmnFile, issues);
             validateVersionTag(process, bpmnFile, issues);
         }
 
@@ -362,6 +372,42 @@ void validateProcessExecutable(Process process, File bpmnFile, List<BpmnElementL
         }
     }
 
+    /**
+     * Validates that the process has at least one message start event as a direct child.
+     *
+     * <p>
+     * DSF processes are started via incoming messages. Start events inside subprocesses are not counted.
+     * </p>
+     *
+     * @param process  the BPMN process to validate
+     * @param bpmnFile the BPMN file for error reporting
+     * @param issues   the list to add validation issues to
+     */
+    void validateMessageStartEvent(Process process, File bpmnFile, List<BpmnElementLintItem> issues) {
+        String processId = process.getId() != null ? process.getId() : "";
+
+        boolean hasMessageStart = process.getChildElementsByType(StartEvent.class).stream()
+                .anyMatch(BpmnModelUtils::isMessageStartEvent);
+
+        if (!hasMessageStart) {
+            issues.add(BpmnElementLintItem.of(
+                    LinterSeverity.ERROR,
+                    LintingType.BPMN_MESSAGE_START_EVENT_NOT_FOUND,
+                    processId,
+                    bpmnFile,
+                    processId));
+        } else {
+            issues.add(new BpmnElementLintItem(
+                    LinterSeverity.SUCCESS,
+                    LintingType.SUCCESS,
+                    processId,
+                    bpmnFile,
+                    processId,
+                    String.format("Process '%s': has at least one message start event on process level.", processId)
+            ));
+        }
+    }
+
     /**
      * Validates that camunda:versionTag exists and uses the DSF placeholder "#{version}".
      *

linter-core/src/main/java/dev/dsf/linter/bpmn/BpmnTaskLinter.java

@@ -197,7 +197,7 @@ public void lintServiceTask(
 
         // 1. Validate task name
         if (isEmpty(task.getName())) {
-            issues.add(BpmnElementLintItem.of(LinterSeverity.ERROR,
+            issues.add(BpmnElementLintItem.of(LinterSeverity.WARN,
                     LintingType.BPMN_SERVICE_TASK_NAME_EMPTY, elementId, bpmnFile, processId));
         } else {
             issues.add(BpmnElementLintItem.success(elementId, bpmnFile, processId,
@@ -282,9 +282,8 @@ public void lintSendTask(
 
         // 1. Validate task name
         if (isEmpty(sendTask.getName())) {
-            issues.add(new BpmnElementLintItem(LinterSeverity.WARN,
-                    LintingType.BPMN_EVENT_NAME_EMPTY, elementId, bpmnFile, processId,
-                    "'" + elementId + "' has no name"));
+            issues.add(BpmnElementLintItem.of(LinterSeverity.WARN,
+                    LintingType.BPMN_SEND_TASK_NAME_EMPTY, elementId, bpmnFile, processId));
         } else {
             issues.add(BpmnElementLintItem.success(elementId, bpmnFile, processId,
                     "SendTask has a non-empty name: '" + sendTask.getName() + "'"));
@@ -357,7 +356,7 @@ public void lintUserTask(
 
         // 1. Validate task name
         if (isEmpty(userTask.getName())) {
-            issues.add(BpmnElementLintItem.of(LinterSeverity.ERROR,
+            issues.add(BpmnElementLintItem.of(LinterSeverity.WARN,
                     LintingType.BPMN_USER_TASK_NAME_EMPTY, elementId, bpmnFile, processId));
         } else {
             issues.add(BpmnElementLintItem.success(elementId, bpmnFile, processId,
@@ -409,17 +408,16 @@ public void lintReceiveTask(
         String elementId = receiveTask.getId();
 
         if (isEmpty(receiveTask.getName())) {
-            issues.add(new BpmnElementLintItem(LinterSeverity.WARN,
-                    LintingType.BPMN_EVENT_NAME_EMPTY, elementId, bpmnFile, processId,
-                    "'" + elementId + "' has no name."));
+            issues.add(BpmnElementLintItem.of(LinterSeverity.WARN,
+                    LintingType.BPMN_RECEIVE_TASK_NAME_EMPTY, elementId, bpmnFile, processId));
         } else {
             issues.add(BpmnElementLintItem.success(elementId, bpmnFile, processId,
                     "ReceiveTask has a non-empty name: '" + receiveTask.getName() + "'"));
         }
 
         if (receiveTask.getMessage() == null || isEmpty(receiveTask.getMessage().getName())) {
             issues.add(BpmnElementLintItem.of(LinterSeverity.ERROR,
-                    LintingType.BPMN_MESSAGE_START_EVENT_MESSAGE_NAME_EMPTY, elementId, bpmnFile, processId));
+                    LintingType.BPMN_RECEIVE_TASK_MESSAGE_NAME_EMPTY, elementId, bpmnFile, processId));
         } else {
             String msgName = receiveTask.getMessage().getName();
             issues.add(BpmnElementLintItem.success(elementId, bpmnFile, processId,

linter-core/src/main/java/dev/dsf/linter/output/LintingType.java

@@ -34,24 +34,31 @@ public enum LintingType {
     BPMN_MESSAGE_SEND_TASK_IMPLEMENTATION_CLASS_NOT_FOUND("Message send task implementation class not found."),
 
     // ==================== BPMN SEND TASK ====================
+    BPMN_SEND_TASK_NAME_EMPTY("Send task name is empty."),
     BPMN_SEND_TASK_NO_INTERFACE_CLASS_IMPLEMENTING("Send task implementation class does not implement required interface."),
     BPMN_SEND_TASK_IMPLEMENTATION_CLASS_NOT_EXTENDING_ABSTRACT_TASK_MESSAGE_SEND("Send task implementation class does not extend AbstractTaskMessageSend."),
 
+    // ==================== BPMN RECEIVE TASK ====================
+    BPMN_RECEIVE_TASK_NAME_EMPTY("Receive task name is empty."),
+    BPMN_RECEIVE_TASK_MESSAGE_NAME_EMPTY("Receive task message name is empty."),
+
     // ==================== BPMN FLOW ====================
     BPMN_MESSAGE_START_EVENT_NOT_FOUND("Message start event not found."),
+    BPMN_MESSAGE_START_EVENT_NAME_EMPTY("Message start event name is empty."),
     BPMN_MESSAGE_START_EVENT_MESSAGE_NAME_EMPTY("Message start event message name is empty."),
     BPMN_FLOATING_ELEMENT("BPMN element is outside of message start event triggered flow."),
     BPMN_FLOW_ELEMENT("BPMN flow element issue."),
 
     // ==================== BPMN EVENTS ====================
-    BPMN_EVENT_NAME_EMPTY("Event name is empty."),
+    BPMN_MESSAGE_END_EVENT_NAME_EMPTY("Message end event name is empty."),
+    BPMN_MESSAGE_INTERMEDIATE_THROW_EVENT_NAME_EMPTY("Message intermediate throw event name is empty."),
     BPMN_ERROR_BOUNDARY_EVENT_ERROR_CODE_EMPTY("Error boundary event error code is empty."),
     BPMN_ERROR_BOUNDARY_EVENT_ERROR_CODE_VARIABLE_EMPTY("Error boundary event error code variable is empty."),
     BPMN_ERROR_BOUNDARY_EVENT_ERROR_NAME_EMPTY("Error boundary event error name is empty."),
     BPMN_ERROR_BOUNDARY_EVENT_NAME_EMPTY("Error boundary event name is empty."),
-    BPMN_MESSAGE_INTERMEDIATE_THROW_EVENT_HAS_MESSAGE("Message intermediate throw event has message."),
-    BPMN_START_EVENT_NOT_PART_OF_SUB_PROCESS("Start event is not part of subprocess."),
-    BPMN_END_EVENT_NOT_PART_OF_SUB_PROCESS_AND_NAME_IS_EMPTY("End event is not part of subprocess and name is empty."),
+    BPMN_MESSAGE_INTERMEDIATE_THROW_EVENT_HAS_MESSAGE_REFERENCE("Message intermediate throw event has message reference."),
+    BPMN_START_EVENT_NOT_PART_OF_SUB_PROCESS_AND_HAS_NO_NAME("Start event is not part of subprocess and has no name."),
+    BPMN_END_EVENT_NOT_PART_OF_SUB_PROCESS_AND_HAS_NO_NAME("End event has no name and is not part of subprocess."),
     BPMN_MESSAGE_INTERMEDIATE_CATCH_EVENT_NAME_EMPTY("Message intermediate catch event name is empty."),
     BPMN_MESSAGE_INTERMEDIATE_CATCH_EVENT_MESSAGE_NAME_EMPTY("Message intermediate catch event message name is empty."),
     BPMN_MESSAGE_BOUNDARY_EVENT_NAME_EMPTY("Message boundary event name is empty."),
@@ -62,6 +69,9 @@ public enum LintingType {
     BPMN_SIGNAL_END_EVENT_SIGNAL_EMPTY("Signal end event signal is empty."),
     BPMN_END_EVENT_INSIDE_SUB_PROCESS_SHOULD_HAVE_ASYNC_AFTER_TRUE("End event inside subprocess should have asyncAfter=true."),
     BPMN_END_EVENT_NO_INTERFACE_CLASS_IMPLEMENTING("End event implementation class does not implement required interface."),
+    BPMN_INTERMEDIATE_THROW_EVENT_NO_INTERFACE_CLASS_IMPLEMENTING("Intermediate throw event implementation class does not implement required interface."),
+    BPMN_MESSAGE_END_EVENT_IMPLEMENTATION_CLASS_NOT_EXTENDING_ABSTRACT_TASK_MESSAGE_SEND("Message end event implementation class does not extend AbstractTaskMessageSend."),
+    BPMN_MESSAGE_INTERMEDIATE_THROW_EVENT_IMPLEMENTATION_CLASS_NOT_EXTENDING_ABSTRACT_TASK_MESSAGE_SEND("Message intermediate throw event implementation class does not extend AbstractTaskMessageSend."),
 
     // ==================== BPMN GATEWAYS ====================
     BPMN_EXCLUSIVE_GATEWAY_HAS_MULTIPLE_OUTGOING_FLOWS_BUT_NAME_IS_EMPTY("Exclusive gateway has multiple outgoing flows but name is empty."),
@@ -78,6 +88,10 @@ public enum LintingType {
     BPMN_USER_TASK_LISTENER_TASK_OUTPUT_CODE_INVALID_FHIR_RESOURCE("User task listener task output code references invalid FHIR resource."),
     BPMN_USER_TASK_LISTENER_TASK_OUTPUT_SYSTEM_INVALID_FHIR_RESOURCE("User task listener task output system references invalid FHIR resource."),
     BPMN_USER_TASK_LISTENER_TASK_OUTPUT_VERSION_NO_PLACEHOLDER("User task listener task output version does not use placeholder."),
+    BPMN_USER_TASK_LISTENER_PRACTITIONER_ROLE_INPUT_EMPTY(
+            "User task listener input parameter 'practitionerRole' is defined but has no value."),
+    BPMN_USER_TASK_LISTENER_PRACTITIONERS_INPUT_EMPTY(
+            "User task listener input parameter 'practitioners' is defined but has no value."),
 
     // ==================== BPMN FIELD INJECTION ====================
     BPMN_FIELD_INJECTION_NOT_STRING_LITERAL("Field injection value is not a string literal."),
@@ -93,7 +107,7 @@ public enum LintingType {
 
     // ==================== BPMN EXECUTION LISTENER ====================
     BPMN_EXECUTION_LISTENER_CLASS_NOT_FOUND("Execution listener class not found."),
-    BPMN_EXECUTION_LISTENER_NOT_IMPLEMENTING_REQUIRED_INTERFACE("Execution listener does not implement required interface."),
+    BPMN_EXECUTION_LISTENER_CLASS_NOT_IMPLEMENTING_REQUIRED_INTERFACE("Execution listener class does not implement required interface."),
 
     // ==================== BPMN PROCESS ====================
     BPMN_PROCESS_ID_PATTERN_MISMATCH("Process ID does not match required pattern: domain_processname (e.g. testorg_myprocess)."),
@@ -106,8 +120,6 @@ public enum LintingType {
     BPMN_PROCESS_VERSION_TAG_NO_PLACEHOLDER("Process camunda:versionTag does not use '#{version}' placeholder."),
 
     // ==================== BPMN GENERAL ====================
-    BPMN_PRACTITIONERS_HAS_NO_VALUE_OR_NULL("Practitioners has no value or is null."),
-    BPMN_PRACTITIONER_ROLE_HAS_NO_VALUE_OR_NULL("PractitionerRole has no value or is null."),
     BPMN_NO_ACTIVITY_DEFINITION_FOUND_FOR_MESSAGE("No ActivityDefinition found for message."),
     BPMN_NO_STRUCTURE_DEFINITION_FOUND_FOR_MESSAGE("No StructureDefinition found for message."),
 

linter-core/src/main/java/dev/dsf/linter/util/bpmn/BpmnModelUtils.java

@@ -51,6 +51,18 @@ public static Optional<String> extractImplementationClass(BaseElement element) {
         return getCamundaClassFromMessageEvents(definitions);
     }
 
+
+    /**
+     * Returns whether the start event is triggered by a message (has a {@link MessageEventDefinition}).
+     *
+     * @param startEvent the BPMN start event to inspect
+     * @return {@code true} if the start event has a message event definition
+     */
+    public static boolean isMessageStartEvent(StartEvent startEvent) {
+        return !startEvent.getEventDefinitions().isEmpty()
+                && startEvent.getEventDefinitions().iterator().next() instanceof MessageEventDefinition;
+    }
+
     /**
      * Scans a collection of event definitions to find the Camunda class from a MessageEventDefinition.
      *