CMMN Documentation

The item control is called ManualActivationRule. The symbol is modeled after a tape recorder play button. Having the symbol on a model element means that there is a manual activation rule configured for the element. By naming (and table 5.40 in the spec), a rule evaluating to 'true' means manual activation. Not specifying a rule should, according to the specification (figure 5.12) also evaluate to a value of 'true'. This leads to the situation where both of the following tasks have manual activation. This looks like a contradiction and is confusing for modelers as they, in order to configure automatic activation, must define a manual activation rule that resolves to false.

We decided to handle this differently. In the current implementation, a missing manual activation rule defaults to false, meaning automatic activation. Thus, the task on the left auto starts. Another advantage of this is that all missing plan item controls (manual activation, repetition, required) default to false in the case of a missing rule.

In addition, Automatic activation by default is, in our experience, the better choice for the case plan model itself (no symbol) and a better default (because more common) for stages, process tasks and case tasks.

The order and logic related to the evaluation of sentries of a CMMN model is not specified in CMMN specification version 1.0. Because of this, the runtime-evaluation of CMMN models in our implementation is likely to differ from other vendors. edoras one CMMN works as follows:

Triggering plan items

A plan item transitions from AVAILABLE to ACTIVE (or ENABLED) based on its entry sentry configuration and the transitions the sentry’s on-part items undergo (if any).

Plan items are created and made AVAILABLE as their parent container (Case Plan Model or Stage) starts. From that point on, a plan item will listen to a trigger event. Possible trigger events (conditions) are:

An individual sentry triggers under the following conditions:

A sentry’s on-parts (one or more) fire under the following conditions:

Current implementation

Our current CMMN engine implementation behaves according the rules described above, with the following exception:

The behaviour can be described has having a memory effect. For example: We have a plan item with a sentry holding a condition and an on-part. The condition is false. At some point, the on-part item undergoes the desired transition. Now, during some later event processing cycle, the condition switches to true. The plan item triggers.

Starting with edoras one S104, a second type of trigger mode is available. It is called "On event" and does not exhibit the memory effect described above. The trigger mode can be selected on sentry elements in the VIS modeler.

A third trigger mode called "Deferred repetition" is under discussion. The idea is to record on-part transitions that happen as the sentry condition is false. Then, as the sentry condition turns to true, the recorded transitions would be played back in the order they occurred, potentially triggering multiple instances of the sentry’s plan item.

Deferred sentry evaluation (i.e. considering element transitions in sentry on-parts that were observed in a previous model evaluation cycle) are not only relevant in combination with sentry conditions but also in situations where the model element owning the sentry is created at a later point in time. Consider the following situation:

The bottom task will exit as either one of the top two tasks completes. The sentry referring to the top-right task uses trigger mode "Event deferred". If we start the case, complete the top-right task and then start the stage, the bottom task (the one in the stage) will immediately terminate due to the memory effect described above.

By choosing trigger mode "On event", this wont happen. The bottom task can only be exited via the top-left task’s completion if it exists at the point in time the top left task completes.

There is also a forum topic on sentry evaluation https://forum.edorasware.com/t/cmmn-sentry-evaluation-semantics/89

The specification is not clear on how to handle the repetition rule in combination with sentry AND-conditions (multiple on-parts creating an AND condition an a sentry). The edoras one CMMN implementation is based on an algorithm that distinguishes between current and past event transitions.

The specification is not clear on how to handle plan item or case file item on-parts that refer to potentially multiple runtime instances. Our implementation is based on an "at least one" approach.

The first instance of a plan item triggers according to the rules defined under Sentry Evaluation, above. Subsequent instances only trigger if one or more on-parts trigger.

There is an extension in place for repeatable plan items that are configured for manual activation and don’t have a sentry with on-parts. If such a plan item completes, it will create and trigger a new instance of itself.

A plan item can trigger itself, directly or indirectly via some plan item on-part configuration like an on-part connection onto itself. Potential infinite loops must be caught via a suitable sentry condition.

The CMMN engine enforces a configurable maximum recursion limit as a safety precaution. This limit can be configured by setting custom property triggerLimit on the Case plan model to the desired maximum number. Without explicitly setting this property, the limit is set to 1. This means that during a given model evaluation cycle, a maximum number of 1 new instances can be triggered for a given model plan item and parent stage instance.

The following is a legal diagram fragment:

The modeler’s intention in this example is: The ExitSentry of Task 2 has a PlanItemOnPart referring to Task 1 having a sentryRef pointing to the ExitSentry of Task 1. The meaning: Task 1 exiting via the one ExitSentry triggers the exit of Task 2. The problem: just by looking at the diagram, it is not clear which ExitSentry holds the PlanItemOnPart. There should be an arrow or some other symbol indicating the direction of the connector (the PlanItemOnPart).

