Support manual event subscription based case event-registry start (#3817)

* add support for dynamic, manually created event subscriptions to start a new case based on a specific combination of correlation values

* small typos and comment improvements

---------

Co-authored-by: Micha Kiener <micha.kiener@flowable.com>

Author: mkiener

modules/flowable-cmmn-api/src/main/java/org/flowable/cmmn/api/CmmnRuntimeService.java

@@ -18,6 +18,9 @@
 
 import org.flowable.cmmn.api.runtime.CaseInstanceBuilder;
 import org.flowable.cmmn.api.runtime.CaseInstanceQuery;
+import org.flowable.cmmn.api.runtime.CaseInstanceStartEventSubscriptionBuilder;
+import org.flowable.cmmn.api.runtime.CaseInstanceStartEventSubscriptionDeletionBuilder;
+import org.flowable.cmmn.api.runtime.CaseInstanceStartEventSubscriptionModificationBuilder;
 import org.flowable.cmmn.api.runtime.ChangePlanItemStateBuilder;
 import org.flowable.cmmn.api.runtime.GenericEventListenerInstanceQuery;
 import org.flowable.cmmn.api.runtime.MilestoneInstanceQuery;
@@ -313,12 +316,12 @@ public interface CmmnRuntimeService {
      * @param identityLinkType
      *            type of identity, cannot be null.
      * @throws FlowableObjectNotFoundException
-     *             when the process instance or group doesn't exist.
+     *             when the case instance or group doesn't exist.
      */
     void addGroupIdentityLink(String caseInstanceId, String groupId, String identityLinkType);
 
     /**
-     * Removes the association between a user and a process instance for the given identityLinkType.
+     * Removes the association between a user and a case instance for the given identityLinkType.
      * 
      * @param caseInstanceId
      *            id of the case instance, cannot be null.
@@ -332,7 +335,7 @@ public interface CmmnRuntimeService {
     void deleteUserIdentityLink(String caseInstanceId, String userId, String identityLinkType);
 
     /**
-     * Removes the association between a group and a process instance for the given identityLinkType.
+     * Removes the association between a group and a case instance for the given identityLinkType.
      * 
      * @param caseInstanceId
      *            id of the case instance, cannot be null.
@@ -381,7 +384,7 @@ public interface CmmnRuntimeService {
     FormInfo getStartFormModel(String caseDefinitionId, String caseInstanceId);
 
     /**
-     * Create a {@link ChangePlanItemStateBuilder}, that allows to set various options for changing the state of a process instance.
+     * Create a {@link ChangePlanItemStateBuilder}, that allows to set various options for changing the state of a case instance.
      */
     ChangePlanItemStateBuilder createChangePlanItemStateBuilder();
 
@@ -442,4 +445,32 @@ public interface CmmnRuntimeService {
      *     when the given event is not suitable for dispatching.
      */
     void dispatchEvent(FlowableEvent event);
+    
+    /**
+     * Creates a new event subscription builder to register a subscription to start a new case instance based on an event with a particular set of
+     * correlation parameter values. In order for this to work, the case definition needs to have an event-registry based start event with a
+     * dynamic, manual subscription based behavior and the registered correlation parameter values within the builder need to be based on
+     * actual correlation parameter definitions within the event model the start event is based on.
+     * Register one or more correlation parameter value with in the builder before invoking the
+     * {@link CaseInstanceStartEventSubscriptionBuilder#subscribe()} method to create and register the subscription.
+     *
+     * @return the subscription builder
+     */
+    CaseInstanceStartEventSubscriptionBuilder createCaseInstanceStartEventSubscriptionBuilder();
+
+    /**
+     * Creates a new event subscription modification builder to modify one or more previously registered case start event subscriptions based
+     * on a particular case definition and with an optional combination of correlation parameter values.
+     *
+     * @return the subscription modification builder
+     */
+    CaseInstanceStartEventSubscriptionModificationBuilder createCaseInstanceStartEventSubscriptionModificationBuilder();
+
+    /**
+     * Creates a new event subscription deletion builder to delete one or more previously registered case start event subscriptions based
+     * on a particular case definition and with an optional combination of correlation parameter values.
+     *
+     * @return the subscription deletion builder
+     */
+    CaseInstanceStartEventSubscriptionDeletionBuilder createCaseInstanceStartEventSubscriptionDeletionBuilder();
 }

modules/flowable-cmmn-api/src/main/java/org/flowable/cmmn/api/runtime/CaseInstanceStartEventSubscriptionBuilder.java

@@ -0,0 +1,86 @@
+/* Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.flowable.cmmn.api.runtime;
+
+import java.util.Map;
+
+import org.flowable.eventsubscription.api.EventSubscription;
+
+/**
+ * A builder API to create an event subscription to start an event-based case instance whenever an event with a very specific
+ * combination of correlation values occurs.
+ * You can model an event-based start for a case model to create a new case instance whenever that event happens, but not, if
+ * it should only start a case on a particular combination of correlation values.
+ *
+ * In order for this to work, you need a case definition with an event registry start, configured with the manual, correlation based
+ * subscription behavior.
+ *
+ * @author Micha Kiener
+ */
+public interface CaseInstanceStartEventSubscriptionBuilder {
+
+    /**
+     * Set the case definition to be started using a manually added subscription by its key. By default, always the latest version is
+     * used to start a new case instance, unless you use {@link #doNotUpdateToLatestVersionAutomatically()} to mark the builder to stick to
+     * exactly the current version of the case definition and don't update it, if a new version would be deployed later on.
+     * This method is mandatory and will throw an exception when trying to register a subscription where the case definition key was not set or
+     * is null.
+     *
+     * @param caseDefinitionKey the key of the case definition to be started a new instance of when the subscription has a match at runtime
+     * @return the builder to be used for method chaining
+     */
+    CaseInstanceStartEventSubscriptionBuilder caseDefinitionKey(String caseDefinitionKey);
+
+    /**
+     * Mark the subscription to not use the latest case definition automatically, should there be a new version deployed after the subscription
+     * was created. This means, adding the subscription will always stick to the current version of the case definition, and it will NOT be updated
+     * automatically should there be a new version deployed later on. By default, when this method is not invoked on the builder, the subscription will
+     * be updated automatically to the latest version when a new version of the case definition is deployed.
+     * The subscription can still be updated to the latest version by manually migrating it to whatever version you want.
+     *
+     * @return the builder to be used for method chaining
+     */
+    CaseInstanceStartEventSubscriptionBuilder doNotUpdateToLatestVersionAutomatically();
+
+    /**
+     * Adds a specific correlation parameter value for the subscription, which means this value needs to exactly match the event
+     * payload in order to trigger the case start (along with all registered correlation parameter values of course).
+     *
+     * @param parameterName the name of the correlation parameter
+     * @param parameterValue the value of the correlation parameter
+     * @return the builder to be used for method chaining
+     */
+    CaseInstanceStartEventSubscriptionBuilder addCorrelationParameterValue(String parameterName, Object parameterValue);
+
+    /**
+     * Registers a list of correlation parameter values for the subscription. The result is the same as registering
+     * them one after the other.
+     *
+     * @param parameters the map of correlation parameter values to be registered for the subscription
+     * @return the builder to be used for method chaining
+     */
+    CaseInstanceStartEventSubscriptionBuilder addCorrelationParameterValues(Map<String, Object> parameters);
+
+    /**
+     * Set the tenant id for the subscription.
+     *
+     * @param tenantId the id of the tenant
+     * @return the builder to be used for method chaining
+     */
+    CaseInstanceStartEventSubscriptionBuilder tenantId(String tenantId);
+
+    /**
+     * Creates the event subscription with the registered combination of correlation parameter values and saves it.
+     */
+    EventSubscription subscribe();
+}

modules/flowable-cmmn-api/src/main/java/org/flowable/cmmn/api/runtime/CaseInstanceStartEventSubscriptionDeletionBuilder.java

@@ -0,0 +1,68 @@
+/* Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.flowable.cmmn.api.runtime;
+
+import java.util.Map;
+
+import org.flowable.cmmn.api.CmmnRuntimeService;
+
+/**
+ * A builder API to delete a manually created case start event subscription which was created and registered using the
+ * {@link CmmnRuntimeService#createCaseInstanceStartEventSubscriptionBuilder()} builder API.
+ * With this API you can delete one or more such subscriptions based on the correlation parameter values and event type.
+ *
+ * @author Micha Kiener
+ */
+public interface CaseInstanceStartEventSubscriptionDeletionBuilder {
+
+    /**
+     * Set the case definition using its specific id the manually created subscription is based on. This is mandatory and must be provided.
+     *
+     * @param caseDefinitionId the id of the case definition the subscription is based on (an exact version of it)
+     * @return the builder to be used for method chaining
+     */
+    CaseInstanceStartEventSubscriptionDeletionBuilder caseDefinitionId(String caseDefinitionId);
+    
+    /**
+     * Set the tenant id in case you are running in a multi tenant environment and the event model needs to be retrieved from a specific tenant.
+     *
+     * @param tenantId the id of the tenant the subscription is created for
+     * @return the builder to be used for method chaining
+     */
+    CaseInstanceStartEventSubscriptionDeletionBuilder tenantId(String tenantId);
+
+    /**
+     * Adds a specific correlation parameter value for the subscription to be deleted. If you register the same correlation parameter values
+     * as when creating and registering the event subscription, only that particular one will be deleted with this builder.
+     * If you want to delete all manually created subscriptions, don't register any correlation parameter values, which would result in all matching
+     * the provided case definition and event-registry start event will be deleted.
+     *
+     * @param parameterName the name of the correlation parameter
+     * @param parameterValue the value of the correlation parameter
+     * @return the builder to be used for method chaining
+     */
+    CaseInstanceStartEventSubscriptionDeletionBuilder addCorrelationParameterValue(String parameterName, Object parameterValue);
+
+    /**
+     * Registers a list of correlation parameter values for the subscription(s) to be deleted.
+     *
+     * @param parameters the map of correlation parameter values to be registered for the subscription
+     * @return the builder to be used for method chaining
+     */
+    CaseInstanceStartEventSubscriptionDeletionBuilder addCorrelationParameterValues(Map<String, Object> parameters);
+
+    /**
+     * Deletes all the matching event subscriptions.
+     */
+    void deleteSubscriptions();
+}

modules/flowable-cmmn-api/src/main/java/org/flowable/cmmn/api/runtime/CaseInstanceStartEventSubscriptionModificationBuilder.java

@@ -0,0 +1,76 @@
+/* Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.flowable.cmmn.api.runtime;
+
+import java.util.Map;
+
+import org.flowable.cmmn.api.CmmnRuntimeService;
+
+/**
+ * A builder API to modify a manually created case start event subscription which was created and registered using the
+ * {@link CmmnRuntimeService#createCaseInstanceStartEventSubscriptionBuilder()} builder API.
+ * With this API you can modify one or more such subscriptions like migrating to a specific version of a case definition (if you choose to not automatically
+ * migrate then to the latest version upon deployment of a new version).
+ *
+ * @author Micha Kiener
+ */
+public interface CaseInstanceStartEventSubscriptionModificationBuilder {
+
+    /**
+     * Set the case definition using its specific id the manually created subscription is based on. This is mandatory and must be provided.
+     *
+     * @param caseDefinitionId the id of the case definition the subscription is based on (an exact version of it)
+     * @return the builder to be used for method chaining
+     */
+    CaseInstanceStartEventSubscriptionModificationBuilder caseDefinitionId(String caseDefinitionId);
+    
+    /**
+     * Set the tenant id in case you are running in a multi tenant environment and the event model needs to be retrieved from a specific tenant.
+     *
+     * @param tenantId the id of the tenant the subscription is created for
+     * @return the builder to be used for method chaining
+     */
+    CaseInstanceStartEventSubscriptionModificationBuilder tenantId(String tenantId);
+
+    /**
+     * Adds a specific correlation parameter value for the subscription to be modified. If you register the same correlation parameter values as when creating
+     * and registering the event subscription, only that particular one will be modified with this builder.
+     * If you want to modify all manually created subscriptions, don't register any correlation parameter values, which would result in all matching
+     * the provided case definition and event-registry start event will be modified.
+     *
+     * @param parameterName the name of the correlation parameter
+     * @param parameterValue the value of the correlation parameter
+     * @return the builder to be used for method chaining
+     */
+    CaseInstanceStartEventSubscriptionModificationBuilder addCorrelationParameterValue(String parameterName, Object parameterValue);
+
+    /**
+     * Registers a list of correlation parameter values for the subscription(s) to be modified.
+     *
+     * @param parameters the map of correlation parameter values to be registered for the subscription
+     * @return the builder to be used for method chaining
+     */
+    CaseInstanceStartEventSubscriptionModificationBuilder addCorrelationParameterValues(Map<String, Object> parameters);
+
+    /**
+     * Migrate all the matching event subscriptions to the latest case definition, which should be done if you want to manually upgrade the subscriptions
+     * to the latest version of the case definition.
+     */
+    void migrateToLatestCaseDefinition();
+
+    /**
+     * Migrate all matching event subscriptions to the specific case definition.
+     * @param caseDefinitionId the id of the case definition to migrate to
+     */
+    void migrateToCaseDefinition(String caseDefinitionId);
+}

modules/flowable-cmmn-converter/src/main/java/org/flowable/cmmn/converter/CmmnXmlConstants.java

@@ -221,6 +221,7 @@ public interface CmmnXmlConstants {
     String ELEMENT_EVENT_OUT_PARAMETER = "eventOutParameter";
     String START_EVENT_CORRELATION_CONFIGURATION = "startEventCorrelationConfiguration";
     String START_EVENT_CORRELATION_STORE_AS_UNIQUE_REFERENCE_ID = "storeAsUniqueReferenceId";
+    String START_EVENT_CORRELATION_MANUAL = "manualSubscription";
 
     String ELEMENT_VARIABLE_AGGREGATION = "variableAggregation";
     String ATTRIBUTE_VARIABLE_AGGREGATION_VARIABLE = "variable";