Skip to main content

Manual case and process start event subscriptions

v3.15.0+ for event registry process start, v3.15.1+ for event registry case start

Introduction​

This tutorial explains on how to use event registry start events for both case and process models with manually created and registered event subscriptions with a specific combination of correlation parameter values.

It was always possible to use an event registry start event for both process and case models in order to start a new process or case instance based on an inbound event or even make it kind of a singleton in a sense that for a particular combination of correlation parameter values, a new instance would be started only, if none already running at the event time.

But it was not possible to only start a new instance based on a defined, specific combination of correlation parameter values.

This how-to guides you through all necessary steps to manually register combinations of correlation parameter values to subscribe to an event in order to start a new process or case.

Event registry based models​

Sample use case​

In our example use case, we receive customer data changes over an event inbound channel and want to react to some of them, but not all by either starting a new process or case instance depending on the type of change or customer or even source.

Event definition model​

We assume to have a customer change event with three correlation parameters:

  • customerId - the id of the customer (most likely coming from your CRM)
  • changeType - the type of the change (e.g. address change, contact change, budget change, etc)
  • sourceType - the source producing the event (e.g. CRM, ERP, manual, etc)

The event definition could look like this: Event definition model

To make things simple, we just used two generic payload fields for the actual change data (like the changed address) as we only focus on the correlation parameters and how to create subscriptions for them.

Process and case model​

To make use of this event, we create a process and case model with an event registry start event to kick off a new instance.

Look at this very simple process model, the interesting part of course is the event registry event start, the rest is just showing on how to use the actual event data, but does not do anything for this example: Process model

To configure the start event, you can open the event property and select our previously created event model and then switch to the Payload mappings tab and map the event fields to whatever variable name you want inside the process. The payload fields have been marked as transient, assuming they would be processed at the very start of the process and saved in a less generic way: Process model

The case model looks a bit different as we don't have a visual event registry start event like we do in BPMN as it is not part of the CMMN spec, however, you can find the details in the Case plan model properties. Case model

As for the event start modeling, it is exactly the same as what we did in the process model, you can reach it through the Case plan model and then the Inbound event property: Process model

note

Please pay attention to the Behavior property, which is Start a new instance by default, but for our howto needs to be changed to Through manually created correlation-based subscriptions, which means, by just receiving an event of the mapped event model, nothing will happen, until you manually create subscriptions for it, which we are going to look into below.

Register a specific correlation parameter value event subscription​

As we have our models setup now, we want to look into the details on how to subscribe to very specific event correlation parameter values in order to start a process or case when an event of that combination happens.

As a first example, we want to start the process when a customer change event happens for a very specific change type and source of change, but for all customers:

public void registerEventSubscription(RuntimeService runtimeService) {
    // subscribe for address change event type coming from the CRM
    runtimeService.createProcessInstanceStartEventSubscriptionBuilder()
        .processDefinitionKey("customerChangeProcess")
        .addCorrelationParameterValue("eventType", "addressChange")
        .addCorrelationParameterValue("sourceType", "CRM")
        .subscribe();
}

There is a builder API, reachable through the process runtime service to create and register event subscriptions for manual process starts with a specific combination of correlation parameter values.
The process definition key must be provided and at least one correlation parameter to make it different from a general process start on an event reception. You can add one or more correlation parameter values to create a subscription for exactly that combination.
In our example, we can see that we only want the process to be started, when we receive an addressChange from the CRM, but for all customers.

As a second example, we want to start a case for a budget change coming from the ERP as it might be a bit more complex to handle and needs more flexibility, so a case is more doing it as a pure process model:

public void registerEventSubscription(CmmnRuntimeService cmmnRuntimeService) {
    // subscribe for address change event type coming from the CRM
    cmmnRuntimeService.createCaseInstanceStartEventSubscriptionBuilder()
        .caseDefinitionKey("customerChangeCase")
        .addCorrelationParameterValue("eventType", "budgetChange")
        .addCorrelationParameterValue("sourceType", "ERP")
        .subscribe();
}

The builder API is accessible through the CMMN runtime service and is very similar to the process one. The only change we did was registering for a different set of correlation parameter values.

Automatic vs. manual migration of subscriptions​

Assume we have a process or case model using the event registry start event to kick-off a new instance depeding on manually created subscriptions as we just learned in the chapters before.
What happens, if we deploy a new version of that model? Let's first look at the default behavior, when we always want to start a new instance and not using manual subscriptions. In this case, the generic event subscription is automatically updated to reflect the latest model definition so in other words, such a generic event-based start will always start the latest version of the model.

With the new manual subscription behavior, we can actually choose, whether those manually registered subscriptions will automatically be updated to the latest version or if they stay with exact the version they have been subscribed to.

Both scenarios can make sense, automatically migrating to the latest version first of all gives you the same behavior like with the other options by always using the latest version automatically, but manually migrating gives you more control on which exact version you want to start. Maybe the existing subscriptions rely on exactly the version of the model they have been created for and might not work with a newer version just out of the box.