The CMMN 1.0 XSD doesn’t include a PARENT_TERMINATE transition as depicted in table 7.9 of CMMN specification 1.0. The edoras one CMMN engine uses the EXIT transition instead.

According to CMMN 1.0 specification, completing a stage (unlike terminating it) doesn’t propagate the completion to any child plan items. This means that, as a stage completes, child plan items remain in their current state. This leads to questions regarding child plan items that are in a non-terminal state like AVAILABLE or ENABLED. What should happen if a legal transition on such a plan item is attempted once the parent stage has been completed?

In the current implementation of the edoras one CMMN engine, the transition PARENT_COMPLETE is introduced and used to terminate child plan items in state AVAILABLE or ENABLED. This new transition is used internally. The transition can not be captured by a plan item on-part in the model. The resulting state of a PARENT_COMPLETE transition on a plan item is state EXPIRED.

5.4.9.2 of the specification mentions entry and exit criteria with respect to discretionary items as supported. Figure 5.12 states that DiscretionaryItems are not associated with Sentries. Entry and exit criteria references are modeled in the XML (XSD) only on PlanItems. Not on DiscretionaryItems. The current implementation of the CMMN engine does not support sentries on Discretionary Items.

An arbitrary map of custom String/String properties can be edited during design time and stored on select CMMN elements:

The map is serialized to JSON and stored under attribute customAttributes in the XML. The purpose of these properties is to configure certain CMMN extensions like repeatable user event listeners. Customer implementation extensions can also make use of these properties to implement custom logic based on arbitrary design-time properties.

The elements for which custom attributes are supported are:

Except for the case file item, the customAttribute is stored as part of the item’s PlanItemDefinition.

The CMMN repetition rule allows to create multiple instances of a given model plan item. The triggering of a plan item (START, ENABLE or OCCUR) is controlled by sentries. Only a Sentry with on-parts that fire may lead to the creation and triggering of an additional instance of the plan item.

By introducing the Automatic repetition extension, it is possible to automatically trigger the creation of a new instance of a plan item as it completes. For this to work, a plan item must be configured as follows:

If this is the case, a plan item can repeatedly be created by means of an action button under Available Actions in the case HTML template. The action button becomes available as the previous plan item instance completes.

In the picture above, the two Human task configurations are identical (the on-part event of the Human task on the right hand side is 'complete'). Automatic repetition is simply a modelling short-cut for the pattern on the right hand side with event 'complete'. If you want to be able to create multiple task instances at the same time, consider using the pattern on the right with event 'manualStart'.

The CMMN specification 1.0 states, that a plan item’s repetition expression is evaluated at the point of the plan item’s creation (transition to AVAILABLE) and maintained throughout the life cycle of the plan item. The current implementation handles this differently: The engine evaluates the rule on demand, i.e. each time a new plan item instance may potentially be created, the rule is evaluated.

Please note that automatic repetition may have an impact on stage auto-completion. Manually starting a plan item with automatic repetition leads to the activation of the plan item. As the plan item completes a new plan item instance is created and put into state 'enabled' in order to accept an additional click (i.e. MANUAL_START). This means that, with automatic repetition, by default, there is always an enabled instance of the repeatable plan item in the run-time model. With auto-completion off, this will prevent the parent stage from completing.

Automatic repetition as described above can be disabled on the level of the whole model by setting the following custom property on the case plan model:

In the edoras one CMMN implementation, plan items can be configured to be "completion neutral". If checked, the plan item will not prevent a stage from completing, meaning that such a plan item is neutral with respect to stage completion evaluation. The rationale to introduce this option is as follows:

Following the specification, a stage with a plan item in state Available does not complete unless we set the stage’s auto-complete flag to true. In many modeling situations, this forces us to set a stage to auto-completion as soon as we use a plan item which potentially may remain AVAILABLE. By treating such plan items as neutral, as now possible by setting the Completion Neutral option, we gain modeling flexibility in the sense that we can still use the auto-completion flag to model some other condition of a stage, for example, the handling of plan items in state ENABLED.

A special type of user event listener named Stage Auto Completion is available in CMMN models. This user event listener can be placed in any Stage. It can not be connected to any other item. It is typically placed into a stage which has Auto Complete set to off.

During run-time, this new event listener appears as an action button in the Case GUI if the stage it is part of would complete had it its Auto Completion property set to true. In other words, this new event listener will become available as soon as the stage can be completed in a normal way (in general as soon as there are no more active plan items). Clicking the action button for this user event listener will then complete the stage.

User events and external events support a custom property manualRepetition (simply named Repetition in the VIS properties editor). The value can be any back-end condition. If the condition evaluates to true, a new user event instance is created upon occurrence of the preceding one. This allows the modeler to create a user event button in the GUI which remains visible and can be invoked multiple times. For external event listeners this means that there is always an instance of the event listener available to receive an OCCUR transition.

