CMMN Documentation

1. Design & Implementation Notes

1.1. CMMN Specification Issues (and interpretations)

During the course of implementing a working CMMN engine based on CMMN specification version 1.0, a number of specification issues were identified. This section lists the issues that popped up and explains how the current implementation of the edoras one CMMN engine deals with it.

1.1.1. ManualActivationRule

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.

1.1.2. Sentry Evaluation

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:

the plan item has no entry sentry. In this case it will immediately trigger (as part of the same event processing cycle that created it).
the plan item has at least one entry sentry that triggers (logical OR among multiple sentries).

An individual sentry triggers under the following conditions:

it has no condition (expression) and no on-parts.
it has a condition (expression) and no on-parts, and the condition evaluates to true.
it has one or more on-parts, the on-parts fire, and there is either no condition or a condition evaluating to true.

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

if there is one on-part, it fires if the on-part item it listens to undergoes the desired transition as part of the current event processing cycle.
if there are more than one on-parts, the sentry fires if at least one of the on-parts fire and all other on-part items' last transition (possibly from an earlier event processing cycle) equal the one the on-part is configured for.

In other words, multiple on-parts of a single sentry form a logical AND. In order for the sentry to trigger, at least one of the on-parts must trigger as part of the current event processing cycle and all (!) other on-part items must have undergone the desired transition as their last transition (but not necessarily during the same event processing cycle).

Current implementation

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

The first instance of a plan item with one or more on-parts may trigger merely based on a sentry condition turning to true, provided the on-parts are satisfied. This is the default behaviour of sentries in edoras one CMMN. This type of trigger mode is called "Event deferred".

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

1.1.3. Implementing the RepetitionRule

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.

1.1.4. On-Parts and Repetition (Multiplicity)

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.

1.1.5. Triggering repeatable plan items - current implementation

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.

1.1.6. The sentryRef Dilemma

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).

1.1.7. Parent Termination of Event Listeners and Milestones

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.

1.1.8. Transitions on plan items within terminal stages

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.

1.1.9. Discretionary Items and Sentries

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.

1.1.10. Non-Blocking Tasks and Exit Sentries

Tables 5.18 and 5.29 in the CMMN 1.0 specification rule out the use of exit sentries for plan items that are non-blocking. In the current edoras one implementation, however, we allow such exit sentries. There are use-cases where it makes perfect sense to exit a plan item in a not yet started state like AVAILABLE or ENABLED, at which point the setting of the plan item’s Blocking property is not relevant (and thus should not disallow it).

1.2. CMMN Extensions

1.2.1. Custom Attributes

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:

Case (case plan model)
Stage
Process task
Service task
Human task
Case task
Milestone
User event listener
Event listener (external events)
Case file item (stored in 'caseFileItemDefinition' XML element)

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

1.2.2. Automatic repetition

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:

The manual activation rule must resolve to true
The repetition rule must resolve to true
The plan item must not have any on-parts. (If there are on-parts, the on-parts will be responsible for the creation of new plan item instances.)

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.

repetition

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:

repetition = standardCmmn

1.2.3. Plan Items and Stage Completion

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.

1.2.4. Manual Stage Auto-Completion

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.

1.2.5. Repetition of User Events and External Events (User event listener, Event listener)

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.

1.2.6. Rule Evaluation

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.

1.2.7. Cross-Stage Plan Item On-Parts

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):

crossStagePlanItemOnParts

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.

2. Developer Documentation

2.1. Integrating Custom Extension Code

There are two ways to call custom extension code from a running CMMN case:

Invoke custom code by means of a service task (by evaluating a runtime expression).
Configure a custom CmmnActionListener implementation via your project Spring configuration
Provide low-level custom implementations for plan item transitions.

The following sections describe the options in more detail:

2.1.1. Execute custom code by means of a Service Task

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.

2.1.2. Provide a custom CmmnActionListener implementation

The CMMN Spring context allows to specify one optional CmmnActionListener implementation as part of the DefaultCmmnEngine bean configuration. The CmmnActionListener exposes the two methods

void actionWillBePerformed(CmmnActionEvent cmmnActionEvent);

and

void actionPerformed(CmmnActionEvent cmmnActionEvent);

The methods will be called just before and just after the execution of a CMMN action. The types of actions for which the listeners are invoked are:

CASE_CREATION_EVENT
PLAN_ITEM_TRANSITION_EVENT
CASEFILE_ITEM_TRANSITION_EVENT
DISCRETIONARY_ITEM_PLANNING_ACTION_EVENT
MODEL_REEVALUATION_EVENT

The event types supported by the CmmnActionListener interface are high-level events. They allow to hook into top-level events of the CMMN engine - top-level events meaning external events imposed on the CMMN engine typically resulting from a user interaction or CMMN service call.

Please note that once such a top-level event is being processed, no additional top-level events will be generated as a result of the internal CMMN state update handling. This explains why there is a CASE_CREATION_EVENT but no event representing the completion (or closing) of a case. The closing of a case typically results as a consequence of a particular high-level event (like PLAN_ITEM_TRANSITION_EVENT). If you need to capture the completion (or termination) of your CMMN case, you will have to provide a custom transition handler for the COMPLETE and/or TERMINATE transitions of the CasePlanModel (see next section). Note: An alternative way to capture Case creation and completion events would be to re-configure the CmmnCaseProvider via Spring.

2.1.3. Provide custom implementations for plan item transitions

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, extending or hooking into 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:

Define a bean with name cmmnExtensions implementing interface CmmnExtensions or extending DefaultCmmnExtensions.
In your CmmnExtensions class, implement the method of you choice to return your handler implementation. E.g. implement method getOccurExtension(..) to return your implementation of an OccurHandler.
Your implementation of the handler must extend the appropriate abstract handler (e.g. the OccurHandler) and implement the generic handler method

public abstract Object handleTransition(PlanItem planItem, TransitionData transitionData,
                                        EngineListeners engineListeners,
                                        PersistenceListeners persistenceListeners);

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

the type of plan item for which to return the custom handler
an arbitrary string. The string is called extensionType and can be provided in your model as a custom property with name extensionType. (E.g. define the custom attribute (key/value pair) extensionType=MyExtension on your model element)

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.

2.2. Storing custom plan item state

Plan item run-time instances feature a map of key/value pairs of type string that can be used by modelers and extension code writers to persist custom run-time information. Custom plan item state can be stored on a plan item instance as soon as the instance is created (i.e. in state AVAILABLE). The state is kept throughout the life-cycle of the plan item. It is persisted as part of the CMMN engine run-time state.

State can be written in extension code via method setCustomState(String key, String value) on the passed plan item instance. State values can be read via getter getCustomState(String key).

By using the prefix _customState_ in variable names, custom key/values can be stored via target variable references (e.g. by service tasks or output parameter maps).

This feature is not optimized to store significant amounts of data. Please restrict its use to the storing of small strings like IDs.

2.3. Standard CMMN State Transition Implementations

The edoras one CMMN engine implementation is split into two parts:

A generic CMMN engine implmenentation
Edoras one integration code

See: Design & Implementation Notes.

The edoras one integration code is implemented per PlanItem type and CMMN transition type. The following table outlines which particular integration methods are provided for the various plan item types and transitions. The table also shows the purpose of the available edoras one implementations.

The main goal of the table is to support edoras one customer code developers in the task of implementing CMMN extensions. The table shows which standard implementations are available. Based on the table, developers of extensions can decide which hooks they want to extend or override.

Empty cells in the table mean that there is no edoras one implementation needed. There is code executed for the cell (transition and plan item type) within the CMMN state model, however, there is no need to take an action on edoras one Work Items.

CasePlanModel

Stage

HumanTask

ProcessTask (BPMN)

ProcessTask (Service task)

CaseTask

Milestone

UserEventListener

create

Creates and starts a Case Work Item for the CMMN case represented by the CasePlanModel.

Updates the clientRef field of the task plan item.

enable

manualStart

Starts the HumanTask (see 'start').

Starts the BPMN process (see 'start').

Executes the service task (see 'start')

Starts the CaseTask (see 'start').

start

Creates and starts the Task Work Item referenced by the HumanTask. The Task is based on an AdHoc Task Definition. AdHoc Task Definitions for HumanTasks are created during deployment of the CMMN Case model.

Creates and starts a Process Work Item.

Executes the service task

Creates and starts a new CMMN StateModel for the Case referenced by the CaseTask. This leads to 'create' of the CaseTask’s CasePlanModel.

occur

complete

Completes the Case Work Item (archives the case).

Collects output parameters from the completed task and stores them on the case.

Collects output parameters from the completed process and stores them on the case.

Collects output parameters from the completed case task and stores them on the case.

exit

Sets the sub-state of the HumanTask work object to INTERRUPTED.

Cancels the process.

Terminates the case represented by the CaseTask.

disable

re-enable

fault

reactivate

terminate

Completes the Case Work Item (archives the case).

Same as for 'exit'

Case auto-completion handling

After having applied an external event to a StateModel (like after applying a state transition), a StateModel’s auto-completion is evaluated. If a StateModel completes due to auto-completion (or otherwise is considered exited/terminated), and if the StateModel represents a CaseTask, then a suitable transition (complete, exit or terminate) is triggered in the parent Case for the CaseTask that was just completed/exited/terminated.

2.4. CMMN Service API

The standard edoras one Spring configuration contains a bean named cmmnService. The bean exposes methods that allow client projects to invoke actions on CMMN case instances.

2.4.1. Calls invoking state change

Re-evaluate a case state model

void handleStateUpdate(WorkObjectId caseId, TransitionData transitionData);

This method re-evaluates the model, evaluating all relevant sentries and other expressions. Any necessary state changes resulting from expressions are applied to the model. See parameter section for details on method parameters.

Invoke a plan item transition on a CMMN case instance

void handlePlanItemTransition(WorkObjectId caseId, String planItemId, PlanItemTransition planItemTransition, TransitionData transitionData);

This method applies the passed plan item transition to the selected plan item and re-evaluates the model. See Common CMMN service call parameters for details on method parameters.

Invoke a case file item transition on a CMMN case instance

void handleCaseFileItemTransition(WorkObjectId caseId, String caseFileItemId, CaseFileItemTransition caseFileItemTransition, TransitionData transitionData);

This method applies the passed case file item transition to the selected case file item item and re-evaluates the model. See Common CMMN service call parameters for details on method parameters.

Invoke a discretionary item planning action on a CMMN case instance

void handleDiscretionaryItemPlanning(WorkObjectId caseId, String discretionaryItemId, TransitionData transitionData);

This method 'plans' the selected discretionary item and re-evaluates the model. See Common CMMN service call parameters for details on method parameters.

2.4.2. Query CMMN run-time state

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

Get a particular plan item instance by Id

PlanItemView getPlanItem(WorkObjectId caseId, String planItemId, TransitionData transitionData);

The method returns a view object on the selected plan item. The returned PlanItemView exposes the same properties as the ones documented for _planItem in the section CMMN Expressions. See Common CMMN service call parameters for details on method parameters.

Get a list of plan items of a given type

List<PlanItemView> getPlanItems(WorkObjectId caseId, Class<? extends PlanItem> planItemType, TransitionData transitionData);

The method returns a list of PlanItemViews. Each PlanItemView exposes the same properties as the ones documented for _planItem in the section CMMN Expressions. See Common CMMN service call parameters for details on method parameters.

Note: This method is identical to the next one passing singleInstanceMode=false.

Get a list of plan items of a given type (optional "single instance mode" parameter)

List<PlanItemView> getPlanItems(WorkObjectId caseId, Class<? extends PlanItem> planItemType, boolean singleInstanceMode, TransitionData transitionData);

Query the CMMN run-time model of a case and return information on a particular plan item instance.

Map<String, Object> getPlanItemProperties(WorkObjectId caseId, planItemId, String[] properties, TransitionData transitionData);

Returns a map containing information on the selected plan item. The map contains the property name/value entries as defined by the properties parameter. See Common CMMN service call parameters for details on method parameters.

Query the CMMN run-time model of a case and return information on plan item instances.

List<Map<String, Object>> getPlanItemProperties(WorkObjectId caseId,
Class<? extends PlanItem> planItemType, boolean singleInstanceMode, String[] properties,
TransitionData transitionData);

The method returns the list of matching plan item instances. Each plan item instance in the returned list is represented by a map. Each map contains the property name/value entries as defined by the properties parameter. See Common CMMN service call parameters for details on method parameters.

Get the list of current states (milestones and stages) for a CMMN case instance

List<CurrentState> getCurrentStates(WorkObjectId caseId, TransitionData transitionData);

The method returns the list of current states of the case (states of stages and milestones). See Common CMMN service call parameters for details on method parameters.

Get the list of available actions for a CMMN case instance

List<AvailableAction> getAvailableActions(WorkObjectId caseId, TransitionData transitionData);

The method returns the list of available actions for the case. See Common CMMN service call parameters for details on method parameters.

2.4.3. Query CMMN run-time state (low-level methods)

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.

Get a particular plan item instance by Id

PlanItem getPlanItemInstance(WorkObjectId caseId, String planItemId, TransitionData transitionData);

The method returns the selected PlanItem. All public properties of the PlanItem class are accessible. See Common CMMN service call parameters for details on method parameters.

Get the plan item representing the Case Plan Model of a case

CasePlanModel getCasePlanModel(WorkObjectId caseId, TransitionData transitionData);

The method returns the selected CasePlanModel. All public properties of the CasePlanModel class are accessible. See Common CMMN service call parameters for details on method parameters.

Get a list of plan item instances of a given type

List<PlanItem> getPlanItemInstances(WorkObjectId caseId, Class<? extends PlanItem> planItemType, TransitionData transitionData);

The method returns a list of PlanItems. All public properties of the PlanItem class are accessible. See Common CMMN service call parameters for details on method parameters.

Note: This method is identical to the next one passing singleInstanceMode=false.

Get a list of plan item instances of a given type (optional "single instance mode" parameter)

List<PlanItem> getPlanItemInstances(WorkObjectId caseId, Class<? extends PlanItem> planItemType, boolean singleInstanceMode, TransitionData transitionData);

The method returns a list of PlanItems. All public properties of the PlanItem class are accessible. See Common CMMN service call parameters for details on method parameters.

Get a list of case file item instances of a given definition type

List<CaseFileItem> getCaseFileItemInstances(WorkObjectId caseId, String definitionType, TransitionData transitionData);

The method returns a list of CaseFileItem instances. All public properties of the CaseFileItem class are accessible. See Common CMMN service call parameters for details on method parameters.

2.4.4. Utility methods

Create a TransitionData object with one or more parameters

This call allows to create a TransitionData object containing one or more parameter key/value pairs. The method can be used to construct a TransitionData object that is then passed to any of the service call methods above accepting a TransitionData object.

