CMMN Documentation

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

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

The order and logic related to the evaluation of sentries of a CMMN model is not at all 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.

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). Our implementation is based on an algorithm that distinguishes between current and past event transitions.

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

Another problem in the area of the repetition property is related to the evaluation of the rule’s expression. Sectioni 7.6.4 in CMMN specification 1.0 states that the rule is evaluated at the point of instantiation of the repeatable plan item and that the value of the evaluation is maintained throughout the life-cycle of the plan item. This however can lead to an ambiguity. Consider the following setup:

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

Section 7.6.1 doesn’t take Event Listeners into consideration. In the current implementation and in contrast to the specification, Event Listeners (whether they have occurred or not) do not prevent a stage from completing. They are neutral with respect to stage completion evaluation.

Following the specification, a stage with an event listener in state Available does not complete (unless we consider the stage’s auto-complete flag). For example, if a stage contains a single event listener in state Available, the stage does not complete unless we set the stage’s auto-complete flag. In most modeling situations, this forces us set a stage to auto-completion as soon as we use an event listener in the stage. By treating event listeners as neutral, as in the current implementation, we gain modeling flexibility in the sense that we can still use (or not use) the auto-completion flag in order to model some more meaningful condition of a stage.

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. This renders DiscretionaryItems not very useful.. The current implementation of the CMMN engine does not support sentries on Discretionary Items.

Formal modeling of CMMN Parameters is not yet included in the current CMMN implementation. We left it out due to time constraints and due to the fact that the CMMN specification doesn’t support parameter mappings for HumanTasks.

As an alternative to the CMMN modeling framework for Parameters, a simple generic run-time parameter concept was implemented. This custom parameter concept does not interfere with the CMMN specification and can co-exist with any formal CMMN Parameters implementation that may follow in the future. It works as described in section Parameters on page CMMN Extensions.

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 enable CMMN extensions like the ManualRepetition extension described below. Customer extensions of the transition call-back methods can also make use of these properties to implement custom logic based on design-time properties.

The elements for which custom attributes are supported are:

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

The CMMN repetiion rule allows to create multiple instances of a given model plan item. The creation of a new instance of a plan item is controlled by sentries. Only a Sentry triggering on a plan item may lead to the creation of a new instance of the plan item.

By introducing the Manual Repetition extension, it is now possible to manually trigger the creation of a new instance of a plan item. For this to work, a plan item must be configured as follows:

If this is the case, a plan item can repeatedly be created by means of an action button under Available Actions in the case HTML template.

Manual Repetition is not only supported for plan items but also for discretionary items.

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. In the context of the Manual Repetition extension, this rule has been adjusted. The engine now evaluates the rule on demand, i.e. each time a new plan item instance may potentially be created, the rule is evaluated. This happens, for example, during the sentry evaluation loop, or as a plan item does a MANUAL_START transition.

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. This allows the modeler to create a user event button in the GUI which remains visible and can be invoked multiple times.

There is no conceptual reason to disallow plan item on-parts referring to plan items outside the sentry’s stage (as CMMN spec 1.0 does). The current implementation of the CMMN engine allows such connections. For example, the CMMN engine evaluates the following model correctly:

Every plan item which can be modeled with an entry sentry automatically receives a standardized input parameter map during run-time. The map contains key/value pairs of type String/String according to the following semantic:

This map is available to developers of plan item extensions via the TransitionData parameter. In edoras one Work Items, the map is available to modelers under variable name _triggerItems.

Example:

As task B-ID is started or enabled, it will receive the following input parameter map:

Current limitation: only the trigger items leading to the start/enable 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 event on the target plan item are included.

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. [This functionality is in planning and not yet available.]

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

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

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

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

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

The edoras case Work Object ID.

The model element ID of the item. Append #N (where N is the instance number) to address a particular plan item instance (e.g. of a repeatable plan item). The hash must be URL encoded (# = %23). If you pass a sourcePlanItemId without instance suffix, the engine will always find the instance with the highest index (i.e. the instance created most recently).

If there exists a work object for the plan item of interest, you can also pass the edoras Work Object ID.

The transition to apply (the names of enum PlanItemTransition)

The model element ID of the case file item. Append #N (where N is the instance number) to address a particular case file item instance. The hash must be URL encoded (# = %23). If there exists a work object for the case file item of interest, you can also pass the edoras Work Object ID.

The transition to apply (the names of enum CaseFileItemTransition). Currently only CREATE and UPDATE are supported.

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

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

Case File Items - For created case file items

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

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

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

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

The events

are supported on the level of the REST API and custom transition implementations (extension code) for plan items (except the case itself). There is currently no GUI support or visual feed-back available for these transitions and resulting states.