All edoras one CMMN rules and back-end expressions (like the required, repetition and manual activation rules) are evaluated on demand. There is no default logic in place to evaluate such a rule at the point in time a stage is activated (as the specification defines, for example, for the required rule). By evaluating such expressions on demand, the edoras one CMMN engine adds a great deal of modeling flexibility. For example, it is now easily possible to model plan items that repeat N times. The original evaluation logic can explicitly be modeled by a service task (or some other means) that executes at stage activation time and stores the result of a particular expression on the Case Work Item. By using such a stored variable as a rule expression, the original evaluation semantic is then effectively in place.

According to the specification (description of sourceRef in table 5.22 of CMMN Specification 1.0), plan item on-parts referring to plan items outside the sentry’s stage are not supported. In contrast to the specification, the current implementation of the edoras one CMMN engine allows such connections.

For example, the following diagram shows a valid edoras one CMMN model containing cross-stage on-parts. We have a down-hierarchy connection from task 3 to task 1 (task 3 listens to an event of a task residing in a sub-stage) and an up-hierarchy connection from task 2 to task 4 (task 2 listens to an event of a task residing in a parent stage):

Please refer to section CMMN Connectors ("on-parts") for more examples on cross-hierarchy connections and explanations on how they are resolved at run-time.

Service tasks are available in the palette and can be placed into the model like any task. By means of a runtime expression configured on the service task, arbitrary code can be executed as the runtime representation of the task starts. The result of the expression evaluation is stored in the case scope under the variable name provided by the modeler. Service tasks are non-blocking, meaning, as soon as they trigger, they evaluate the expression, store the result and complete.

This is a very flexible and powerful yet low-level way of integrating custom Java code into a case model. Using this approach, the complete edoras one implementation of the CMMN engine can be replaced with custom implementation code. Replacing or extending a select sub-set of the existing implementation classes is possible too. In order to introduce a custom transition handler for a given plan item, the following steps are necessary:

It is possible to selectively return handlers. The methods in interface CmmnExtensions all have the same signature: they receive

Based on these parameters you can decide which custom handler implementation (if any) you want to return. By returning null, the default edoras one handler implementation will be used.

If you decide to return a custom handler, you have the option to completely replace the default implementation or to invoke your handler code before or after the default implementation code. Check out method getExtensionPoint() in class BaseHandler. If you don’t override getExtensionPoint(), your code will replace the default implementation code.

Please refer to the table on page Standard CMMN State Transition Implementations in order to get an overview of the available default edoras one implementation handlers and their purpose.

These are high-level query methods to get information about a particular running CMMN case. All of these methods return simple Java types or CMMN implementation interfaces

These are low-level query methods to get information about a particular running CMMN case. These methods return actual implementation objects. Whenever possible, use one of the higher-level methods above.

This property allows to expose CMMN plan item model elements by model Id on the deployed Case definition. It takes the form:

The property receives a comma-separated list of plan item types. The possible plan item types are:

The types honor hierarchy, so by setting a property value of PlanItem, all plan item model Ids in the CMMN model will be exposed.

The model Ids will be written to a Case definition Work Object variable named cmmnModelIds_<plan-item-type-from-property-value>. As many work object variables will be created as there are comma-separated elements in the property value.

Note: the stage representing the CasePlanModel will never be output. This is due to the structure of the CMMN XML where the CasePlanModel stage does not have a corresponding plan item element.

For example, by specifying property

The following work object variables will be created and stored on the Case Definition Work Object:

The variables will list the model Ids of the named types that are modeled in the CMMN model.

Note: by making use of the plan item type hierarchy, you can expose the same model Ids in one result variable. To do so just specify a property value of EventListener.

This property, in combination with property cmmn.expose.planItemStates, allows to expose CMMN run-time plan item states as Case Work Object variables. The property is defined like:

The property takes a comma-separated list of plan item types (similar to property cmmn.expose.planItemModelTypes). For more information, see the description for the next property.

This property, in combination with property cmmn.expose.planItemTypes, allows to expose CMMN run-time plan item states in Case Work Object variables. The property is defined like:

The property takes a comma-separated list of plan item states. Possible states are: AVAILABLE, ENABLED, DISABLED, ACTIVE, FAILED, SUSPENDED, TERMINATED, COMPLETED, CLOSED, EXPIRED (EXPIRED is a non-standard CMMN state used to mark plan items that were in states {AVAILABLE, ENABLED}, as their parent stage completed). The key word ALL is supported to expose all of the above states.

The result of defining properties cmmn.expose.planItemTypes and cmmn.expose.planItemStates are Case Work Object variables named after the naming scheme described below, each containing a comma-separated list of zero or more CMMN run-time plan item instance Ids.