TransitionData parameters(String key, Object value, ...);

Create a TransitionData object with one or more form data items

This call allows to create a TransitionData object containing one or more form data key/value pairs. The method can be used to construct a TransitionData object that is then passed to any of the service call methods above accepting a TransitionData object.

Note: to pass both, parameters and form data to a service method, use this helper to construct a TransitionData object. Prepend keys with the prefix _param_ to mark them as parameters.

TransitionData formData(String key, Object value, ...);

Resolve a work object Id

Best effort work object Id resolution. Typed work object Ids may get converted to a string during a front-end round-trip. This method returns the input parameter unchanged if it is of type WorkObjectId. Otherwise, if it is of type String, it tries to convert it into a WorkObjectId and returns it. Otherwise returns null.

WorkObjectId resolveId(Object workObjectId)

Resolve an external work object Id

Similar to `resolveId(Object)' with the difference that the Id passed in the input parameter is expected to be an external work object Id. The Id returned is the external Id’s internal Id.

WorkObjectId resolveExternalId(Object workObjectId)

2.4.5. Common CMMN service call parameters

Parameter `caseId`

Case IDs in the API calls below are expected to be Case Work Object Ids. Should you only have access to an external case Id, use method resolveExternalId(Object) to convert an external Id to the internal Id expected in the CMMN service call. For example:

cmmnService.handlePlanItemTransition(cmmnService.resolveExternalId(<my-external-id>), ...

Parameter `planItemId`

The planItemId parameter in the methods below is used to identify a plan item instance. You can pass any one of the following IDs (they will match in the order given):

id (the plan item model Id). For example: onehumantask1. When passing a model Id in a context where an instance Id is expected, the model Id will always map to the most recent (i.e. highest instance index) instance of the plan item.
instanceId (the plan item instance id, i.e. the model Id with the instance suffix). For example: onehumantask1~3
clientId (the plan item’s client Id, where applicable; for example a Human task’s work object Id)
clientRef (the plan item’s client reference, where applicable; for example the process reference of a Process task)

In case of ambiguities (e.g. when passing an id or clientRef to a model with multiple instances of the respective plan item), the most recent plan item instance (the one with the highest instance suffix) is selected. If the plan item is available in multiple parent stage instances, the highest plan item instance from the highest stage instance is selected.

Parameter `caseFileItemId`

The caseFileItemId parameter in the methods below is used to identify case file item instances. Pass either a case file item Id or a case file item instance Id. When passing a case file item Id, it will match the most recent (highest index) instance available.

Parameter `transitionData`

The optional TransitionData parameter in the method calls below can be used to pass form data or parameters along with the call. Simply construct a new TransitionData object (using either the empty constructor or a constructor with a parameter map) and pass it along with your call. The parameter is optional. It can be omitted or passed as null.

Use one of the service methods parameters(…) or formData(…) to construct a TransitionData object to be used in a call to one of the service methods accepting TransitionData.

Parameter `singleInstanceMode`

This can be used to limit the number of instances per plan item model element to 1. If true, zero or one instance is returned per model plan item (zero for plan items that have not been created yet, i.e. for plan items that are part of a stage that has never been started). The particular instance that is returned if there are multiple instances available for a repeatable plan item is the one with the highest instanceIntId (or index), i.e. the most recent one.

Parameter `planItemType`

This parameter is used to filter the types of plan items. Passing null maps to PlanItem which is the base class for all plan item types and thus includes all types of plan items. You can specify any of the following classes:

planItemTypes

Parameter `properties`

This parameter contains the comma-separated list of properties you’re interested in. Each property will be returned as a map entry (property name/value). The properties that are available are the same ones that are available in back-end expressions for the _planItem key word. See CMMN Expressions.

2.5. edoras one CMMN configuration properties

This section describes the System properties that are supported by the CMMN engine. They are typically added to the one.properties file.

2.5.1. Property `cmmn.planitem.exposed-model-types`

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

cmmn.planitem.exposed-model-types = <comma-separated list of model plan item types; see below>

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

planItemTypes

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

cmmn.planitem.exposed-model-types = UserEvent, ExternalEvent

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

cmmnModelIds_UserEvent
cmmnModelIds_ExternalEvent

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.

2.5.2. Property `cmmn.planitem.exposed-types`

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:

cmmn.planitem.exposed-types = <comma-separated list of model plan item types>

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

2.5.3. Property `cmmn.expose.exposed-states`

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

cmmn.planitem.exposed-states = <comma-separated list of CMMN plan item states>

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.planitem.exposed-types 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

cmmn.planitem.exposed-types = ExternalEvent
cmmn.planitem.exposed-states = AVAILABLE, ENABLED

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

_cmmn_states_ExternalEvent_AVAILABLE
_cmmn_states_ExternalEvent_ENABLED

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.

3. User Documentation

3.1. Current Feature Overview

This page describes the scope of the initial edoras one CMMN engine implementation.

Important: When running CMMN cases, make sure the case template is selected (make sure your URL starts with /case.html#…). If not, simply edit it in the browser’s address bar and reload the page.

3.1.1. Plan Items and Case File Items

Stages

A case can be structured by using stages. Stages can be nested. As of sprint 85, stages can be visuaized in the case template. See CMMN Stage and Milestone Visualization.

Plan fragments

Plan fragments can be put into a model. They allow to group individual plan items. Plan fragments do now have a run-time representation and no associated functionality other than to provide a means to enclose a bunch of plan items.

Process tasks

edoras one process tasks can be placed in a model and wired up using connectors and sentries. Input/output is handled via input and output parameter maps that can be modeled on the Process task element.

Service tasks

Service tasks can be placed into a model like any other task. When triggered, a service task evaluates a back-end expression and stores the evaluation result in the scope of the case under a variable name provided by the modeler. Service tasks are non-blocking. They immediately complete once the result is stored in the result variable.

Send mail task

A Send mail task is a special type of Service task which allows to send out e-mail notifications.

Create document task

A Create document task is a special type of Service task which creates a document instance from a document model and associates it with the case by setting the case as pareent.

Initialize variables task

An Initialize variables task is a special type of Service task which allows to initialize a set of variables on the Case Work Item (or arbitrary target Work Items).

Add comment task

An Add comment task is a special type of Service task which creates a Work Item text comment on an arbitrary target Work Item (the Case by default).

Dmn rule task

A Dmn rule task is a special type of Service task which evaluates Dmn rule and sets the outputs as a variables to the case scope.

Human tasks

Ad-hoc human tasks can be placed in a model and wired up using connectors and sentries. Input/output is handled via input and output parameter maps that can be modeled on the Human task element.

Human tasks have an init form and a work form. The work form is the main form. Where applicable, the init form is used (e.g. when starting a human task with manual activation from the case actions menu).

Case tasks

Case tasks can be placed in a model and wired up using connectors and sentries. Input/output is handled via input and output parameter maps that can be modeled on the Case task element.

Case file items

Case file items can be placed in a model. Currently only one Case file item type is supported:

DefinitionType: edorasCaseVariable. By using this case file item type, a case file item can be modeled which refers to a variable of the Case Work Object. As the variable changes, corresponding Create/Update/Delete events are triggered on the case file item.

The following features/restrictions apply: 1) Multiplicity is not supported. Please leave the corresponding field empty in the model. 2) Only top-level variables can be addressed (i.e. a simple variable name with no dots). If the variable holds an array or map, updates to the array or map will result in an update event of the modeled variable (Add Child/Remove Child events are currently not supported). 3) The Delete event is triggered in situations where the variable is set to null. An initial create of the variable (or re-set after a Delete event) will trigger a Create event. Any other update to the variable will trigger an Update event.

Milestones

Milestones can be placed in a model and configured via sentries. Reached milestones are visible in the case template. As of sprint 85, additional options for milestone visibility is available. See CMMN Stage and Milestone Visualization.

User events

Support for User events. As of sprint 84, user event listeners can be configured to be invoked more than once. See See CMMN Extensions (Repetition of User Events).

Timer events

Timer events can be modeled via the Timer event listener model element. Absolute times, relative times (durations) and repeating timers are supported by the model element. The CMMN timerStart property is currently not supported. However, it can easily be modeled by placing the Timer event listener into a stage and thus controlling the timer starting point via the stage’s life-cycle.

Generic events

External system events can be modeled by means of a generic event listener symbol. Such events can be triggered using the CMMN service.

3.1.2. HTML template

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)

3.1.3. Sentries and Events

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:

CREATE
ENABLE
MANUAL_START
START
COMPLETE
EXIT
TERMINATE

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

DISABLE
REENABLE
FAULT
REACTIVATE,

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

OCCUR

is supported for Milestones and Event listeners. The resulting state is COMPLETED.

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

CREATE
UPDATE
DELETE

3.1.4. Roles

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).

3.1.5. Discretionary Items and planning

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.

Simple optional tasks can be modeled on the basis of normal plan items, by setting the Manual start attribute and possibly using a run-time expression for the Required attribute.

3.1.6. PlanItem properties

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.

3.1.7. Custom PlanItem attributes

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.

3.1.8. Custom PlanItem state

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.

Please refer to Storing custom plan item state for more information.

3.1.9. CMMN Case migration

The run-time state of a running CMMN case can be migrated from its current model XML to a more recent model XML. This feature is able to automatically adapt the persisted state of the running case to the new model structure. The feature currently only supports structural model changes. It does not cater for changes of variable names or other changes related to the way the modeler chooses to store data on work objects.

Please refer to CMMN run-time Case migration for more information.

3.2. CMMN Stage Completion

To know and understand the circumstances under which a CMMN stage completes or terminates is an essential prerequisite for the successful modeling of CMMN cases. This section explains the logic behind stage completion and describes the modeling options that are available to configure and control the completion of a particular stage of a running model.

The following illustration summarizes stage completion logic. Detailed descriptions are presented in the sections below the picture.

3.2.1. Relevant plan item states for stage completion

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:

AVAILABLE - a plan item which has been created but has not yet triggered. A plan item is created when its parent stage is started. Note: A plan item is said to have triggered when its entry sentry has fired (or if it doesn’t have an entry sentry).
ENABLED - the state indicating that the plan item had triggered but was not automatically started (due to its "Manual Activation" property evaluating to "true").
ACTIVE - a state indicating that the plan item has been started (which is the default reaction upon triggering)
An INACTIVE state like COMPLETED, TERMINATED, DISABLED. Inactive is not an official CMMN state (in CMMN lingo it would be "terminal" or "semi-terminal) - but let’s call it like that the for the sake of this discussion.

3.2.2. Stage completion rules

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

A stage with no plan item or with all plan items in an INACTIVE state will automatically complete.

Two simple conditions that stop a stage from completing:

The stage contains one or more ACTIVE plan items.
The stage contains one or more "required" plan items in state AVAILABLE or ENABLED.

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 stage has its Auto Completion property set to "true" (black square), or else
The stage has default completion (no black square) and there are no ENABLED plan items and all AVAILABLE plan items are Completion Neutral (see below)

3.2.3. Modeling properties that control Stage completion

The following modeling properties have an impact on stage completion:

The state of the Auto Complete property of a stage (see discussion above)
The Required property of a plan item (this has an impact on the interpretation of AVAILABLE and ENABLED with respect to Auto Completion of a stage)
The Completion Neutral property of a plan item. This has an impact on the interpretation of the AVAILABLE state. A plan item with Completion Neutral "true" will not prevent a stage from completing (regardless of the stage’s Auto Completion property)

3.3. CMMN Connectors ("on-parts")

3.3.1. Connection types

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:

Same stage connections: a plan item connects via a plan item on-part with another plan item, both plan items being siblings of each other (i.e. immediate children of the same stage).
Up-hierarchy connections: a plan item connects to an element in a parent stage (one or possibly more levels up).
Down-hierarchy connections: a plan item connects to an element residing in a sub-stage (one or possibly more levels down).
Cross-hierarchy connections: a plan item connects to an element residing in a different branch of the stage hierarchy of the CMMN model (note cross-hierarchy connections are supported starting with edoras one 1.5.0.S101).

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

3.3.2. On-part resolution

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

For entry sentries:

Any to one, common run-time hierarchy policy : any instance of a repeatable plan item will trigger zero or one new instance of the target plan item (per target plan item parent stage instance) within the common run-time branch of the stage instance tree.

For exit sentries:

Any to all, common run-time hierarchy policy : any instance of a repeatable plan item will terminate all instances of the target plan item within the common run-time branch of the stage instance tree.

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):

parent stage #1
    dependent task #1
    dependent task #2
    sub-stage #1
        task #1
    sub-stage #2
        task #2
    dependent sub-stage #1
        dependent sub-task #1
parent stage #2
    dependent task #3
    sub-stage #3
    dependent sub-stage #2

The connections marked in the diagram behave as described below:

An up-hierarchy on-part from task to dependent task. Completing task #1 or task #2 will trigger a new instance of dependent task within parent stage #1.
An up-hierarchy on-part from task to dependent task via an exit sentry. Completing task #1 or task #2 will terminate all instances of dependent task within parent stage #1 (but not parent stage #2 as that stage represents a different branch of the run-time hierarchy). See also note below on the order of sentry evaluation.
An up-hierarchy on-part from task to sub-stage. Completing task #1 or task #2 will trigger a new instance of sub-stage within parent stage #1.
An up-hierarchy on-part from task to sub-stage via an exit sentry. Completing task #1 will terminate sub-stage #1 (but not sub-stage #2 as that stage represents a different branch of the run-time hierarchy). Note, by completing task, its parent (sub-stage) auto-completes. However, termination via the modeled exit sentry happens first and thus determines the final state of sub-stage #1.
A cross-hierarchy on-part from task to dependent sub-stage. Completing task #1 or task #2 will trigger a new instance of dependent sub-stage within parent stage #1.
A cross-hierarchy on-part from task to dependent sub-task. Completing task #1 or task #2 will trigger any available instance of dependent sub-task in all active instances of dependent sub-stage of parent stage #1. Note: the event has a memory effect. Subsequently starting an instance of dependent sub-stage within parent stage #1 will automatically start the dependent sub-task instance of the new stage (see section Sentry Evaluation). Note, this type of cross-hierarchy connection is described in more detail in section Stage Hierarchy - model structure vs run-time structure, below.
A cross-hierarchy on-part from task to dependent sub-stage via an exit sentry. Completing task #1 or task #2 will terminate all instances of dependent sub-stage within parent stage #1.

Sentry order: CMMN Specification version 1.0 doesn’t define the order in which entry and exit sentries are being evaluated. The behavior of the edoras one CMMN engine is such that entry sentries are evaluated first. Given an entry sentry and an exit sentry on the same plan item listening to the same condition, as the condition occurs, a new instance of the plan item is triggered and then immediately terminated.

3.3.3. Stage Hierarchy - model structure vs run-time structure

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:

Figure 1. Modeling a cross-hierarchy on-part

The model structure looks like this:

Case plan model
    parent stage
        sub-stage one
            task
        sub-stage two
            dependent task

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.

Case plan model #1
    parent stage #1
        sub-stage one #1
            task #1
        sub-stage two #1
            dependent task #1

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:

Case plan model #1
    parent stage #1
        sub-stage one #1
            task #1
        sub-stage two #1
            dependent task #1
    parent stage #2
        sub-stage one #2
            task #2
        sub-stage two #2
            dependent task #2

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:

Figure 2. Resolving a cross-hierarchy on-part

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:

Case plan model #1
    parent stage #1
        milestone #1
        sub-stage one #1
            task #1
        sub-stage two #1
            dependent task #1
    parent stage #2
        milestone #2
        sub-stage one #2
            task #2
        sub-stage two #2
            dependent task #2

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.

Figure 3. Controlling on-part resolution by means of a milestone

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.

3.4. CMMN Parameters

3.4.1. Overview

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:

Explicit parameters - parameters explicitly modeled in the CMMN model or parameters passed into the evaluation cycle (e.g. as CMMN service call parameters)
Implicit parameters - parameters automatically set up by the CMMN engine for the duration of the current evaluation cycle.

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

Form scope - form scope parameters are available during the initial plan item transition addressed by a CMMN service call
'Param' scope - param scope parameters are available during the whole evaluation cycle (CMMN service call)

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.

3.4.2. Passing parameters to a state model

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:

by passing them as query parameters in GET REST calls (with or without _param_ prefix)
by passing them as query parameters in PUT REST calls (with _param_ prefix)
by providing them as init form variables using _param_ as prefix in the form variable name
via the TransitionData object in the case of CMMN service calls.

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.

3.4.3. Passing parameters within a state model (using parameter maps)

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.

3.4.4. Accessing 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:

referring to a parameter in a sentry expression
in a service task expression
in a parameter map expression (Human tasks, Process tasks, Case tasks)

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).

3.4.5. Writing parameter values

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

by naming the parameter in a service task result variable. Prepend the target variable name of the service task with _param_ in order to store the result of the service task in the parameter map of the current evaluation cycle. (Without the prefix, the result of a service task is persisted on the target Work Item, which is the Case Work Item by default.)
by using the _param_ prefix in target variable names of input or output parameter maps of Human task, Process tasks or Case tasks.
in CMMN extension code by writing to the parameter map of the transitionData object.

3.4.6. Implicit parameters

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

_planItem
_planItems
_triggerItems
_triggerItem

See section Expression variables with special meanings for more information.

3.4.7. Store and forward of parameters and trigger items

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.

3.4.8. Examples: Recursive CaseTask invocation

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:

#{_triggerItems['onecasetask1'].workItem.result + _triggerItems['onecasetask2'].workItem.result}

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

3.5. CMMN Expressions

3.5.1. Overview

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

Entry sentry expressions
Exit sentry expressions
Expressions in task input and output parameter maps
The expression evaluated as part of a Service task
Expressions that determine the applicability of the Required, Repetition and Manual activation properties on plan items
Various properties in the Attributes pane of a CMMN model, like plan item name properties (to set the name as a result of an expression evaluation) or the 'show state' property for stages and milestones.

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.

To enable server-side debug output for expression resolution, including execution times in milliseconds, set the following log4j property: log4j.logger.com.edorasware.cmmn.one.implementation.OneEngineListeners = DEBUG

3.5.2. Expression variables with special meanings

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

_planItem - the current plan item.
_planItems - a map of all plan item instances of the running model. The map is keyed by plan item instance Id.
_triggerItems - a map of the plan item instances being responsible for the triggering of the current plan item. This map is keyed by plan item model Id (not instance Id). The value obtained from looking up a _triggerItems element is a generic object of type EventSource, wrapping either a plan item or a case file item (depending on the exact circumstances for the triggering of the plan item).
_triggerItem the trigger item if there is exactly one element in _triggerItems.
parametersMap - the map of transition data parameters. For example, use an expression like parametersMap.containsKey('foo') to test for the existence of a 'foo' parameter.
formDataMap - the map of form data items (form scope parameters).
variablesMap - this is an expression variable which, in the context of an edoras one Work Item, returns the work item’s variables map. This again can be used to test for the existence of a work item variable (e.g. myWorkItemReference.variablesMap.containsKey('foo')).

Variables of the current Work Item (if applicable), of form scope and param scope (see section CMMN Parameters) can simply be referred to by name. They do not require a special prefix.

3.5.3. `_planItem`

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:

Properties exposed by plan items

General properties

blocking - the value of the Blocking property.
casePlanModel - the plan item representing the current case plan model.
clientId - the client Id as a string; may be null (see workItem).
completionNeutral - the value of the Completion neutral property.
customState - a map (key/value pairs both of type String) of custom run-time state. See Storing custom plan item state
id - the static model Id.
index - the instance number, an integer >= 1; no gaps; the bigger the number the younger the plan item (synonym for instanceIntId).
instanceId - the instance Id (see Instance Ids).
instanceIntId - the instance number (synonym for index).
lastTransition - the last CMMN transition applied to the plan item (e.g. "COMPLETE").
manualActivation - the value of the Manual activation rule, evaluated at the moment the property is accessed.
name - the name of the plan item.
parent - the parent plan item. Returns null for the case plan model.
repetition - the value of the Repetition rule, evaluated at the moment the property is accessed.
required - the value of the Required rule, evaluated at the moment the property is accessed.
state - the CMMN state as a string (e.g. "ACTIVE").
workItem (or workObject) - a typed edoras one work object ID for the string stored under clientId; may be null.

For example, the following expression returns true if the plan item for which it is evaluated is in state ACTIVE:

#{_planItem.state == 'ACTIVE'}

Properties related to Cases started as Case tasks

ownerCasePlanModel - the Case plan model of the Case that started the current Case. Applies to all types of Case tasks (root or sub-case). Returns null for top level Cases (i.e. cases not started as a Case task).
parentCasePlanModel - the Case plan model of the parent Case. This only applies to Cases started as Case tasks of type sub-case. Returns null for any other type of Case.
topMostCasePlanModel - the Case plan model of the top most CMMN Case in the current Case hierarchy. When called for a root Case task or a top-level CMMN Case, will return its own Case plan model.
caseTask - returns true if the current Case was created from a Case task. Returns false otherwise.
subCaseTask - returns true if the current Case was created from a Case task and is of type sub-case. Returns false otherwise.
rootCaseTask - returns true if the current Case was created from a Case task and is of type root-case. Returns false otherwise.

For example, the following expression will return the value of variable myVariable of the top-most Case in the current plan item’s CMMN Case hierarchy. Note: When called within a top-level Case or a CMMN Case task of type root case, the expression shown below is equivalent to expression: #{myVariable == 'some value'}

#{_planItem.topMostCasePlanModel.workObject.myVariable == 'some value'}

Properties exposed by plan items of type Case task

targetCasePlanModel - the Case plan model of the Case started by the Case task. Returns null for Case tasks that have not yet been started or for plan items that are not of type Case task.
planItems - returns the Case task’s target Case plan model’s plan items. Returns null for Case tasks that have not yet been started or for plan items that are not of type Case task.

For example, assuming that the current plan item is of type Case task, the following expression will return true, if the state of the plan item with model Id 'modelid' within the plan item’s target Case is 'ACTIVE'. The expression will return false if the target Case doesn’t exist or if the 'modelid' plan item in the target Case is not in state 'ACTIVE'.

#{_planItem.planItems['modelid'].state == 'ACTIVE'}

Properties exposed by plan items of type Stage

These properties only make sense when called for stages (i.e. _planItem is of type Stage). These properties count child instances that are in a given state (or in any stage, in the case of childInstanceCount).

autoComplete - the boolean value of the auto-complete flag (or expression) of this stage.
availableChildrenCount - the number of available children of this stage plan item. Returns 0 when called for a non stage plan item.
activeChildrenCount - the number of active children of this stage plan item. Returns 0 when called for a non stage plan item.
childInstanceCount - the number of child instances of this stage plan item. Returns 0 when called for a non stage plan item.
completedChildrenCount - the number of completed children of this stage plan item. Returns 0 when called for a non stage plan item.
disabledChildrenCount - the number of disabled children of this stage plan item. Returns 0 when called for a non stage plan item.
enabledChildrenCount - the number of enabled children of this stage plan item. Returns 0 when called for a non stage plan item.
terminatedChildrenCount - the number of terminated children of this stage plan item. Returns 0 when called for a non stage plan item.
triggeredChildrenCount - the number of triggered children of this stage plan item (after transitions {ENABLE, START, OCCUR}. Returns 0 when called for a non stage plan item.

For example, given the stage plan item _planItem the following expression will tell you the number of child plan item instances the stage has:

#{_planItem.childInstanceCount}

Properties related to stage completion

waitingOnChildren - determines whether the stage is waiting on any child plan items for its completion. This property considers the current state of the stage’s autoComplete property. Returns false for non stage plan items.
waitingOnChildren(autoComplete) - determines whether the stage is waiting on any child plan items for its completion. The boolean result value is determined under the scenario of the boolean autoComplete value passed in the method call. Returns false for non stage plan items.

For example, assuming _planItem is a stage with autoCompletion set to false, the following expression will tell you whether the stage would complete under the scenario that autoCompletion was true:

#{not _planItem.waitingOnChildren(true)}

Properties related to sentries

The following properties are related to sentries and sentry evaluation. armed in these methods means that the plan item is ready to respond to an event, deferred means that that a suitable event has already occurred and the plan item is 'waiting' on a condition.

armed - returns true if the underlying plan item is armed. For an event listener, this means that invoking the OCCUR transition on the event listener has an effect, i.e. it triggers a transition on one or more connected plan items. For a plan item with entry sentries, armed means that the plan item is in state AVAILABLE and one or more of the plan item’s entry sentries are armed (See armedEntrySentries, below).
armedEntrySentries - the set of entry sentries (model IDs) whose condition is either missing or true. Returns an empty set for a plan item that has already been fired.
armedExitSentries - the set of exit sentries (model IDs) whose condition is either missing or true. Returns an empty set for a plan item that has not yet been created or is terminal.
deferredEntrySentries - the set of entry sentries (model IDs) whose on-parts have triggered. Returns an empty set for a plan item that has already been fired. Never includes sentries with no on-parts or trigger mode 'On event'.
deferredExitSentries - the set of exit sentries (model IDs) whose on-parts have triggered. Returns an empty set for a plan item that has not yet been created or is terminal. Never includes sentries with no on-parts or trigger mode 'On event'.

For example, an expression to test whether the condition of a specific sentry for a specific plan item is true might look like this:

#{_planItems['onehumantask1'].armedEntrySentries.contains('oneentrycriterion1')}

Count properties across the whole Case

These properties always return the total number, irrespective of the particular stage instance the current plan item is a child of.

availableCount - the number of instances of this plan item that are available.
activeCount - the number of instances of this plan item that are active.
completedCount - the number of instances of this plan item that have been completed.
disabledCount - the number of instances of this plan item that are disabled.
enabledCount - the number of instances of this plan item that are enabled.
instanceCount - the number of instances of this plan item.
terminatedCount - the number of instances of this plan item that have been terminated.
triggeredCount - the number of instances of this plan item that have been triggered (transitioned from AVAILABLE to either ACTIVE, ENABLED or OCCURRED).

For example, the following expression returns the number of plan item instances of the plan item type represented by _planItem that have been terminated:

#{_planItem.terminatedCount}

Count properties related to the parent stage instance

These properties are evaluated with respect to the stage instance the current plan item is a child of.

availableCountInStage - the number of instances of this plan item that are available with respect to the plan item’s parent stage instance.
activeCountInStage - the number of instances of this plan item that are active with respect to the plan item’s parent stage instance.
completedCountInStage - the number of instances of this plan item that have been completed as part of the plan item’s parent stage instance.
disabledCountInStage - the number of instances of this plan item that are disabled with respect to the plan item’s parent stage instance.
enabledCountInStage - the number of instances of this plan item that are enabled with respect to the plan item’s parent stage instance.
indexInStage - the instance number within the plan item’s parent stage instance, an integer >= 1; no gaps; the bigger the number the younger the plan item.
instanceCountInStage - the number of instances of this plan item with respect to the plan item’s parent stage instance.
terminatedCountInStage - the number of instances of this plan item that have been terminated with respect to the plan item’s parent stage instance.
triggeredCountInStage - the number of instances of this plan item that have been triggered (transitioned from AVAILABLE to either ACTIVE, ENABLED or OCCURRED) with respect to the plan item’s parent stage instance.

For example, the following expression returns true if _planItem is the first instance of its model element within its parent stage:

#{_planItem.indexInStage == 1}

This expression returns true if _planItem is the last instance of its type within its parent stage:

#{_planItem.indexInStage == _planItem.instanceCountInStage}

In addition to the above properties, the property planItemInternal can be used to access the underlying plan item implementation instance. This is internal API, however, and may break without notice.

3.5.4. `_planItems`

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:

#{_planItems['humantask~3']}

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

3.5.5. `_triggerItems`

Every plan item which can be modeled with an entry sentry automatically receives a standardized input parameter map named _triggerItems bound to 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:

"_triggerItems" : {
  "<A-ID>" -> "<A's trigger item (an instance of an EventSource object)>"
}

3.5.6. `_triggerItem`

The single value element of _triggerItems if _triggerItems contains exactly one element. If there are no trigger items or more than one in the _triggerItems map, this parameter is not set.

Properties exposed by trigger items

A trigger item (as returned for example by an expression like #{_triggerItems['my-human-task-model-id']}) exposes the following properties:

id - the static model Id
instanceId - the instance Id (see Instance Ids)
instanceIntId - the instance number, an integer >= 1
clientId - the client Id as a string; may be null (see workItem)
workItem (or workObject) - a typed work object ID for the string stored under clientId; may be null
state - the CMMN state as a string (e.g. "ACTIVE")
lastTransition - the last CMMN transition applied to the trigger item (e.g. "COMPLETE")
caseFileItem - a boolean value resolving to true if the trigger item represents a case file item
planItem - the plan item represented by this trigger item (if not a case file item). This planItem object exposes more properties. See Properties exposed by plan items

In addition to the above properties, the property caseFileItemInternal can be used to access the underlying case file item implementation instance (for case file item events). This is internal API, however, and may break without notice.

Please note the following when referring to trigger items:

Only the trigger items leading to the start/enable/occur of the target plan item are included in the _triggerItems map. If we have a sentry with multiple on-parts, only the on-parts whose transition triggers the enable/enable/occur event on the target plan item are included.
Trigger items are transient. They are only available as part of the current evaluation cycle (i.e. for evaluation during the model evaluation cycle during which they triggered). For task plan items: if the trigger items are needed at a later point in time, use an input parameter mapping to persist them to a desired work item.
Please also note a possible ambiguity with respect to multiple sentries: Multiple sentries represent a logical OR. If multiple such OR-ed sentries trigger simultaneously, the exact sentry passed in _triggerItems is not defined.

3.5.7. Instance Ids

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.

To refer to the most recent instance of a plan item, the instance Id suffix can be skipped (i.e. the model Id can be used).

3.5.8. Referring to Work Objects in expressions

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:

#{_planItem.workItem.exitMe}

Special care must be taken when referring to ID variables which are involved in Front-end round trips. Form variables or case variables are typically involved in front-end/back-end server round-trips and may loose their 'ID' behavior as described above (because their type may get converted to a string). For those cases, wrap your ID expression by a call to cmmnBean.resolveId(..). For the example shown above, this would result in the following expression:

#{cmmnBean.resolveId(_planItem.workItem).exitMe}

3.5.9. Referring to Work Object variables in expressions

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

#{myVariable}

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

Work Object variables may not always be initialized. Referring to a non-existing variable will result in an expression evaluation exception. There is a remedy for this though: If you want a Work Object variable reference for a non-existing variable to silently resolve to null, access the variable via the Work Object’s variablesMap. For example: #{variablesMap.myVariable}.

3.6. CMMN Stage and Milestone Visualization

3.6.1. Intro

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.

3.6.2. Visualization options for stages and milestones

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

Available, active or completed, but hidden in the case template (e.g. the CMMN model contains the stage, but it is not showed in the case template)
Available and shown in the case template, but not active at the moment
Active and shown in the case template
Completed and shown in the case template (completed means, the stage has been active and has been completed)

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

Available or reached but hidden in the case template
Available but not yet reached and shown in the case template
Reached and shown in the case template

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.

3.6.3. Visualized states

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.

3.6.4. First step implementation

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:

Show state → boolean, default is true
Show state (RT) → optional expression to define the availability of the milestone dynamically
Display order → integer

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:

Show state → boolean, default is true
Show state (RT) → optional expression to define the availability of the stage dynamically
Display order → integer

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.

3.7. CMMN Execution Modes (Non-Blocking vs Ansynchronous)

This section describes how the CMMN property isBlocking is interpreted and how it relates to synchronous (or asynchronous) execution.

In the current implementation, service tasks are carried out non-blocking. They start, carry out some task and complete, all as part of the same evaluation cycle. They don’t remain in state active.

In addition, service tasks are executed synchronously. An asynchronous mode for service tasks may become available in a future implementation.

The following table puts the meaning of the various options in relation to each other:

3.7.1. Service tasks

	Synchronous	Asynchronous
Blocking	n/a	starts, starts an asynchronous thread of execution, remains (blocks) in state active, completes upon receiving the completion event from the asynchronous execution
Non-blocking	starts, executes, completes (DEFAULT)	starts, executes (fire and forget of an asynchronous thread of execution to carry out the task), completes

Synchronous

Asynchronous

Blocking

n/a

starts, starts an asynchronous thread of execution, remains (blocks) in state active, completes upon receiving the completion event from the asynchronous execution

Non-blocking

starts, executes, completes (DEFAULT)

starts, executes (fire and forget of an asynchronous thread of execution to carry out the task), completes

3.7.2. Other tasks (e.g. Human tasks)

Non-service tasks (like Human tasks, which are asynchronous by nature) are implemented in the following way.

	Synchronous	Asynchronous
Blocking	n/a	starts, starts the task, remains (blocks) in state active, completes upon recreceiving external task completion event (DEFAULT)
Non-blocking	n/a	starts, starts the task (fire and forget), completes

Synchronous

Asynchronous

Blocking

n/a

starts, starts the task, remains (blocks) in state active, completes upon recreceiving external task completion event (DEFAULT)

Non-blocking

n/a

starts, starts the task (fire and forget), completes

3.8. CMMN run-time Case migration

This is currently an experimental feature. It is not enabled by default. To turn it on, set configuration property experimental.enable-cmmn-case-migration to true.

There may be situations where you want to alter a case’s underlying CMMN model as it is executing. This is typically the case if you have long running cases and you need to adapt to changes in business or regulatory requirements not only for new cases but also for the cases currently being executed.

The edoras one CMMN engine supports automatic migrations of running cases from an old CMMN Case model (the one a particular case is based on) to a more recent model version. Please note, that the current implementation only supports automatic migration of structural model changes. It does not cater for changes of variable names or other changes related to the way the modeler chooses to store data on work objects.

The feature is triggered via the Migrate button that is available for Case models in the edoras one Modeler Dashboard. Clicking this button will migrate all running (i.e. not archived) Cases of that model type from their current model version to the latest model version.

The Migrate function is a powerful feature which should be employed with great care. As noted above, only structural model changes are supported. An overview of supported and un-supported types of model changes follows below:

3.8.1. Supported types of model changes

adding new plan items, like adding a new Human task to a stage.
adding new stages. This includes the introduction of new parent stages to existing stages.
moving plan items, including stages.
deleting plan items.
renaming of model IDs: in most cases, the migration algorithm will successfully detect renamed model elements (including renamed model IDs) and will be able to re-map old run-time state to the new model element.

3.8.2. Types of model changes not supported

any logic in the model that deals with the storing and accessing of case data. This includes the naming of variables and how variables are being referenced in sentry expressions and other expressions.
expressions referring to model elements whose model ID has been renamed

In order to fully migrate running cases that need to adopt these types of changes, you’ll have to run custom migration code that takes all relevant model changes into consideration and alters any relevant persisted state accordingly. This obviously is easier said than done. Complex migrations of running business cases will have to be planned, executed and tested involving business analysts, modelers, developers and testers.

3.8.3. Examples of supported model changes

This section illustrates a number of basic model changes and explains how the automatic migration algorithm deals with them.

Any number of such supported model changes can be applied in a single migration. As a result, complex model transformations can be performed in a single migration step as long as you keep in mind the rules and limitations described here.

Adding a plan item

In this example, the modeler introduced a new task that is started upon the completion of an existing task. After the migration of running cases to this new model, the following two scenarios are of interest:

if Existing task has not been completed, completing the task will trigger the New task as modelled in the new model version.
if however, the Existing task had already been completed, the outcome will depend on the sentry option of New task’s entry sentry:
- If it is of type Event deferred, the new task will automatically be started by the migration. This is due to the fact that during migration, the last plan item transition of all existing plan items is re-evaluated against the newly introduced model elements.
- If it is of type On event, the New task will not be started and, for this particular model, will never be started.

Removing a plan item

In this example, the modeler will remove the Delete task and connect Existing task via a Complete event directly with Remaining task. Just picture the new model without the Delete task and a direct connection from Existing task to Remaining task.

When migrating cases to this new model, the following happens:

if Delete task is active, it will be terminated by applying the EXIT transition to it. Based on the fact that Delete task was active in this scenario, we must have had a COMPLETE transition on Existing task and as a result will have Remaining task in state ACTIVE (provided the sentry mode is Event deferred - see example above).
if Delete task has not yet been completed, completing it will simply trigger Remaining task.

Introducing new stages and moving existing stages

In this example, we will migrate a running case from this model:

to this model:

Let’s consider the migration of a running case with an active Existing stage and an active Existing task. Since the modeler decided to introduce a new parent stage for Existing stage, the migration of the running case to the new model will yield the following result, depending on the value of the new stage’s entry sentry:

if the sentry evaluates to true during case migration, the New parent stage will be active and the existing stage and task from the old run-time state will be properly moved to the new stage, carrying over their existing state (active stage, active task).
if however, the sentry evaluates to false, the New parent stage will not be started after migration. Consequently, the Existing stage and Existing task from the old run-time state can not yet exist. As a result, Existing stage and Existing task will be terminated as part of the migration step (by means of applying the EXIT transition to it). Once New parent stage triggers, a new instance of Existing stage and Existing task will be started.

4. CMMN Palette

This section describes the elements available in the CMMN modelling palette of edoras one. Each modeling element and their corresponding attributes are described in detail below.

These are the common attributes available for all model elements of an edoras one CMMN diagram.

Table 1. Common attributes
Attribute Name	Description
Name	The name of the element. This is the name displayed in the diagram. If no RT-Name is specified, this name is also used in the running case.
Name (RT)	The name of the element in a running case. If left empty, Name is used. The name can be localized. The value provided here may be a run-time expression (or it can be a static string containing one or more run-time expressions). Use the #{..} syntax for expressions. Evaluation context is the Case Work Item.
Description	The description for the element. The description is not displayed in the diagram but is exported as part of the generated CMMN XML. The description can be localized.
Custom Properties	Any properties as key/value pairs (string/string). These properties are exported as part of the CMMN XML and can be accessed at runtime. Keys are case insensitive.
Background Color	The background color of the element in the diagram.
Border Color	The border color of the element in the diagram.

Custom Properties are not available for Sentry and Connector elements. Background Color is not available for the Connector element.

There are several attributes that allow to customize the font format diagram elements. If the attributes are set at the level of the Case Plan Model, all the elements of the case will contain these attributes by default:

Table 2. Text format attributes
Attribute Name	Description
Font size	The font size of the element in the diagram.
Font weight	The font weight of the element in the diagram.
Font style	The font style of the element in the diagram.
Font Color	The font color of the element in the diagram.

These attributes can also be modified by the shortcut with a "T" icon placed in the left-bottom corner of the components. Clicking on this brings up a text format dialog where the formatting can be changed as required. The dialog includes a button to remove the style format and goes back to the default format.

4.1. Case plan model

The Case plan model represents the case itself. It is the top-most parent stage for all model elements of the case.

Table 3. Specific attributes for the Case plan model
Attribute Name	Description
Auto complete	See Auto complete attribute of Stage

Table 4. Supported custom attributes for the Case plan model
Key	Value
repetition	`standardCmmn` - set this custom attribute on the Case plan model if you want to disable the automatic repetition feature (see Automatic repetition).
triggerLimit	Some integer value >= 1. This value determines how many new instances of a model element can be triggered per parent stage and model evaluation cycle. This is used for recursion detection/prevention. If this value is missing, a default value of 1 is assumed. Background: In certain modeling scenarios you may decide to create and trigger multiple new instances of a particular model element. If your model contains such recursions, you can raise the limit here to a higher value, taking into account the maximum number of expected recursions for your case. The value provided here represents a hard limit. Reaching it will cause a run-time exception. You will have to make sure to stay below this limit by means of suitable sentry expressions.
extensionType	Optional extension type. See Provide custom implementations for plan item transitions.

4.2. Human task

A Human task represents a form based data collection / data maintenance activity performed by a Case worker. When started, a Human task will create an edoras one Task Work Item which will act as the default container for any task data and which can be assigned to other users, and marked with a due date, priority and other attributes, just like any edoras one Task Work Item.

Table 5. Specific attributes for Human tasks
Attribute Name	Description
Model ID	A unique ID for the element. The ID is used to refer to a model element from outside of the diagram (e.g. from a CMMN Action button in a form). For convenience, this ID can be edited.
Required	Select this option to mark the element as required (exclamation mark decorator). Required plan items must reach one of the states {Completed, Terminated, Disabled} in order for their parent stage to complete.
Required (RT)	An optional run-time expression (#{..} syntax) for the Required property. If empty, the setting of the Required flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Required flag. The expression is evaluated once at the point of creation of the plan item instance (i.e at the start of the parent stage or at repetition time). Evaluation context is the Case Work Item.
Repetition	Select this option to mark the element as repeatable (fence-mark decorator). Repeatable plan items may exist more than once at run-time, each having their own life-cycle. The combination of this property, Manual activation and no entry sentry has a special meaning called Automatic repetition: As a previous instance of the plan item completes, a new instance is automatically created and set into state Enabled. Repeatable event listeners can be triggered (i.e. occur) multiple times.
Repetition (RT)	An optional run-time expression (#{..} syntax) for the Repetition property. If empty, the setting of the Repetition flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Repetition flag. The value is evaluated on demand, i.e. at the point in time a plan item’s sentry fires (leading to the creation of a new instance if evaluated to true). Evaluation context is the Work Item associated with the task, or the Case Work Item if no more specific Work Item is available. [#repetitionSyntax] [NOTE] A special variable naming syntax exists to store the result of a repeatable plan item (to prevent one plan item instance from overwriting the result of an earlier plan item instance). This works as follows: if you add the suffix '[]' to a variable name (e.g. to the result variable of a Service Task or to an output parameter variable of a Human task), the parameter will be stored on the target Work Object in a map keyed by the plan item’s instance Id (the name of the map being the string before the '[]' suffix).
Manual activation	Select this option to mark the element to have manual activation (right arrow 'play' decorator). Plan items with Manual activation move from state Available to state Enabled once they trigger. A plan item in state Enabled exposes an action button that allows the user to manually start the plan item.
Manual activation (RT)	An optional run-time expression (#{..} syntax) for the Manual activation property. If empty, the setting of the Manual activation flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Manual activation flag. The value is evaluated on demand, i.e. at the point in time a plan item is triggered (moving out of state Available). Evaluation context is the Case Work Item.
Completion neutral	Select this option to mark the element to be 'completion neutral'. The flag can be used to influence the way the plan item’s parent stage completes. Background: plan items in state Available may prevent the parent Stage (or Case) from automatically completing. By checking this property, the plan item will behave neutral with respect to the completion of the parent container.
Blocking	Set this property to mark the task as blocking. Blocking is the default behaviour where a task plan item remains active until it is moved out of its active state as work on the case progresses. An example of a typical flow of action would be: the Work Item is started and remains active until the case worker completes it or until it is completed due to some external condition. By marking a plan item as non-blocking, the plan item is started and immediately completes from the point of view of the case model. The plan item’s Work Object (e.g. the Task Work Object for a Human task), however, may remain active until a case worker decides to complete it. By setting the non-blocking property, you can effectively detach the life-cycle of a plan item and its corresponding Work Object. See [blockingModes] for more information on how the blocking property is interpreted in a running CMMN case.
Initialize form reference	The form reference referring to an edoras one form to be used as the task’s init form. The init form is only relevant for tasks with Manual activation. The init form is shown at the point the user decides to manually start the task. Form fields of the init form will be passed to the new Work Item as parameters with 'form scope'. By default, the init form fields will be persisted on the new Work Object. By using the prefix `_param_` in form field variable names, form fields can be passed on in memory without being persisted on the target Work Item (see section CMMN Parameters for details on edoras one CMMN parameters).
Work form reference	The form reference referring to an edoras one form to be used as the task’s work form.
In	An optional input parameter map. Allows to map parameters and variables onto the Human task’s Work Item as it is started. See section CMMN Parameters.
Out	An optional output parameter map. Allows to map parameters and variables onto the original Case Work Item as the Human task’s Work Item completes. See section CMMN Parameters.
Task id	The name of the variable under which to store the new Task Work Item Id on the original Case Work Item (i.e. to let the owning Case know the Id of the started task). The name is optional and, if provided, can be a back-end expression (#{..} syntax) resolving to the name of the variable (evaluation context is the Case Work Item). If your Human task is repeatable, append the variable name with a pair of brackets ('[]'). This will store the Task Work Object Ids in a map keyed by Human task instance Ids.
Owner	Set the owner of the task by selecting an existing user statically.
Owner (RT)	Use a backend expression to evaluate the owner dynamically at runtime.
Assignee	Set the assignee of the task by selecting an existing user statically.
Assignee (RT)	Use a backend expression to evaluate the assignee dynamically at runtime.
Candidate Users	Set the candidate users of the task by selecting existing users statically.
Candidate Users (RT)	Use a backend expression to evaluate the candidate users dynamically at runtime.
Candidate Groups	Set the candidate users of the task by selecting existing groups statically.
Candidate Groups (RT)	Use a backend expression to evaluate the candidate groups dynamically at runtime.
Priority	The priority to be set on the new Task Work Item. Defaults to priority 50 if left empty.
Due date	An optional task due date.
Allowed actions	The set of allowed actions that can be performed on the Task Work Item.

Table 6. Supported custom attributes for Human tasks
Key	Value
extensionType	Optional extension type. See Provide custom implementations for plan item transitions.

4.3. Case task

A Case task represents an edoras one Case. Use this element to start a CMMN case that is available in the current edoras one App.

Table 7. Specific attributes for Case tasks
Attribute Name	Description
Model ID	A unique ID for the element. The ID is used to refer to a model element from outside of the diagram (e.g. from a CMMN Action button in a form). For convenience, this ID can be edited.
Required	Select this option to mark the element as required (exclamation mark decorator). Required plan items must reach one of the states {Completed, Terminated, Disabled} in order for their parent stage to complete.
Required (RT)	An optional run-time expression (#{..} syntax) for the Required property. If empty, the setting of the Required flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Required flag. The expression is evaluated once at the point of creation of the plan item instance (i.e at the start of the parent stage or at repetition time). Evaluation context is the Case Work Item.
Repetition	Select this option to mark the element as repeatable (fence-mark decorator). Repeatable plan items may exist more than once at run-time, each having their own life-cycle. The combination of this property, Manual activation and no entry sentry has a special meaning called Automatic repetition: As a previous instance of the plan item completes, a new instance is automatically created and set into state Enabled. Repeatable event listeners can be triggered (i.e. occur) multiple times.
Repetition (RT)	An optional run-time expression (#{..} syntax) for the Repetition property. If empty, the setting of the Repetition flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Repetition flag. The value is evaluated on demand, i.e. at the point in time a plan item’s sentry fires (leading to the creation of a new instance if evaluated to true). Evaluation context is the Work Item associated with the task, or the Case Work Item if no more specific Work Item is available. [#repetitionSyntax] [NOTE] A special variable naming syntax exists to store the result of a repeatable plan item (to prevent one plan item instance from overwriting the result of an earlier plan item instance). This works as follows: if you add the suffix '[]' to a variable name (e.g. to the result variable of a Service Task or to an output parameter variable of a Human task), the parameter will be stored on the target Work Object in a map keyed by the plan item’s instance Id (the name of the map being the string before the '[]' suffix).
Manual activation	Select this option to mark the element to have manual activation (right arrow 'play' decorator). Plan items with Manual activation move from state Available to state Enabled once they trigger. A plan item in state Enabled exposes an action button that allows the user to manually start the plan item.
Manual activation (RT)	An optional run-time expression (#{..} syntax) for the Manual activation property. If empty, the setting of the Manual activation flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Manual activation flag. The value is evaluated on demand, i.e. at the point in time a plan item is triggered (moving out of state Available). Evaluation context is the Case Work Item.
Completion neutral	Select this option to mark the element to be 'completion neutral'. The flag can be used to influence the way the plan item’s parent stage completes. Background: plan items in state Available may prevent the parent Stage (or Case) from automatically completing. By checking this property, the plan item will behave neutral with respect to the completion of the parent container.
Blocking	Set this property to mark the task as blocking. Blocking is the default behaviour where a task plan item remains active until it is moved out of its active state as work on the case progresses. An example of a typical flow of action would be: the Work Item is started and remains active until the case worker completes it or until it is completed due to some external condition. By marking a plan item as non-blocking, the plan item is started and immediately completes from the point of view of the case model. The plan item’s Work Object (e.g. the Task Work Object for a Human task), however, may remain active until a case worker decides to complete it. By setting the non-blocking property, you can effectively detach the life-cycle of a plan item and its corresponding Work Object. See [blockingModes] for more information on how the blocking property is interpreted in a running CMMN case.
Case reference	The Case model reference referring to the CMMN Case that is to start as this Case task moves to state Active.
Case reference (RT)	An optional run-time expression (#{..} syntax) that resolves to a Case reference at the time the Case task is started.
Case name	An optional RT expression for the name of the started Case Work Item. If left empty, defaults to the value of the Name attribute under Common Attributes.
Scope	Defines the hierarchy of the started Case. `Sub case` - the started Case will be a child of the current Case. Its tasks, actions and states will be visually integrated in the GUI of the current case. `Root case` - the started Case will be a top-level Case. You will have to select the started Case in the User Dashboard to work with it.
In	An optional input parameter map. Allows to map parameters and variables onto the Case task’s Work Item as it is started. See section CMMN Parameters.
Out	An optional output parameter map. Allows to map parameters and variables onto the original Case Work Item as the Case task’s Work Item completes. See section CMMN Parameters.
Case id	The name of the variable under which to store the new Case Work Item Id on the original Case Work Item (i.e. to let the owner Case know the Id of the started Case). The name is optional and, if provided, can be a back-end expression (#{..} syntax) resolving to the name of the variable (evaluation context is the original Case Work Item). If your Case task is repeatable, append the variable name with a pair of brackets ('[]'). This will store the Case Work Object Ids in a map keyed by Case task instance Ids.

Table 8. Supported custom attributes for Case tasks
Key	Value
extensionType	Optional extension type. See Provide custom implementations for plan item transitions.

4.4. Process task

A Process task represents an edoras one BPMN process. Use this element to start a BPMN process that is available in the current edoras one App.

Table 9. Specific attributes for Process tasks
Attribute Name	Description
Model ID	A unique ID for the element. The ID is used to refer to a model element from outside of the diagram (e.g. from a CMMN Action button in a form). For convenience, this ID can be edited.
Required	Select this option to mark the element as required (exclamation mark decorator). Required plan items must reach one of the states {Completed, Terminated, Disabled} in order for their parent stage to complete.
Required (RT)	An optional run-time expression (#{..} syntax) for the Required property. If empty, the setting of the Required flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Required flag. The expression is evaluated once at the point of creation of the plan item instance (i.e at the start of the parent stage or at repetition time). Evaluation context is the Case Work Item.
Repetition	Select this option to mark the element as repeatable (fence-mark decorator). Repeatable plan items may exist more than once at run-time, each having their own life-cycle. The combination of this property, Manual activation and no entry sentry has a special meaning called Automatic repetition: As a previous instance of the plan item completes, a new instance is automatically created and set into state Enabled. Repeatable event listeners can be triggered (i.e. occur) multiple times.
Repetition (RT)	An optional run-time expression (#{..} syntax) for the Repetition property. If empty, the setting of the Repetition flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Repetition flag. The value is evaluated on demand, i.e. at the point in time a plan item’s sentry fires (leading to the creation of a new instance if evaluated to true). Evaluation context is the Work Item associated with the task, or the Case Work Item if no more specific Work Item is available. [#repetitionSyntax] [NOTE] A special variable naming syntax exists to store the result of a repeatable plan item (to prevent one plan item instance from overwriting the result of an earlier plan item instance). This works as follows: if you add the suffix '[]' to a variable name (e.g. to the result variable of a Service Task or to an output parameter variable of a Human task), the parameter will be stored on the target Work Object in a map keyed by the plan item’s instance Id (the name of the map being the string before the '[]' suffix).
Manual activation	Select this option to mark the element to have manual activation (right arrow 'play' decorator). Plan items with Manual activation move from state Available to state Enabled once they trigger. A plan item in state Enabled exposes an action button that allows the user to manually start the plan item.
Manual activation (RT)	An optional run-time expression (#{..} syntax) for the Manual activation property. If empty, the setting of the Manual activation flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Manual activation flag. The value is evaluated on demand, i.e. at the point in time a plan item is triggered (moving out of state Available). Evaluation context is the Case Work Item.
Completion neutral	Select this option to mark the element to be 'completion neutral'. The flag can be used to influence the way the plan item’s parent stage completes. Background: plan items in state Available may prevent the parent Stage (or Case) from automatically completing. By checking this property, the plan item will behave neutral with respect to the completion of the parent container.
Blocking	Set this property to mark the task as blocking. Blocking is the default behaviour where a task plan item remains active until it is moved out of its active state as work on the case progresses. An example of a typical flow of action would be: the Work Item is started and remains active until the case worker completes it or until it is completed due to some external condition. By marking a plan item as non-blocking, the plan item is started and immediately completes from the point of view of the case model. The plan item’s Work Object (e.g. the Task Work Object for a Human task), however, may remain active until a case worker decides to complete it. By setting the non-blocking property, you can effectively detach the life-cycle of a plan item and its corresponding Work Object. See [blockingModes] for more information on how the blocking property is interpreted in a running CMMN case.
Process reference	The process model reference referring to the BPMN process that is to start as this Process task moves to state Active.
Process reference (RT)	An optional run-time expression (#{..} syntax) that resolves to a process reference at the time the process task is started.
Process name	An optional RT expression for the name of the started Process Work Item. If left empty, defaults to the value of the Name attribute under Common Attributes.
In	An optional input parameter map. Allows to map parameters and variables onto the Process Work Item as it is started. See section CMMN Parameters.
Out	An optional output parameter map. Allows to map parameters and variables onto the Case Work Item as the Process Work Item completes. See section CMMN Parameters.
Process id	The name of the variable under which to store the process Work Object Id on the Case Work Item (i.e. to let the Case know the Id of the started process). The name is optional and, if provided, can be a back-end expression (#{..} syntax} resolving to the name of the variable (evaluation context is the Case Work Item). If your Process task is repeatable, append the variable name with a pair of brackets ('[]'). This will store the process Work Object Ids in a map keyed by Process task instance Ids.

Table 10. Supported custom attributes for Process tasks
Key	Value
extensionType	Optional extension type. See Provide custom implementations for plan item transitions.

4.5. Service task

A Service task is a special type of task which, as it moves to state Active, evaluates a back-end expression and optionally stores its result (if any) on a Work Item.

Table 11. Specific attributes for Service tasks
Attribute Name	Description
Model ID	A unique ID for the element. The ID is used to refer to a model element from outside of the diagram (e.g. from a CMMN Action button in a form). For convenience, this ID can be edited.
Required	Select this option to mark the element as required (exclamation mark decorator). Required plan items must reach one of the states {Completed, Terminated, Disabled} in order for their parent stage to complete.
Required (RT)	An optional run-time expression (#{..} syntax) for the Required property. If empty, the setting of the Required flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Required flag. The expression is evaluated once at the point of creation of the plan item instance (i.e at the start of the parent stage or at repetition time). Evaluation context is the Case Work Item.
Repetition	Select this option to mark the element as repeatable (fence-mark decorator). Repeatable plan items may exist more than once at run-time, each having their own life-cycle. The combination of this property, Manual activation and no entry sentry has a special meaning called Automatic repetition: As a previous instance of the plan item completes, a new instance is automatically created and set into state Enabled. Repeatable event listeners can be triggered (i.e. occur) multiple times.
Repetition (RT)	An optional run-time expression (#{..} syntax) for the Repetition property. If empty, the setting of the Repetition flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Repetition flag. The value is evaluated on demand, i.e. at the point in time a plan item’s sentry fires (leading to the creation of a new instance if evaluated to true). Evaluation context is the Work Item associated with the task, or the Case Work Item if no more specific Work Item is available. [#repetitionSyntax] [NOTE] A special variable naming syntax exists to store the result of a repeatable plan item (to prevent one plan item instance from overwriting the result of an earlier plan item instance). This works as follows: if you add the suffix '[]' to a variable name (e.g. to the result variable of a Service Task or to an output parameter variable of a Human task), the parameter will be stored on the target Work Object in a map keyed by the plan item’s instance Id (the name of the map being the string before the '[]' suffix).
Manual activation	Select this option to mark the element to have manual activation (right arrow 'play' decorator). Plan items with Manual activation move from state Available to state Enabled once they trigger. A plan item in state Enabled exposes an action button that allows the user to manually start the plan item.
Manual activation (RT)	An optional run-time expression (#{..} syntax) for the Manual activation property. If empty, the setting of the Manual activation flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Manual activation flag. The value is evaluated on demand, i.e. at the point in time a plan item is triggered (moving out of state Available). Evaluation context is the Case Work Item.
Completion neutral	Select this option to mark the element to be 'completion neutral'. The flag can be used to influence the way the plan item’s parent stage completes. Background: plan items in state Available may prevent the parent Stage (or Case) from automatically completing. By checking this property, the plan item will behave neutral with respect to the completion of the parent container.
Expression	A back-end expression (#{..} syntax) or static text mixed with any number of embedded back-end expressions. The expression is evaluated as the Service task becomes Active. Evaluation context is the Case Work Item.
Result variable	The name of the variable under which to store the result of the expression evaluation. The name can be a back-end expression (resolving to the name of the variable). By default, the variable is stored on the Case Work Item. Use the `_param_` prefix in the variable name to store the result in memory for the duration of the current model evaluation cycle (see sections CMMN Parameters and CMMN Expressions).

Table 12. Supported custom attributes for Service tasks
Key	Value
extensionType	Optional extension type. See Provide custom implementations for plan item transitions.

4.6. Send mail task

A Send mail task is a special type of service task which allows to send out e-mail notifications.

Table 13. Specific attributes for Send mail tasks
Attribute Name	Description
Model ID	A unique ID for the element. The ID is used to refer to a model element from outside of the diagram (e.g. from a CMMN Action button in a form). For convenience, this ID can be edited.
Required	Select this option to mark the element as required (exclamation mark decorator). Required plan items must reach one of the states {Completed, Terminated, Disabled} in order for their parent stage to complete.
Required (RT)	An optional run-time expression (#{..} syntax) for the Required property. If empty, the setting of the Required flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Required flag. The expression is evaluated once at the point of creation of the plan item instance (i.e at the start of the parent stage or at repetition time). Evaluation context is the Case Work Item.
Repetition	Select this option to mark the element as repeatable (fence-mark decorator). Repeatable plan items may exist more than once at run-time, each having their own life-cycle. The combination of this property, Manual activation and no entry sentry has a special meaning called Automatic repetition: As a previous instance of the plan item completes, a new instance is automatically created and set into state Enabled. Repeatable event listeners can be triggered (i.e. occur) multiple times.
Repetition (RT)	An optional run-time expression (#{..} syntax) for the Repetition property. If empty, the setting of the Repetition flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Repetition flag. The value is evaluated on demand, i.e. at the point in time a plan item’s sentry fires (leading to the creation of a new instance if evaluated to true). Evaluation context is the Work Item associated with the task, or the Case Work Item if no more specific Work Item is available. [#repetitionSyntax] [NOTE] A special variable naming syntax exists to store the result of a repeatable plan item (to prevent one plan item instance from overwriting the result of an earlier plan item instance). This works as follows: if you add the suffix '[]' to a variable name (e.g. to the result variable of a Service Task or to an output parameter variable of a Human task), the parameter will be stored on the target Work Object in a map keyed by the plan item’s instance Id (the name of the map being the string before the '[]' suffix).
Manual activation	Select this option to mark the element to have manual activation (right arrow 'play' decorator). Plan items with Manual activation move from state Available to state Enabled once they trigger. A plan item in state Enabled exposes an action button that allows the user to manually start the plan item.
Manual activation (RT)	An optional run-time expression (#{..} syntax) for the Manual activation property. If empty, the setting of the Manual activation flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Manual activation flag. The value is evaluated on demand, i.e. at the point in time a plan item is triggered (moving out of state Available). Evaluation context is the Case Work Item.
Completion neutral	Select this option to mark the element to be 'completion neutral'. The flag can be used to influence the way the plan item’s parent stage completes. Background: plan items in state Available may prevent the parent Stage (or Case) from automatically completing. By checking this property, the plan item will behave neutral with respect to the completion of the parent container.
Mail Model	This mail model defines rich-text templates for the mail subject and body. Backend expressions in the mail model templates will be replaced when the mail is sent. The mail model is a required runtime back end expression (the `Mail Model RT` attribute) or a literal (the `Mail Model` attribute) that defines the mail model key or its model id. In the literal case, you are able to select the mail model based on a select box which is populated with the mail models of the current app. In this case, the version of the mail model taken is the one that will be deployed next which on subsequent changes to the mail model will not be the latest mail model definition deployed. If you specify a back end expression, then this should resolve to either an email model id or email definition key (that is, a specific version of an email model). In the first case, the latest deployed version (definition) of the email model is used as template. In the latter case, the specified definition will be used, similar to selecting the literal case mentioned above.
Mail Recipient	The mail recipient is a required expression or literal that defines the email recipient (or multiple recipients). The first mail recipient can be accessed in the mail template by `${recipient}` expression.
Mail Reply-To	The mail reply-to is an optional expression that specify an explicit reply address. If no reply address is defined then the global system default will be used (which will vary from installation to installation)
Mail CC	Specify one or multiple CC recipients using literals or backend expressions. This attribute is optional
Mail Bcc	Specify one or multiple BCC recipients using literals or backend expressions. This attribute is optional
Mail Priority	An optional expression or literal that specifies the mail priority (usually an integer in the range 1 - 5)
Mail Headers	Specify additional mail headers. They will be applied before the message is sent
Attachments ids	The list of documents sent by the email. The documents can be referenced by its id or a backend expression.

Table 14. Supported custom attributes for Send mail tasks
Key	Value
extensionType	Optional extension type. See Provide custom implementations for plan item transitions.

4.7. Create document task

A Create document task is a special type of Service task which creates a document instance from a document model and associates it with the case by setting the case as parent.

Table 15. Specific attributes for Create document tasks
Attribute Name	Description
Model ID	A unique ID for the element. The ID is used to refer to a model element from outside of the diagram (e.g. from a CMMN Action button in a form). For convenience, this ID can be edited.
Required	Select this option to mark the element as required (exclamation mark decorator). Required plan items must reach one of the states {Completed, Terminated, Disabled} in order for their parent stage to complete.
Required (RT)	An optional run-time expression (#{..} syntax) for the Required property. If empty, the setting of the Required flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Required flag. The expression is evaluated once at the point of creation of the plan item instance (i.e at the start of the parent stage or at repetition time). Evaluation context is the Case Work Item.
Repetition	Select this option to mark the element as repeatable (fence-mark decorator). Repeatable plan items may exist more than once at run-time, each having their own life-cycle. The combination of this property, Manual activation and no entry sentry has a special meaning called Automatic repetition: As a previous instance of the plan item completes, a new instance is automatically created and set into state Enabled. Repeatable event listeners can be triggered (i.e. occur) multiple times.
Repetition (RT)	An optional run-time expression (#{..} syntax) for the Repetition property. If empty, the setting of the Repetition flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Repetition flag. The value is evaluated on demand, i.e. at the point in time a plan item’s sentry fires (leading to the creation of a new instance if evaluated to true). Evaluation context is the Work Item associated with the task, or the Case Work Item if no more specific Work Item is available. [#repetitionSyntax] [NOTE] A special variable naming syntax exists to store the result of a repeatable plan item (to prevent one plan item instance from overwriting the result of an earlier plan item instance). This works as follows: if you add the suffix '[]' to a variable name (e.g. to the result variable of a Service Task or to an output parameter variable of a Human task), the parameter will be stored on the target Work Object in a map keyed by the plan item’s instance Id (the name of the map being the string before the '[]' suffix).
Manual activation	Select this option to mark the element to have manual activation (right arrow 'play' decorator). Plan items with Manual activation move from state Available to state Enabled once they trigger. A plan item in state Enabled exposes an action button that allows the user to manually start the plan item.
Manual activation (RT)	An optional run-time expression (#{..} syntax) for the Manual activation property. If empty, the setting of the Manual activation flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Manual activation flag. The value is evaluated on demand, i.e. at the point in time a plan item is triggered (moving out of state Available). Evaluation context is the Case Work Item.
Completion neutral	Select this option to mark the element to be 'completion neutral'. The flag can be used to influence the way the plan item’s parent stage completes. Background: plan items in state Available may prevent the parent Stage (or Case) from automatically completing. By checking this property, the plan item will behave neutral with respect to the completion of the parent container.
Document Model	Select a document model for the new document to be created.
Document Model (RT)	An optional run-time expression (#{..} syntax) that resolves to a document model key.
Document Id variable name	Specify an optional variable name under which the Id of the newly created document instance will be stored on the case.
Document name	The name of the document to be created within the case. The name may contain expressions.

Table 16. Supported custom attributes for Create document tasks
Key	Value
extensionType	Optional extension type. See Provide custom implementations for plan item transitions.

4.8. Initialize variables task

An Initialize variables task is a special type of Service task which allows to initialize a set of variables on the Case Work Item (or arbitrary target Work Items).

This task is modeled after the Initialize variables task for BPMN process models and works the same way except that the default target Work Object is not the Process but the current CMMN Case. The CMMN specific variable naming features (the _param_ and _customState_ prefixes and the [] suffix) are not supported at this time. Please use a basic Service task to update such values.

Table 17. Specific attributes for Initialize variables tasks
Attribute Name	Description
Model ID	A unique ID for the element. The ID is used to refer to a model element from outside of the diagram (e.g. from a CMMN Action button in a form). For convenience, this ID can be edited.
Required	Select this option to mark the element as required (exclamation mark decorator). Required plan items must reach one of the states {Completed, Terminated, Disabled} in order for their parent stage to complete.
Required (RT)	An optional run-time expression (#{..} syntax) for the Required property. If empty, the setting of the Required flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Required flag. The expression is evaluated once at the point of creation of the plan item instance (i.e at the start of the parent stage or at repetition time). Evaluation context is the Case Work Item.
Repetition	Select this option to mark the element as repeatable (fence-mark decorator). Repeatable plan items may exist more than once at run-time, each having their own life-cycle. The combination of this property, Manual activation and no entry sentry has a special meaning called Automatic repetition: As a previous instance of the plan item completes, a new instance is automatically created and set into state Enabled. Repeatable event listeners can be triggered (i.e. occur) multiple times.
Repetition (RT)	An optional run-time expression (#{..} syntax) for the Repetition property. If empty, the setting of the Repetition flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Repetition flag. The value is evaluated on demand, i.e. at the point in time a plan item’s sentry fires (leading to the creation of a new instance if evaluated to true). Evaluation context is the Work Item associated with the task, or the Case Work Item if no more specific Work Item is available. [#repetitionSyntax] [NOTE] A special variable naming syntax exists to store the result of a repeatable plan item (to prevent one plan item instance from overwriting the result of an earlier plan item instance). This works as follows: if you add the suffix '[]' to a variable name (e.g. to the result variable of a Service Task or to an output parameter variable of a Human task), the parameter will be stored on the target Work Object in a map keyed by the plan item’s instance Id (the name of the map being the string before the '[]' suffix).
Manual activation	Select this option to mark the element to have manual activation (right arrow 'play' decorator). Plan items with Manual activation move from state Available to state Enabled once they trigger. A plan item in state Enabled exposes an action button that allows the user to manually start the plan item.
Manual activation (RT)	An optional run-time expression (#{..} syntax) for the Manual activation property. If empty, the setting of the Manual activation flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Manual activation flag. The value is evaluated on demand, i.e. at the point in time a plan item is triggered (moving out of state Available). Evaluation context is the Case Work Item.
Completion neutral	Select this option to mark the element to be 'completion neutral'. The flag can be used to influence the way the plan item’s parent stage completes. Background: plan items in state Available may prevent the parent Stage (or Case) from automatically completing. By checking this property, the plan item will behave neutral with respect to the completion of the parent container.
Init variables	Define the list of variable initializations here. Each line in this property editor will initialize one variable. The `Target` column can be empty (in which case the target is the current Case Work Item; the constants `root`, `parent` are supported in addition to any target expressed by means of a back-end expression). The columns `Variable name` and `Initial value` define the variable’s name and value respectively. Expressions (using the #{..} syntax) are supported in all three columns.
Overwrite if existing	If set to true, the values of already defined variables will be overwritten. Otherwise, already initialized variables are skipped.

Table 18. Supported custom attributes for Initialize variables tasks
Key	Value
extensionType	Optional extension type. See Provide custom implementations for plan item transitions.

4.9. Add comment task

An Add comment task is a special type of Service task which creates a Work Item text comment on an arbitrary target Work Item (the Case by default).

Table 19. Specific attributes for Add comment tasks
Attribute Name	Description
Model ID	A unique ID for the element. The ID is used to refer to a model element from outside of the diagram (e.g. from a CMMN Action button in a form). For convenience, this ID can be edited.
Required	Select this option to mark the element as required (exclamation mark decorator). Required plan items must reach one of the states {Completed, Terminated, Disabled} in order for their parent stage to complete.
Required (RT)	An optional run-time expression (#{..} syntax) for the Required property. If empty, the setting of the Required flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Required flag. The expression is evaluated once at the point of creation of the plan item instance (i.e at the start of the parent stage or at repetition time). Evaluation context is the Case Work Item.
Repetition	Select this option to mark the element as repeatable (fence-mark decorator). Repeatable plan items may exist more than once at run-time, each having their own life-cycle. The combination of this property, Manual activation and no entry sentry has a special meaning called Automatic repetition: As a previous instance of the plan item completes, a new instance is automatically created and set into state Enabled. Repeatable event listeners can be triggered (i.e. occur) multiple times.
Repetition (RT)	An optional run-time expression (#{..} syntax) for the Repetition property. If empty, the setting of the Repetition flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Repetition flag. The value is evaluated on demand, i.e. at the point in time a plan item’s sentry fires (leading to the creation of a new instance if evaluated to true). Evaluation context is the Work Item associated with the task, or the Case Work Item if no more specific Work Item is available. [#repetitionSyntax] [NOTE] A special variable naming syntax exists to store the result of a repeatable plan item (to prevent one plan item instance from overwriting the result of an earlier plan item instance). This works as follows: if you add the suffix '[]' to a variable name (e.g. to the result variable of a Service Task or to an output parameter variable of a Human task), the parameter will be stored on the target Work Object in a map keyed by the plan item’s instance Id (the name of the map being the string before the '[]' suffix).
Manual activation	Select this option to mark the element to have manual activation (right arrow 'play' decorator). Plan items with Manual activation move from state Available to state Enabled once they trigger. A plan item in state Enabled exposes an action button that allows the user to manually start the plan item.
Manual activation (RT)	An optional run-time expression (#{..} syntax) for the Manual activation property. If empty, the setting of the Manual activation flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Manual activation flag. The value is evaluated on demand, i.e. at the point in time a plan item is triggered (moving out of state Available). Evaluation context is the Case Work Item.
Completion neutral	Select this option to mark the element to be 'completion neutral'. The flag can be used to influence the way the plan item’s parent stage completes. Background: plan items in state Available may prevent the parent Stage (or Case) from automatically completing. By checking this property, the plan item will behave neutral with respect to the completion of the parent container.
Comment Target Object	A back-end expression that resolves to the Work Item to which the new comment should be added.
History variable name	Stores the last comment added in the given variable name. If empty the comment is added to the comment-stream.
Comment User	Allows to specify the user in whose name the comment is created. The provided value may be a back-end expression (#{..} syntax).
Comment Template	The text template for the comment. The template supports embedded back-end expressions (#{..} syntax).

Table 20. Supported custom attributes for Add comment tasks
Key	Value
extensionType	Optional extension type. See Provide custom implementations for plan item transitions.

4.10. Dmn rule task

A Dmn rule task is a special type of Service task which evaluates Dmn rule.

Table 21. Specific attributes for Dmn rule tasks
Attribute Name	Description
Model ID	A unique ID for the element. The ID is used to refer to a model element from outside of the diagram (e.g. from a CMMN Action button in a form). For convenience, this ID can be edited.
Required	Select this option to mark the element as required (exclamation mark decorator). Required plan items must reach one of the states {Completed, Terminated, Disabled} in order for their parent stage to complete.
Required (RT)	An optional run-time expression (#{..} syntax) for the Required property. If empty, the setting of the Required flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Required flag. The expression is evaluated once at the point of creation of the plan item instance (i.e at the start of the parent stage or at repetition time). Evaluation context is the Case Work Item.
Repetition	Select this option to mark the element as repeatable (fence-mark decorator). Repeatable plan items may exist more than once at run-time, each having their own life-cycle. The combination of this property, Manual activation and no entry sentry has a special meaning called Automatic repetition: As a previous instance of the plan item completes, a new instance is automatically created and set into state Enabled. Repeatable event listeners can be triggered (i.e. occur) multiple times.
Repetition (RT)	An optional run-time expression (#{..} syntax) for the Repetition property. If empty, the setting of the Repetition flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Repetition flag. The value is evaluated on demand, i.e. at the point in time a plan item’s sentry fires (leading to the creation of a new instance if evaluated to true). Evaluation context is the Work Item associated with the task, or the Case Work Item if no more specific Work Item is available. [#repetitionSyntax] [NOTE] A special variable naming syntax exists to store the result of a repeatable plan item (to prevent one plan item instance from overwriting the result of an earlier plan item instance). This works as follows: if you add the suffix '[]' to a variable name (e.g. to the result variable of a Service Task or to an output parameter variable of a Human task), the parameter will be stored on the target Work Object in a map keyed by the plan item’s instance Id (the name of the map being the string before the '[]' suffix).
Manual activation	Select this option to mark the element to have manual activation (right arrow 'play' decorator). Plan items with Manual activation move from state Available to state Enabled once they trigger. A plan item in state Enabled exposes an action button that allows the user to manually start the plan item.
Manual activation (RT)	An optional run-time expression (#{..} syntax) for the Manual activation property. If empty, the setting of the Manual activation flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Manual activation flag. The value is evaluated on demand, i.e. at the point in time a plan item is triggered (moving out of state Available). Evaluation context is the Case Work Item.
Completion neutral	Select this option to mark the element to be 'completion neutral'. The flag can be used to influence the way the plan item’s parent stage completes. Background: plan items in state Available may prevent the parent Stage (or Case) from automatically completing. By checking this property, the plan item will behave neutral with respect to the completion of the parent container.
Comment Target Object	A back-end expression that resolves to the Work Item to which the new comment should be added.
History variable name	Stores the last comment added in the given variable name. If empty the comment is added to the comment-stream.
Comment User	Allows to specify the user in whose name the comment is created. The provided value may be a back-end expression (#{..} syntax).
Comment Template	The text template for the comment. The template supports embedded back-end expressions (#{..} syntax).

Table 22. Supported custom attributes for Add comment tasks
Key	Value
extensionType	Optional extension type. See Provide custom implementations for plan item transitions.

4.11. Milestone

This element represents the CMMN Milestone plan item.

Table 23. Specific attributes for Milestones
Attribute Name	Description
Model ID	A unique ID for the element. The ID is used to refer to a model element from outside of the diagram (e.g. from a CMMN Action button in a form). For convenience, this ID can be edited.
Repetition	Select this option to mark the element as repeatable (fence-mark decorator). Repeatable plan items may exist more than once at run-time, each having their own life-cycle. The combination of this property, Manual activation and no entry sentry has a special meaning called Automatic repetition: As a previous instance of the plan item completes, a new instance is automatically created and set into state Enabled. Repeatable event listeners can be triggered (i.e. occur) multiple times.
Repetition (RT)	An optional run-time expression (#{..} syntax) for the Repetition property. If empty, the setting of the Repetition flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Repetition flag. The value is evaluated on demand, i.e. at the point in time a plan item’s sentry fires (leading to the creation of a new instance if evaluated to true). Evaluation context is the Work Item associated with the task, or the Case Work Item if no more specific Work Item is available. [#repetitionSyntax] [NOTE] A special variable naming syntax exists to store the result of a repeatable plan item (to prevent one plan item instance from overwriting the result of an earlier plan item instance). This works as follows: if you add the suffix '[]' to a variable name (e.g. to the result variable of a Service Task or to an output parameter variable of a Human task), the parameter will be stored on the target Work Object in a map keyed by the plan item’s instance Id (the name of the map being the string before the '[]' suffix).
Required	Select this option to mark the element as required (exclamation mark decorator). Required plan items must reach one of the states {Completed, Terminated, Disabled} in order for their parent stage to complete.
Required (RT)	An optional run-time expression (#{..} syntax) for the Required property. If empty, the setting of the Required flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Required flag. The expression is evaluated once at the point of creation of the plan item instance (i.e at the start of the parent stage or at repetition time). Evaluation context is the Case Work Item.
Completion neutral	Select this option to mark the element to be 'completion neutral'. The flag can be used to influence the way the plan item’s parent stage completes. Background: plan items in state Available may prevent the parent Stage (or Case) from automatically completing. By checking this property, the plan item will behave neutral with respect to the completion of the parent container.
Show state	A flag indicating whether the state of this Milestone is displayed at run-time. The standard Case template includes a status bar showing the states of Stages and Milestones. When set to true, the Milestone will be displayed in the status bar with colors reflecting its state: light gray for Available/Enabled/Terminated, dark gray for Completed (i.e. 'reached').
Show state (RT)	A back-end expression (#{..} syntax) determining the state of this flag at run-time. It overrides the value of the Show state on/off flag. Evaluation context is the Case Work Item.
Display order	An integer value (negative, zero or positive) denoting the display order of the Milestone’s state indicator relative to other elements in the status bar (see attribute Show state). The smaller the number, the more to the left.

Table 24. Supported custom attributes for Milestones
Key	Value
extensionType	Optional extension type. See Provide custom implementations for plan item transitions.

4.12. Case file item

Case file items are used to model references to external data. The following types of Case file items are supported (attribute Definition type):

edoras case variable - this type of Case file item allows to define a reference to a variable of the Case Work Item. As the Case variable is created/updated/deleted, corresponding Case file item transitions will be triggered on the Case file item.

Table 25. Specific attributes for both Case file item types
Attribute Name	Description
Model ID	A unique ID for the element. The ID is used to refer to a model element from outside of the diagram (e.g. from a CMMN Action button in a form). For convenience, this ID can be edited.
Multiplicity	Case file item multiplicity values as defined in the CMMN specification.
Definition type	Defines the type and behaviour of this Case file item.

Table 26. Specific attributes for Case file items of type `edoras case variable`
Attribute Name	Description
Variable name	The name of the Case variable for which to receive Create, Update and Delete events. Currently only top-level variable names can be mentioned here. Monitoring the state of a particular sub element (e.g. of a map or array type variable) is currently not supported.

4.13. Stage

This element represents the CMMN Stage plan item. Stages are used to structure your case into stages and sub-stages.

Table 27. Specific attributes for Stages
Attribute Name	Description
Model ID	A unique ID for the element. The ID is used to refer to a model element from outside of the diagram (e.g. from a CMMN Action button in a form). For convenience, this ID can be edited.
Required	Select this option to mark the element as required (exclamation mark decorator). Required plan items must reach one of the states {Completed, Terminated, Disabled} in order for their parent stage to complete.
Required (RT)	An optional run-time expression (#{..} syntax) for the Required property. If empty, the setting of the Required flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Required flag. The expression is evaluated once at the point of creation of the plan item instance (i.e at the start of the parent stage or at repetition time). Evaluation context is the Case Work Item.
Repetition	Select this option to mark the element as repeatable (fence-mark decorator). Repeatable plan items may exist more than once at run-time, each having their own life-cycle. The combination of this property, Manual activation and no entry sentry has a special meaning called Automatic repetition: As a previous instance of the plan item completes, a new instance is automatically created and set into state Enabled. Repeatable event listeners can be triggered (i.e. occur) multiple times.
Repetition (RT)	An optional run-time expression (#{..} syntax) for the Repetition property. If empty, the setting of the Repetition flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Repetition flag. The value is evaluated on demand, i.e. at the point in time a plan item’s sentry fires (leading to the creation of a new instance if evaluated to true). Evaluation context is the Work Item associated with the task, or the Case Work Item if no more specific Work Item is available. [#repetitionSyntax] [NOTE] A special variable naming syntax exists to store the result of a repeatable plan item (to prevent one plan item instance from overwriting the result of an earlier plan item instance). This works as follows: if you add the suffix '[]' to a variable name (e.g. to the result variable of a Service Task or to an output parameter variable of a Human task), the parameter will be stored on the target Work Object in a map keyed by the plan item’s instance Id (the name of the map being the string before the '[]' suffix).
Manual activation	Select this option to mark the element to have manual activation (right arrow 'play' decorator). Plan items with Manual activation move from state Available to state Enabled once they trigger. A plan item in state Enabled exposes an action button that allows the user to manually start the plan item.
Manual activation (RT)	An optional run-time expression (#{..} syntax) for the Manual activation property. If empty, the setting of the Manual activation flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Manual activation flag. The value is evaluated on demand, i.e. at the point in time a plan item is triggered (moving out of state Available). Evaluation context is the Case Work Item.
Completion neutral	Select this option to mark the element to be 'completion neutral'. The flag can be used to influence the way the plan item’s parent stage completes. Background: plan items in state Available may prevent the parent Stage (or Case) from automatically completing. By checking this property, the plan item will behave neutral with respect to the completion of the parent container.
Auto complete	A Stage with this option set to true will complete more eagerly, i.e. even if there are pending non-required children in states Available or Enabled. In other words: With the option set to true, a Stage will complete even if it has children in states Available or Enabled (unless they are Required). With this option set to false, a Stage will only complete if all child elements are in states {Completed, Terminated, Disabled}.
Show state	A flag indicating whether the state of this Stage is displayed at run-time. The standard Case template includes a status bar showing the states of Stages and Milestones. When set to true, the Stage will be displayed in the status bar with colors reflecting its state: light gray for Available/Enabled/Terminated, red for active, dark gray for Completed.
Show state (RT)	A back-end expression (#{..} syntax) determining the state of this flag at run-time. It overrides the value of the Show state on/off flag. Evaluation context is the Case Work Item.
Display order	An integer value (negative, zero or positive) denoting the display order of the Stage’s state indicator relative to other elements in the status bar (see attribute Show state). The smaller the number, the more to the left.

Table 28. Supported custom attributes for Stages
Key	Value
extensionType	Optional extension type. See Provide custom implementations for plan item transitions.

4.14. Plan fragment

Plan fragments can be used to group model elements. Plan fragments don’t have a run-time representation or life-cycle. They don’t have any specific attributes other than Model ID.

4.15. Entry criterion

Use this element to place a CMMN entry sentry on a suitable model element (Case plan model, Stage, Tasks).

Table 29. Specific attributes for Entry sentries
Attribute Name	Description [#triggerMode]
Trigger mode	Defines the sentry’s trigger semantics. The setting here is only relevant for sentries that are connected to other model elements (i.e sentries with one or more "on-parts"). Please refer to section Sentry Evaluation for more information on sentry evaluation logic `On event` - the sentry will only 'fire' if one or more of the on-part elements undergo the desired transition as part of the current model evaluation cycle. If the sentry has a condition, and the condition evaluates to false, the sentry won’t trigger and any transition event will be lost. `Event deferred` - the sentry is evaluated against any on-part element’s last transition. If there is a transition and a false sentry condition, the sentry does not trigger. If the condition turns to true at a later point in time, the sentry will fire based on the state of any relevant on-part element’s last transition. Note `Event deferred` is not supported for events created by Timer event listeners.
Condition	A back-end expression (#{..} syntax) resolving to a boolean value or the constants true or false. A missing expression resolves to true. Evaluation context is the Case Work Item.

4.16. Exit criterion

Use this element to place a CMMN exit sentry on a suitable model element (Case plan model, Stage, Tasks).

Table 30. Specific attributes for Exit sentries
Attribute Name	Description [#triggerMode]
Trigger mode	Defines the sentry’s trigger semantics. The setting here is only relevant for sentries that are connected to other model elements (i.e sentries with one or more "on-parts"). Please refer to section Sentry Evaluation for more information on sentry evaluation logic `On event` - the sentry will only 'fire' if one or more of the on-part elements undergo the desired transition as part of the current model evaluation cycle. If the sentry has a condition, and the condition evaluates to false, the sentry won’t trigger and any transition event will be lost. `Event deferred` - the sentry is evaluated against any on-part element’s last transition. If there is a transition and a false sentry condition, the sentry does not trigger. If the condition turns to true at a later point in time, the sentry will fire based on the state of any relevant on-part element’s last transition. Note `Event deferred` is not supported for events created by Timer event listeners.
Condition	A back-end expression (#{..} syntax) resolving to a boolean value, or the constants true or false. A missing expression resolves to true. Evaluation context is the Work Item most closely related to the sentry’s plan item (e.g. the Task Work Item for a Human task). Evaluation context for Stages and the Case plan model is the Case Work Item.

4.17. Timer event listener

This model element represents the source of a timer event. A Timer event listener in state Available will respond to a timer event as configured via the model element’s properties panel. At the point in time a Timer event listener is created (it transitions to state Available), it will start a timer in the background with a time configuration as specified by the modeler via the Timer properties dialog. Once the timer running in the background fires, the corresponding Timer event listener will trigger (it will transition to Completed).

The point in time the Timer event listener transitions to Available marks the reference point for relative timer configurations (like a duration of, for example, one month). Once a background timer triggers, its Timer event listener must be in state Availble in order to respond to the timer signal. As a consequence, by putting a Timer event listener into a Stage, you can

control the start reference point of the timer via the stage’s entry sentry configuration (the timer is initialized as the stage starts) and
cancel a timer by completing (or exiting) the stage.

Please note that trigger mode Event deferred is not supported for timer events (see [triggerMode]. If a timer fires on a sentry whose condition is false, the sentry will not trigger and the event will be lost.

Table 31. Specific attributes for Timer event listeners
Attribute Name	Description
Model ID	A unique ID for the element. The ID is used to refer to a model element from outside of the diagram (e.g. from a CMMN Action button in a form). For convenience, this ID can be edited.
Completion neutral	Select this option to mark the element to be 'completion neutral'. The flag can be used to influence the way the plan item’s parent stage completes. Background: plan items in state Available may prevent the parent Stage (or Case) from automatically completing. By checking this property, the plan item will behave neutral with respect to the completion of the parent container.

Table 32. Supported custom attributes for Timer event listeners
Key	Value
extensionType	Optional extension type. See Provide custom implementations for plan item transitions.

4.18. User event listener

This model element represents the source of a user interaction. A User event listener in state Available is rendered as an action button in the CMMN case template (under Case actions). Clicking the action button triggers an Occur transition on the even listener. There is a set of properties allowing to configure the behaviour of the action button representing the User event listener in the GUI. Please refer to section [activationAttributes].

User event listeners are smart in the sense that their GUI representation (i.e. action button) is only visible if clicking it actually has an effect in the run-time model (i.e. a sentry connected with the user event listener actually triggers the plan item it is connected with). To deactivate this smart behavior, see property visbility in the custom attributes table, below.

Table 33. Specific attributes for User event listeners
Attribute Name	Description
Model ID	A unique ID for the element. The ID is used to refer to a model element from outside of the diagram (e.g. from a CMMN Action button in a form). For convenience, this ID can be edited.
Repetition	Select this option to mark the element as repeatable (fence-mark decorator). Repeatable plan items may exist more than once at run-time, each having their own life-cycle. The combination of this property, Manual activation and no entry sentry has a special meaning called Automatic repetition: As a previous instance of the plan item completes, a new instance is automatically created and set into state Enabled. Repeatable event listeners can be triggered (i.e. occur) multiple times.
Repetition (RT)	An optional run-time expression (#{..} syntax) for the Repetition property. If empty, the setting of the Repetition flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Repetition flag. The value is evaluated on demand, i.e. at the point in time a plan item’s sentry fires (leading to the creation of a new instance if evaluated to true). Evaluation context is the Work Item associated with the task, or the Case Work Item if no more specific Work Item is available. [#repetitionSyntax] [NOTE] A special variable naming syntax exists to store the result of a repeatable plan item (to prevent one plan item instance from overwriting the result of an earlier plan item instance). This works as follows: if you add the suffix '[]' to a variable name (e.g. to the result variable of a Service Task or to an output parameter variable of a Human task), the parameter will be stored on the target Work Object in a map keyed by the plan item’s instance Id (the name of the map being the string before the '[]' suffix).
Completion neutral	Select this option to mark the element to be 'completion neutral'. The flag can be used to influence the way the plan item’s parent stage completes. Background: plan items in state Available may prevent the parent Stage (or Case) from automatically completing. By checking this property, the plan item will behave neutral with respect to the completion of the parent container.

Table 34. Supported custom attributes for User event listeners
Key	Value
visibility	`force` - set this custom attribute on the User event listener in order to disable the smart visibility behavior mentioned above. No or any other value enables the smart behavior.
extensionType	Optional extension type. See Provide custom implementations for plan item transitions.

4.19. Stage auto completion

A special type of user event listener to manually complete a stage. This element can be placed in any stage or the case plan model. It works in combination with stages that have their Auto complete property set to false. This user event listener effectively turns the stage’s Auto complete property on upon user request (by the user clicking the action button). The button is only shown if clicking it actually has the effect of completing the stage (i.e. only if the stage would complete had it its Auto complete property set to true).

Table 35. Specific attributes for Stage auto completion
Attribute Name	Description
Model ID	A unique ID for the element. The ID is used to refer to a model element from outside of the diagram (e.g. from a CMMN Action button in a form). For convenience, this ID can be edited.
Completion neutral	Select this option to mark the element to be 'completion neutral'. The flag can be used to influence the way the plan item’s parent stage completes. Background: plan items in state Available may prevent the parent Stage (or Case) from automatically completing. By checking this property, the plan item will behave neutral with respect to the completion of the parent container.

Table 36. Supported custom attributes for User event listeners
Key	Value
visibility	`force` - set this custom attribute on the element in order to disable the smart visibility behavior mentioned above. No or any other value enables the smart behavior.
extensionType	Optional extension type. See Provide custom implementations for plan item transitions.

4.20. Event listener

The Event listener model element represents the source for an external event. Event listeners usually receive an Occur plan item transition sent by a CMMN service bean call.

Table 37. Specific attributes for Event listeners
Attribute Name	Description
Model ID	A unique ID for the element. The ID is used to refer to a model element from outside of the diagram (e.g. from a CMMN Action button in a form). For convenience, this ID can be edited.
Repetition	Select this option to mark the element as repeatable (fence-mark decorator). Repeatable plan items may exist more than once at run-time, each having their own life-cycle. The combination of this property, Manual activation and no entry sentry has a special meaning called Automatic repetition: As a previous instance of the plan item completes, a new instance is automatically created and set into state Enabled. Repeatable event listeners can be triggered (i.e. occur) multiple times.
Repetition (RT)	An optional run-time expression (#{..} syntax) for the Repetition property. If empty, the setting of the Repetition flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Repetition flag. The value is evaluated on demand, i.e. at the point in time a plan item’s sentry fires (leading to the creation of a new instance if evaluated to true). Evaluation context is the Work Item associated with the task, or the Case Work Item if no more specific Work Item is available. [#repetitionSyntax] [NOTE] A special variable naming syntax exists to store the result of a repeatable plan item (to prevent one plan item instance from overwriting the result of an earlier plan item instance). This works as follows: if you add the suffix '[]' to a variable name (e.g. to the result variable of a Service Task or to an output parameter variable of a Human task), the parameter will be stored on the target Work Object in a map keyed by the plan item’s instance Id (the name of the map being the string before the '[]' suffix).
Completion neutral	Select this option to mark the element to be 'completion neutral'. The flag can be used to influence the way the plan item’s parent stage completes. Background: plan items in state Available may prevent the parent Stage (or Case) from automatically completing. By checking this property, the plan item will behave neutral with respect to the completion of the parent container.

Table 38. Supported custom attributes for Event listeners
Key	Value
extensionType	Optional extension type. See Provide custom implementations for plan item transitions.

4.21. Connector

A connector represents a plan item or case file item on-part.

Table 39. Specific attributes for Connectors
Attribute Name	Description
Standard event	When connected to a sentry, a connector exposes this property allowing to set the standard event (CMMN transition) the sentry listens for.

4.22. Activation attributes

The Activation attributes section is available to all model element types which will result in the rendering of an action button at run-time. This includes:

Tasks with Manual activation resolving to true.
Stages with Manual activation resolving to true.
User event listeners

Apart from the activation attributes listed below, the custom property availableActionHidden can be set on these model elements. If set to true, no action button will be generated in the Case Actions section for the model element. CMMN action buttons placed in forms, however, will still be shown.

Table 40. Activation attributes
Attribute Name	Description
Name	The name displayed in the action button. If empty, fall-back to attribute Name under Common attributes.
Name (RT)	The name displayed in the action button. It can be a mixed expression consisting of static text and run-time expressions like "My name is #{bunny-name}". It takes precedence over the Name property at run-time. Evaluation context is the Case Work Item.
Description	The description for the action button. Currently not used in the Case template.
Hide action if	An optional RT expression (#{..} syntax) which, when provided and resolving to true, will hide the action button.
Display order	An integer (negative, zero or positive) denoting the order of the action button relative to other action buttons in the Case actions menu of the standard Case template. Smaller numbers mean higher up in the list.
Candidate users	Allows to restrict the visibility of the action button to users included in the list provided here.
Candidate users (RT)	An expression resolving to a list of candidate users at run-time. See Candidate users, above. Evaluation context is the Case Work Item.
Candidate Groups	Allows to restrict the visibility of the action button to users that are members of the groups listed here.
Candidate groups (RT)	An expression resolving to a list of candidate groups at run-time. See Candidate groups, above. Evaluation context is the Case Work Item.

5. Basic CMMN Modeling Patterns

This section presents a number of simple CMMN modeling patterns. Each pattern is presented with its model diagram and a description of the expected behavior when running the model.

Prerequisites: to re-play the examples in this section you’ll have to be familiar with CMMN modeling to the point of creating a case model, placing and connecting plan items and configuring properties and expressions and on the plan items (model elements).

For building and running these models, make sure to have the case template enabled. I.e. make sure your URL refers to the case.html file like /case.html#/dashboard/user. If the case.html is not set, you can simply edit the URL accordingly.

5.1. Auto-starting a task

5.1.1. Use-Case

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.

5.1.2. Interaction

Start the case → this starts the task "Auto-Start"
Select the task from the "Active Work Items" list
Complete the task → this completes and archives the case

5.2. Manual-start of a task

5.2.1. Use-Case

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.

5.2.2. Interaction

Start the case → this set the task "Manual-Start" to state ENABLED.
Select the task from the "Case Actions" list.
If the task is configured with an init form, you’ll now see the init form and will be prompted to submit the form to start the task.
If the task has no init form, it immediately starts and becomes available under "Active Work Items". The case automatically navigates to the started task’s work form.

5.3. Sentry condition

5.3.1. Use-Case

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".

5.3.2. Interaction

Start the case → the task is not started (it is in state AVAILABLE).
Select the case work form and set the name of the case to "task".
This starts the task - it is now available in the "Active Work Items" list.
The name of the started task is "true", which is the result of evaluating the task’s name expression.

5.4. Sentry on-part

5.4.1. Use-Case

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.

5.4.2. Interaction

Start the case → task "A" is started.
Select task "A" from the "Active Work Items" list.
Complete the task → this starts task "B".

5.5. Sentry-OR

5.5.1. Use-Case

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".

5.5.2. Interaction

Start the case → this starts tasks "A" and "B".
Select any of the tasks from the "Active Work Items" list.
Complete the task → this starts task "A or B completes".

5.6. Sentry-AND

5.6.1. Use-Case

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.

5.6.2. Interaction

Start the case → this starts tasks "A" and "B".
Select any of the tasks from the "Active Work Items" list and complete the task.
Select the other active task from the "Active Work Items" list and complete the task.
By completing the second task, the AND-condition is fulfilled → Task "A and B complete" starts.

5.7. Starting multiple task instances by Automatic Repetition

5.7.1. Use-Case

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)

5.7.2. Interaction

Start the case → this sets the task "Manual-Repetition" to state ENABLED.
Select the task from the "Case Actions" list → this starts the task.
As the task is completed, a new instance is created and put in state ENABLED.
The new instance can be started at any time by selecting it from the "Active Work Items" list.

5.8. Starting multiple task instances using a User Event Listener

5.8.1. Use-Case

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.

5.8.2. Interaction

Start the case → this set the user event listener "Start task" to state ENABLED.
Select the user event listener from the "Case Actions" list → this triggers the user event listeners OCCUR event.
The task is started.
Due to the fact that the user event listener is repeatable, a new instance of it is created and made available in the "Case Actions" list.

5.9. Starting multiple task instances in parallel

5.9.1. Use-Case

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.

5.9.2. Interaction

Start the case → this enables the task (due to the fact that it has an empty sentry with no condition).
Select the task’s action button from the "Case Actions" menu. This starts the task.
The 'Manual start' event from the previous action triggers the on-part of the task to itself and leads to the creation and enabling of a new task instance.

5.10. Starting multiple plan item instances simultaneously

5.10.1. Use-Case

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.

5.10.2. Interaction

Start the case.
Exactly two instances of the stage are active.

5.11. Require a task N times

5.11.1. Use-Case

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:

5.11.2. Interaction

Start the case → the Human Task is available for manual activation.
Start and complete the task → a second instance of the task is available for manual activation.
Start and complete the second instance → the case completes.

5.12. Case File Item - respond to case variable updates

5.12.1. Use-Case

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.

5.12.2. Interaction

Start the case.
Select the "Edit Entity" screen (pencil icon).
Create a new case variable named "myvar".
Edit variable "myvar", setting it to a new value → task "Repeat on update" is started.
Edit variable "myvar", setting it to another value → a new instance of task "Repeat on update" is started.

5.13. Repeat plan items based on a sentry condition

5.13.1. Use-Case

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.

5.13.2. Interaction

Start the case, naming it anything but "repeat".
Rename the case to "repeat" → this triggers the task.
Rename the case to some other value.
Rename the case again to "repeat" → this triggers a second instance of the task.
…and so on.

5.14. Task planning

5.14.1. Use-Case

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).

5.14.2. Interaction

Start the case, naming it anything but "vip".
The case can be completed by clicking the "Complete case" button.
Rename the case to 'vip'.
The "Complete case" button disappears as we now have the required task (and action button) "Send Christmas card".
Rename the case to something other than "vip".
The case can again be completed by the "Complete case" button.

5.15. Milestones

5.15.1. Use-Case

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.

5.15.2. Interaction

Start the case. This starts the task. It also sets the milestone to AVAILABLE.
The AVAILABLE milestone is shown in the header area of the case view (case template).
Select the task from the "Active Work Items" list. This selects the task’s work form.
Complete the task. This triggers the OCCUR transition on the milestone.
The milestone is considered reached (COMPLETED). Its visual representation changes accordingly.

5.16. Stages and Plan Fragments

5.16.1. Use-Case

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).

5.16.2. Interaction

Start the case. This starts stage 1 which starts stage 1.1 which starts task "A".
Stage 2 has an entry sentry listening to the completion of stage 1. At this point, stage 2 is in state AVAILABLE.
Complete task "A".
This results in the completion of stage 1.1 which results in the completion of stage 1.
The completion of stage 1 in turn triggers stage 2’s entry sentry which starts stage 2.
This starts task "B".
Completing task "B" now completes stage 2 and completes (and archives) the case.

5.17. Stage with exit sentry

5.17.1. Use-Case

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.

5.17.2. Interaction

Start the case. This starts the stage which in turn starts the task.
By completing the task, the stage will be completed.
Alternatively, the user can prematurely terminate the stage by clicking "Terminate stage".
This terminates the stage which will propagate the termination to the active task.
As the stage terminates (or completes), the case is completed and archived.

5.18. Task with exit sentry

5.18.1. Use-Case

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.

5.18.2. Interaction

Start the case. This starts the stage which in turn starts the task.
By completing the task, the stage will be completed.
Alternatively, the user can prematurely terminate the stage by clicking "Terminate task".
This terminates the task which completes the stage.
As the stage completes, the case is completed and archived.

5.19. Case and Stage completion

5.19.1. Use-Case

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".

5.19.2. Interaction

Start the case. This start the human task.
Select and complete the human task.
The case does not complete at this time.

Variation with "Auto complete"

Modify the model and set "Auto complete" on the case (Case Plan Model).
Deploy the model (app) and run the case again.
Observe how the case now completes as the task is completed.

Variation with "Completion neutral" on the event listener

Modify the model and set "Auto complete" back to false.
Set the property "Completion neutral" on the user event listener to true.
Deploy the model (app) and run the case again.
Observe how the case now automatically completes as the task is completed.

5.20. User-triggered Stage completion

5.20.1. Use-Case

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).

5.20.2. Interaction

Start the case. This sets the "Complete case" Stage Auto Completion listener to state AVAILABLE. Because of this, the event listener will be available as an action button under "Case Actions".
The case is active.
Click the action button.
The case completes.