note

By default, manually created subscriptions are always automatically migrated to the latest version should their referenced process or case model be newly deployed, unless you explicitly mark it as not to be updated within the builder API before subscribing.

We use the same example as before (for the process subscriptions), but this time mark it to NOT automatically update to the latest version:

public void registerEventSubscription(RuntimeService runtimeService) {
    // subscribe for address change event type coming from the CRM
    runtimeService.createProcessInstanceStartEventSubscriptionBuilder()
        .processDefinitionKey("customerChangeProcess")
        .addCorrelationParameterValue("eventType", "addressChange")
        .addCorrelationParameterValue("sourceType", "CRM")
        .doNotUpdateToLatestVersionAutomatically()
        .subscribe();
}

The only difference is the doNotUpdateToLatestVersionAutomatically() method to mark the builder to not migrate automatically. Of course it works exactly the same with the case event subscription builder. In the next chapter, we can see on how to manually migrate such event subscriptions.

Manually migrating event subscriptions​

If you chose to NOT let manually created subscriptions to be migrated automatically, you need to manually migrate them, if needed, otherwise they will stay with exact the same version they have been created with.

There are several ways on how to migrate the event subscriptions:

  • all at once for a particular process / case definition
  • only selected ones according their correlation parameter values
  • migrate to the latest version or even to a very specific one

If we look at the last example, where we added the doNotUpdateToLatestVersionAutomatically() within the builder API, it means that the manually created event subscriptions will not be updated (migrated) automatically, should a new process model version be deployed.
Instead, we have to manually migrate them.

This first example migrates all manually created event subscriptions for one particular process definition (regardless of all the correlation) and migrates it to the latest, most current version:

public void migrateEventSubscriptions(RuntimeService runtimeService, String oldProcessDefinitionId) {
    // migrate all manually created event subscriptons for a particular process model,
    // regardless of their correlation parameter values
    runtimeService.createProcessInstanceStartEventSubscriptionModificationBuilder()
        .processDefinitionId(oldProcessDefinitionId)
        .migrateToLatestProcessDefinition();
}

We have to provide the exact process definition version using the definition id, not the key, because this gives us way more control to migrate from a very specific version to another specific one as we will see in the next example.

public void migrateEventSubscriptions(RuntimeService runtimeService,
    String oldProcessDefinitionId, String newProcessDefinitionId) {
    // migrate all manually created event subscriptons for a particular process model,
    // regardless of their correlation parameter values
    runtimeService.createProcessInstanceStartEventSubscriptionModificationBuilder()
        .processDefinitionId(oldProcessDefinitionId)
        .migrateToProcessDefinition(newProcessDefinitionId);
}

Or if you only want to migrate one very specific event subscription, you can do this as well:

public void migrateEventSubscriptions(RuntimeService runtimeService, String oldProcessDefinitionId) {
    // migrate all manually created event subscriptons for a particular process model
    // and correlation parameter value set to the latest version
    runtimeService.createProcessInstanceStartEventSubscriptionModificationBuilder()
        .processDefinitionId(oldProcessDefinitionId)
        .addCorrelationParameterValue("eventType", "addressChange")
        .addCorrelationParameterValue("sourceType", "CRM")
        .migrateToLatestProcessDefinition();
}

As you can see, you have the full flexibility to migrate exactly the event subscriptions you want to migrate and to exact the version you need.
Or, as we have seen before, you can let Flowable migrate automatically whenever a new version is deployed.

Manually deleting event subscriptions​

The same way you can migrate event subscriptions, you can also remove (delete) them again. Maybe you no longer want a particular event to be consumed or whatever the reason, but there is a deletion builder API as well allowing you to delete manually created event subscriptions.

public void deleteEventSubscriptions(RuntimeService runtimeService, String oldProcessDefinitionId) {
    // delete all manually created event subscriptons for a particular process model
    runtimeService.createProcessInstanceStartEventSubscriptionDeletionBuilder()
        .processDefinitionId(oldProcessDefinitionId)
        .deleteSubscriptions();
}

Or if you only want to delete a very specific event subscription:

public void deleteEventSubscription(RuntimeService runtimeService, String oldProcessDefinitionId) {
    // delete a very specific manually created event subscription
    runtimeService.createProcessInstanceStartEventSubscriptionDeletionBuilder()
        .processDefinitionId(oldProcessDefinitionId)
        .addCorrelationParameterValue("eventType", "addressChange")
        .addCorrelationParameterValue("sourceType", "CRM")
        .deleteSubscriptions();
}

Summary​

In addition to start new process or case instances whenever a certain event happens, with the manual subscription you can specify exactly for which combination of correlation parameter values you want to start a new case or process instance and also handle the migration whenever a new version is deployed to be fully automatic or manually controlled.