The generated Case Work Object variables are named according to the following pattern: _cmmn_states_<plan-item-type-from-property-value>_<plan-item-state-from-property-value>. Each variable lists the plan item instance Id(s) for the respective combination of plan item type and CMMN state.

For example, by specifying properties

The following work object variables will be created and stored on the Case Work Object:

The variables will list the plan item instance Ids of all plan items of type ExternalEvent that are in the respective state (AVAILABLE or ENABLED). If there are no states for a particular type and state combination, the value stored under the respective case variable will be the empty string.

Adapting to configuration changes

Any state case variables maintained via these configuration properties that have become obsolete (their configuration changed such that their type/state combination is no longer exposed) are set to a value of null. This is in contrast to a value of an empty string, indicating, that the variable is maintained but the case doesn’t currently hold any plan items for the respective type/state combination.

The existing case.html template is supported. In particular the areas:

Active Work Items - For active human tasks and active work items from process tasks and case tasks.

Case File Items - For created case file items

Case Actions - For the starting of tasks with manual activation and for the creation of case file items (according to their multiplicity property)

Sentry If-conditions are supported (evaluated in the context of the case).

Connectors to tasks and stages are supported (plan item on-parts). Supported transitions:

Transitions SUSPEND, RESUME, PARENT-SUSPEND, PARENT-RESUME are not yet supported. CLOSE (on the level of the case) is not supported. Instead, once a case reaches COMPLETED or TERMINATED, it is archived (edoras one ARCHIVED state).

The events

are supported by the CMMN service and custom transition implementations (extension code) for plan items (except the case itself). There is currently no GUI support available to trigger these events and limited support for their visualization (visualization is only supported for DISABLE - disabled stages don’t appear in the currentStates list, and disabled tasks and stages do not generate an action entry in the availableActions list).

The transition

is supported for Milestones and Event listeners:

Connectors to case file items are also supported (case file item on-parts). Supported transitions:

Support for the formal modelling of CMMN roles is not implemented. However, support for access control based on the concept of edoras one "candidate users" and "candidate groups" is provided for Human tasks and the control of the visibility of action buttons (available actions).

Discretionary items planning has been partially implemented. However, support in the modeler and the Case Template (case.html) has been removed due to the limited value of the current implementation. The whole planning aspect will be re-addressed at a future point in time.

Repetition - the Repetition property is supported, including the dynamic evaluation of an expression to determine the property value. If repetition == true, new plan item instances are created depending on entry sentry evaluation.

Manual activation - the ManualActivation property is supported, including the dynamic evaluation of an expression to determine the property value. For manual activation items, menu entries are made available in the Case Actions menu for the starting of these items.

Required - the Required property is supported, including the dynamic evaluation of an expression to determine the property value. The Required property is relevant for the determination of a Stage’s completion status (AutoComplete flag on the Stage).

Blocking - By default, tasks are blocking, meaning their transition to COMPLETE is triggered by an event outside of the case engine (i.e. by a case worker explicitly completing a HumanTask). By modeling a task as non-blocking, the engine immediately completes the task after START (or MANUAL_START).

Autocomplete - the Autocomplete property is supported for stages.

Custom plan item model attributes (name/value pairs, both simple strings) are supported for plan items and case file items.

Custom attributes are needed to extend or qualify the execution semantics in the context of client integration projects.

Custom plan item run-time state (name/value pairs, both simple strings) are supported for plan items. Custom state properties allow to store small bits of information on a plan item run-time instance.

The states of the plan items contained in a stage at run-time determine stage completion ("plan item" is the general term for modelling elements like stages, tasks, milestones and event listeners). The following states are important in this context:

Stages like to complete (unless something prevents them from doing so). In particular:

Two simple conditions that stop a stage from completing:

Plan items in state AVAILABLE or ENABLED (that are not required) may also prevent a stage from completing. Here, however, we have to look at the Auto Completion property of the stage. Provided the above rules are met, a stage with any plan item in state AVAILABLE or ENABLED will complete under the following conditions:

The following modeling properties have an impact on stage completion:

The edoras one CMMN implementation allows modelers to freely connect plan items with each other via sentries and plan item on-parts (or case file item on-parts when referring to a case file item).

The following types of connections are supported:

The following section explains how various types of on-part connections are resolved by the CMMN engine at run-time.

On-part standard events (like Complete) are resolved according to the following policies:

For entry sentries:

For exit sentries:

Please refer to section Stage Hierarchy - model structure vs run-time structure for an explanation what "common run-time hierarchy" means.

The following figure is provided to illustrate the on-part resolution logic for a few types of plan item connections:

Note: For the sake of this example, all sentries listen to standard event Complete. However, the type of event is not relevant with respect to the resolution logic described here.