The transition

is supported for Milestones and Event listeners:

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

Support for CMMN roles is not implemented. Support for Human Task access rights with edoras one is planned.

The configuration of formal CMMN parameters is not yet supported. Information can be passed via case variables. There is an extension in planning which covers certain types of parameters. See CMMN Extensions.

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

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

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

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

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

Autocomplete - the Autocomplete property is supported for stages.

Custom properties (name/value pairs, both simple strings) are supported for the Case (casePlanModel), stages, and the three types of tasks (human, process, case).

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

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

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

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

In addition to whether a state and milestone are 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 should explicitly be modeled within the CMMN case model.

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

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

New milestone attributes:

If the available flag is true or the expression resolves to true, the milestone is rendered as an available state using isCurrentState and isCompleted both set to false. As soon as the milestone has been reached, the flags are both set to true.

New stage attributes:

If the available flag is true or the expression resolves to true, the stage is rendered as an available state using isCurrentState and isCompleted both set to false. As soon as the stage is active, isCurrentState is set to true, once the stage has been completed, the flag isCompleted is set to true as well.

As entering the visualization order might become quite cumbersome if the model contains a lot of stages and milestones, there might be an extra dialog to be reached at global model level (not on a single stage or milestone) to set the order of all stages and milestones in one single place.

The attribute should be added on the single element Case Plan Model which exists in all CMMN models exactly once. The name of the attribute is Phase visualizations and the attribute dialog is built the following way:

All stages and milestones in the case plan model appear as a single row in the dialog. Each row will have the following columns (the values are taken from the properties of each stage and milestone and saving the dialog will write them back as properties, so they can be edited directly by using this overview dialog or by editing the stage or milestone element):

By moving rows up or down, the dialog is building up the visualization order for the stages and milestones and will modify the visualization order property accordingly. This allows an overview of the visualized stages and milestones and their order in the case template.

Autocomplete

A case completes regardless of this option when there are no active children, no children waiting on a sentry, no children available for manual start, no discretionary items to plan and no un-triggered required milestones. With autocomplete enabled, there may be unplanned discretionary items and it will still complete. In addition, It will also complete if there are un-started manual activation children which are not required.

Autocomplete

A stage completes regardless of this option when there are no active children, no children waiting on a sentry, no children available for manual start, no discretionary items to plan and no un-triggered required milestones. With autocomplete enabled, there may be unplanned discretionary items and it will still complete. In addition, It will also complete if there are un-started manual activation children which are not required.

Required

When required, a stage is required to complete/exit once its entry criteria have fired (otherwise its parent stage won’t be able to complete). required is only relevant in combination with manual activation. Once started, a stage is always required to complete or exit, regardless of this option.

Manual activation

By default, a stage starts automatically once its entry criteria have fired. With manual activation evaluating to true, the stage must be manually started. The action button to start the stage becomes available as the stage’s entry criteria fire. Manual activation in combination with required has an impact on the auto-completion of the parent stage.

Repetition

With repetition evaluating to true, multiple instances of the stage can be created. A new instance is created each time its entry criteria fire. The custom property manualRepetition allows the user to create new instances by clicking an action button.

Discretionary

A discretionary stage is optional. If discretionary, the stage requires a user action to be promoted to a normal stage where it becomes subjected to the settings for manual activation, required and autocomplete. Sentries are currently not supported for discretionary items. To model an optional stage, consider using a normal stage that has manual activation and is not required.

Required

When required, a task is required to complete/exit once its entry criteria have fired (otherwise its parent stage won’t be able to complete). required is only relevant in combination with manual activation. Once started, a task is always required to complete or exit, regardless of this option.

Manual activation

By default, a task starts automatically once its entry criteria have fired. With manual activation evaluating to true, the task must be manually started. The action button to start the task becomes available as the task’s entry criteria fire. Manual activation in combination with required has an impact on the auto-completion of the parent stage.

Repetition

With repetition evaluating to true, multiple instances of the task can be created. A new instance is created each time its entry criteria fire. The custom property manualRepetition allows the user to create new instances by clicking an action button.

Discretionary

A discretionary task is optional. If discretionary, the task requires a user action to be promoted to a normal task where it becomes subjected to the settings for manual activation and required. Sentries are currently not supported for discretionary items. To model an optional task, consider using a normal task that has manual activation and is not required.

Blocking

Blocking is the default behavior. Use non-blocking if you want the task to immediately complete once it starts. Non-blocking can be used, for example, to model service tasks.

Required

When required, a milestone is required to fire in order for its parent stage to complete.

Repetition

With repetition evaluating to true, multiple instances of the milestone can be created. A new instance is created each time its entry criteria fire.