In order to explain how these connections are being handled in a running case model, we have to consider it with respect to a particular run-time state. Let’s assume the following run-time structure (the integer suffix denotes the run-time instance of the model element):

The connections marked in the diagram behave as described below:

Plan item on-parts are evaluated with respect to their run-time stage hierarchy. As soon as we are using repeatable stages, the run-time hierarchy of a particular running CMMN model may contain multiple stage instances and thus may contain multiple parallel hierarchy branches. Consider the following model:

The model structure looks like this:

The on-part connector connects task with dependent task. The tasks live in different model hierarchy branches. If we run this case and invoke the User event listener "Start parent stage" once, we get the following run-time hierarchy.

In this scenario, associating the on-part event with its corresponding sentry is unambiguous - we only have one instance of dependent task. Completing task will trigger dependent task (assuming the sentry listens to event Complete).

If we invoke the User event listener "Start parent stage" a second time, we get the following run-time hierarchy:

We now have two instances of dependent task. The engine must now ensure that the correct instance of dependent task is triggered. edoras one CMMN does this by evaluating plan item on-parts within their common run-time hierarchy. Completing task #1 will trigger dependent task #1 but not dependent task #2.

The way the CMMN engine evaluates the Complete event in the model depicted above can be explicitly modeled by introducing an intermediate element in the common model hierarchy of the two connected plan items. This might look like the following:

By introducing the milestone, we explicitly resolve the cross-hierarchy on-part to an up-hierarchy on-part (from task to milestone) and a down-hierarchy on-part from milestone to dependent task. (This can be viewed as resolving an N-to-M relation between the two tasks to an N-to-1 relation to the milestone and then a 1-to-M relation from the milestone to th dependent task.) The run-time structure looks like this:

In most modeling scenarios, using the milestone is not necessary, since the CMMN engine always resolves the on-part with respect to the run-time hierarchy at hand. However, by introducing a common element like the milestone, you can change the behaviour of your plan item on-part connectors.

For example, in the following model, the milestone was put in the top-most level of the diagram (the Case plan model). The effect is now such that completing any instance of task will trigger all instances of dependent task, regardless of the run-time branch dependent task resides in.

The model above effectively "broadcasts" a Complete event of task to all run-time instances of dependent task, regardless of the run-time hierarchy branch dependent task resides in.

The following picture provides a graphical summary of the CMMN parameter support as described in this section. The diagram represents the course of action as a simple model is evaluated (as visible on the left hand side of the diagram, the model consists of an Event listener triggering a Human task with manual start property).

Parameters in edoras one CMMN are key/value pairs which are available for evaluation in CMMN back-end expressions. By default, these parameters are not persisted. They are maintained in memory and are available during a model evaluation cycle. Task parameter maps or service tasks can be used to selectively persist such parameters to the Case Work Item or to pass them on to Human task, Process task or Case task Work Items.

There are two types of parameters:

There are two "time-to-live" scopes for parameters:

Some background: The starting point for a CMMN model evaluation cycle is a CMMN service method invocation. The call wraps a model evaluation cycle. Within an evaluation cycle, multiple plan item transition may take place. For example, a CMMN service call can apply a specific transition to a specific plan item instance. This transition will be processed and will trigger a re-evaluation of the CMMN run-time model, possibly triggering more plan item transitions as part of the same evaluation cycle. The form scope parameters will only be available for the initial plan item transition, the param parameters for all transitions within the same cycle.

By default, edoras one init form data (e.g. when manually starting a Human task via an init form) are passed into the evaluation cycle with form scope. Form scope parameters are automatically persisted on the first Work Item started as part of the evaluation cycle.

Param scope parameters can be passed into the evaluation cycle in the following ways:

Unlike form scope parameters, param parameters are not automatically persisted. They can be persisted, however, by explicitly mapping them in the parameter maps of Human tasks, Process tasks or Case tasks. Or by using a service task for that purpose.

Within a state model, input and output parameter maps of Human tasks, Case tasks and Process tasks can be used to pass parameters between the Case Work Item and the respective edoras one Work Item representing the CMMN task. In the VIS modeler, the input map is called "In", the output map is called "Out". They are available in the properties panel of Human tasks, Case tasks and Process tasks.

The input parameter map is used to map parameters to the edoras one Work Item representing the task (Task Work Item for a Human task, Case Work Item for a Case Task, Process Work Item for a Process task). The mapping takes place as the task is started (START or MANUAL_START transition). Mapped input parameters are persisted on the target Work Item. The evaluation context for the parameter expressions are: Case Work Item, form scope parameters and param scope parameters.

The output parameter map is used to map parameters from the Work Item representing the task to the Case Work Item. The mapping takes place as the task work item completes (COMPLETE transition). Mapped output parameters are persisted on the Case Work Item (except for _param_ prefixed parameters, which are stored in memory with param scope). The evaluation context for the parameter expressions are: the edoras one Work Item representing the CMMN task, form scope parameters and param scope parameters.

Parameters can be accessed by name in CMMN back-end expressions. Form scope and param scope parameters are mapped into the same namespace, with param type parameters taking precedence in case of name clashes. Typical scenarios are:

Parameters can also be accessed by CMMN extension code via the transitionData object, which exposes getter methods for the form data and parameter data maps (for form and param scope parameters, respectively).

Parameter values can be written/updated in any of the following ways:

The following parameters are automatically provided by the CMMN engine for resolution in back-end expressions:

See section Expression variables with special meanings for more information.

There are two evaluation cycles (and thus param scopes) involved in the starting of plan items with manual start property. First there is an ENABLE transition and then, at a later point in time a potential MANUAL_START transition. Often, the state of parameters and trigger items as present at ENABLE time is required during the evaluation cycle of MANUAL_START. To cater for this, the edoras one CMMN engine takes a snapshot of the parameters and trigger items at the point of ENABLE and makes it available during the MANUAL_START cycle. Parameters explicitly passed into the MANUAL_START cycle will overwrite any pre-existing values from an earlier ENABLE cycle.

The following two examples are provided to illustrate some of the concepts and features presented above.

Example 1: Euclid’s algorithm to calculate the GCD of two integer values

The goal of the first case is to calculate the greatest common divisor of two integer values. To do so, the CMMN case model described below implements the recursive version of Euclid’s algorithm.

The case plan model looks as follows:

The case takes two input parameters (the integer values for which to calculate the GCD). They are passed into the case as form scope parameters a and b. If b equals zero, a is returned immediately (i.e. set as result on the case). If b is not zero, the case invokes itself recursively with parameters a := b and b := a modulo b.

The case init form looks like this:

The case work form, presenting the calculated result at the end, looks like this:

The input parameter map of the case task in the model is configured like this:

And the output parameter map like this:

Example 2: Recursive calculation of the Fibonacci number

In the second example, the Fibonacci number is calculated for some integer input N. Unlike the previous example, in this case the _triggerItems parameter is used to access the result of two recursive case invocations. The model looks like this:

The service task expression for "add results" looks like this:

('onecasetask1' and 'onecasetask2' are the model IDs of the two case tasks in the 'sum of' stage.)

edoras one CMMN models support back-end expressions at various locations. These include:

All of the above expressions are evaluated in the context of a given Work Item. By default, this Work Item is the Case. Where applicable, however, a more specific Work Item is set up as the evaluation context for a particular expression. The exact Work Item is determined based on the type of expression. For example, the Work Item context for the evaluation of a Process task’s output parameter map is set up to be the current Process Work Item.

With respect to back-end expressions there is also the concept of the current plan item. The current plan item can be referred to by name _planItem. Here again, the engine will provide the most specific plan item under that variable name when referring to it in an expression. For example, when evaluating the Show state property of a stage, the plan item accessible via _planItem will be the stage for which the expression is being evaluated.

The following special variables (or "implicit parameters", as referred to in the CMMN Parameters section) are available for expression resolution:

Use this variable to refer to the current plan item. As mentioned above, this is the most specific plan item with respect to the expression being evaluated. Expressions evaluated in the context of the case will receive the Case Plan Model as current plan item.

The result returned is a view on the requested plan item, exposing the following properties:

Use this map to refer to any existing plan item instance in your CMMN run-time model. Pass an instance Id as key into the map (see Instance Ids, below). For example, to refer to the third instance of a model element "humantask", use the following expression:

Note: Passing a model Id (no instance suffix) will always refer to the most recent instance (highest instance suffix) available.

Every plan item which can be modeled with an entry sentry automatically receives a standardized input parameter map named _triggerItems bound the model evaluation cycle during which the plan item is triggered. The map contains key/value pairs of type String/EventSource with entries representing the plan item(s) that triggered the current plan item:

Example:

As task B-ID is triggered (started or enabled), it will receive the following input trigger items map:

An instance Id is a Model Id suffixed with a tilde and the plan item’s instance number. For example, given a Human task element with Model Id 'onehumantask', once the first instance of the Task plan item has become available in the run-time model, the plan item can be referred to as _planItems['onehumantask~1'] in an RT expression.

Work Object IDs (aka Work Item IDs) used in back-end expressions automatically resolve to their underlying object. This means you can refer to Work Item properties by means of some ID reference you hold to that Work Item. The workItem property of _planItem is such an ID reference. Consider for example the following situation:

Here we have Process task with an exit sentry. The BPMN process referred to by the task in our example maintains a boolean property as a work object variable named 'exitMe'. This variable can be tested by the sentry condition in the CMMN process task like this:

Work Object variables can simply be referred to by name. For example, the following sentry expression

will evaluate the Case variable myVariable in a boolean context (the Work Object context for entry sentries is always the Case Work Item).

CMMN has a concept for stages and milestones. They somewhat overlap but don’t have exactly the same lifecycle. This secion describes how they can be visualized within the case template at runtime and how they can be configured/modeled within a CMMN case model.

A stage can have the following visualization options (they might change over the lifecycle of the case):

A milestone can have the following visualization options (they might change over the lifecycle of the case):

In addition to whether a state and milestone is rendered within the case template or not, there is a certain order on how they will be rendered. As the case model does not provide a flow-kind of modeling but is rather event and condition driven, the order of stages and milestones must explicitly be modeled within the CMMN case model.

The current implementation of the case templates only knows a concept named availableStates, where milestones and stages are both rendered as states. States have three different options; available, active and completed managed with two boolean flags named isCurrentState and isCompleted.

As a first implementation due to simplicity and also to learn about the real-world requirements, the following new attributes are supported within an edoras vis CMMN case model.

New milestone attributes:

If the show state flag is true or the expression resolves to true, the milestone is rendered as an available state. As soon as the milestone has been reached, it is rendered as a reached state

New stage attributes:

If the show state flag is true or the expression resolves to true, the stage is rendered as an available state. As soon as the stage is active, it is rendered as active. Once it completes, it is rendered as complete.

The default order among stages and milestones with the same user-configured display order is by age (instance creation time). The younger a stage, the more to the right it will appear. Milestones are also ordered by age but grouped and displayed next to their parent stage.

Model a task which automatically starts as its enclosing stage becomes active. In this example, the enclosing stage is the Case Plan Model. As the case is started, the task starts as well.

Model a task which can be started by the user clicking an action button. In this example we have a case model containing a single human task. The task is modeled with Manual Activation set to true. As the case starts, the task is set to state ENABLED. Selecting the task from the list of available actions manually starts (activates) the task.

Trigger (start) a task based on the result of an expression evaluation. In this example we have a case model containing a single Human Task. The task is started as soon as the user sets the name of the case to "task".

Trigger (start) a task based on an event happening on some other model element. This can be modeled using connector lines ("on-parts") between the involved model elements. In the following example we have a case model containing two human tasks. One task starts upon completion of the first task. The relevant event (state transition) to listen to can be configured on the connector line. In this example it’s the "Complete" event.

Like in the previous example, we want to trigger a task based on an event happening on some other model element. However, in this case, more than one preceding plan item event may trigger our task. At least one event must happen to trigger the task (logical OR). In our example, tasks "A" and "B" are started as the case is started. Completing any of the tasks starts task "A or B completes".

In this example multiple plan item on-parts need to form a logical AND. In order for our target task to trigger, all connected plan items must undergo the desired on-part event. In the example below we have a case model containing three human tasks. Tasks "A" and "B" are started as the case is started. Completing both of the tasks starts task "A and B complete".

Note: the required tasks don’t have to undergo the selected transition simultaneously. The CMMN engine remembers the last transition of a plan item. As soon as the last AND connected task undergoes the desired transition, and all other plan item’s last transition matches the desired one, the follow-up task is started.

A task must be able to be executed multiple times at the user’s discretion. There are various ways to model repeatability of plan items. The simplest way is via setting both Manual Activation and Repetition on our task model element. The CMMN engine treats this configuration in a special way: as soon as the task completes, a new instance is created and triggered (set to state ENABLED).

Note: With this setup, there is always an ENABLED instance of the task available. This has an impact on stage/case auto-completion (see next example)

The use-case is the same as in the previous example. However, this time a User Event Listener is used to trigger multiple task instances. Apart from the different graphical model, the run-time behaviour is also slightly different: the creation and triggering of the tasks is controlled via the User Event Listener and not indirectly via the completion of the repeatable task as in the previous example.

Multiple instances of the task can be started (made ACTIVE) at the same time by repeatedly clicking the action button. With this setup, the task goes from CREATED straight to ACTIVE. Using 'Completion neutral' on the User Event Listener, the case more easily auto-completes compared to the previous example as there is never a pending task instance in state ENABLED.

Init forms configured on the task are ignored. In this setup, the task is immediately started once the event listener is selected and the user is navigated to the started task’s work form.

This is another variation on the previous use-case. It demonstrates how a plan item on-part to itself can be used to trigger the repetition. In this example, the standard event that is configured on the plan item on-part (the dotted connector line) is Manual start.

Set up more than one instance of a plan item in one step. In this example exactly two instances of the same repeatable stage are activated as the case starts. This is achieved using a plan item on-part to itself listening to the 'Start' event.

The on-part introduces a recursion which we have to end by means of a condition. In our example, the sentry condition is _planItem.instanceCount < 2.

Note: To protect against infinite looping, by default, the CMMN engine limits the creation/triggering of plan item instances (within the same parent stage) to 1. This limit can be raised setting custom property triggerLimit on the Case Plan Model.

A user must complete a particular task exactly N times. This can be modeled in various ways. One possible way is depicted in the following diagram:

Respond to a Case variable update by means of a Case File Item. In this example we have a case model containing a Case File Item of type "edoras case variable" (the case variable to be monitored is set to "myvar"). We also have a task listening to the UPDATE event of the Case File Item. Each time case variable "myvar" changes, a new instance of the task is started.

Trigger a plan item each time a particular expression turns to true. This is not possible with a simple sentry. In CMMN, repeatable plan items are only triggered based on a plan item "on-part" (a connector to another plan item). Merely triggering on a condition is not possible (except for the first instance).

However, by using a Case File Item of type "edoras case variable", we can achieve this type of behavior. Bind the Case File Item to a case variable of your choice and trigger the evaluation of the plan item’s sentry by updating the variable. In the sentry expression, an arbitrary condition can be evaluated determining whether to actually trigger the task or not.

Enable a task (and make it required) based on some business condition (or planning step). Allow to "undo" this based on changing business conditions.

The task "Send Christmas card" in this example will show up as enabled (with an action button) and will be required to complete if the name of the case equals 'vip'. As soon as the name of the case changes, the task is not required anymore and its action button is hidden. Toggling between the two states can happen as often as necessary.

The expression for the Required Rule is case.name == 'vip'. The expression for the Hide-if expression (under Activation attributes) is not _planItem.required (which is the same as case.name != 'vip' but without duplicating the expression logic of the Required Rule for better maintainability).

Visualize reached (and pending) milestones in the states bar of the case template. In this example we have a case model containing a task and a milestone. As the case is started, the milestone is displayed as pending. As the task completes, the milestone is reached and changes its color to COMPLETED.

Structure your case using Stages and Plan Fragments. Use Stages to structure the run-time behavior of your case. Use Plan Fragments to graphically group related elements in your model. While Stages have a life-cycle and a GUI representation (AVAILABLE/ACTIVE/COMPLETED), Plan Fragments are merely a means to group model elements.

Stages and Plan Fragements can be nested to any level. Stages can be fitted with entry and exit sentries and connected via on-parts (connector lines).

Stages can be exited via exit sentries. In this example, we have a case model containing a stage which can be prematurely terminated by means of a user event listener and exit sentry. This model pattern should be used with care. Only use it to support and model business scenarios where a stage is pre-maturely aborted. Normal stage completion should, when ever possible, be modeled via the stage’s auto-completion capability. See Case and Stage completion, further down.

Abort an active (or enabled) task. Task elements can also be terminated by means of exit sentries. Similar to the previous example, by clicking the user event listener, the end of the stage’s life-cycle can be forced. However, this time indirectly via the termination of the task.

Manage the life-cycle of your case (and possibly of sub-stages within it) via the auto-completion capability of Stages (and the Case Plan Model itself). Stage auto-completion works as follows:

A stage automatically completes as soon as it finds all of its child elements in state COMPLETED or TERMINATED.

Using default settings, a stage with children in states AVAILABLE (created but not yet triggered) or ENABLED (triggered but with Manual Activation) will not automatically complete.

A modeler however may choose to force auto-completion of a stage containing AVAILABLE or ENABLED children by setting the stage’s "Auto complete" property to true.

The property "Completion neutral" on plan items can be used to help with auto completion. It will render the state AVAILABLE neutral with respect to stage completion.

The following case contains a single task and a user event listener. By completing the task, the stage won’t complete as it still observes the user event listener "Early exit" in state AVAILABLE. To force stage completion for this situation, the modeler can either set the stage to "Auto complete" or set the user event listener to "Completion neutral".

Variation with "Auto complete"

Variation with "Completion neutral" on the event listener

Allow a user to complete a stage for which no further work needs to be done.

The model element "Stage auto completion" is available to allow a case worker to manually set a stage to auto-completion. A stage with auto-completion set to true will complete even if there are available or enabled plan items in the stage.

Consider the following example: after running the case, the case is active. The case doesn’t auto complete because there are plan items in states AVAILABLE and ENABLED (and the case’s Auto complete property is set to false).

By clicking the event listener, the stage will be manually set to "Auto complete" and will thus complete as a result of the user clicking the action button.

Note: if there were an active task, setting "Auto complete" to true would not complete the stage. Consequently, the "Complete case" action button would not be visible (the CMMN engine only shows Stage auto completion buttons if selecting them actually completes the stage).