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 (omissions, ambiguities) were identified.
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 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. 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).
Repeated triggering of plan items
Plan items can be repeatable. The first instance triggers according to the rules defined above. Subsequent instances only trigger if one or more on-parts trigger. (There is an extension in place allowing to manually trigger repeatable plan items if they are configured for manual activation.) Repeatedly triggering on merely a condition (no on-part) is not supported.
Current implementation
Our current CMMN engine implementation behaves according the 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.
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.
For simplicity and predictability we are currently considering to disable this exception. There is also a forum topic on this 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). Our implementation is based on an algorithm that distinguishes between current and past event transitions. See also "Repeated triggering of plan items" in the previous section.
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. 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.6. 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.7. 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.8. Parameters
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.
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. Manual 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 Manual Repetition extension, it is 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:
-
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. Manual repetition in combination with on-parts is redundant.
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 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 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 manual repetition may have an impact on stage auto-completion. Manually starting a plan item with manual repetition leads to the activation of the plan item. At the same time, 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 manual repetition, 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. You can avoid this by modeling your manual repetition use-case by means of a user event listener.
Manual 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:
manualRepetition = cmmnStandard
1.2.3. Event Listeners and Stage Completion
In the edoras one CMMN implementation, event listeners can be configured to be "completion neutral". If checked, the event listener will not prevent a stage from completing, meaning that such an event listener is neutral with respect to stage completion evaluation. The rationale to introduce this option is as follows:
Following the specification, a stage with an event listener 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 an event listener in the stage. By treating event listeners as neutral, as now possible by setting the Completion Neutral option on the event listener, we gain modeling flexibility in the sense that we can still use the auto-completion flag to model some other condition of a stage.
1.2.4. 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 OCCURRED transition.
1.2.5. Cross-Stage Plan Item On-Parts
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 as long as the plan item on-parts refer to plan items within the same stage hierarchy.
Plan item on-parts between plan items residing in sibling stages are currently not supported by edoras one CMMN. Such connections must be modeled using an intermediate plan item (like a milestone) residing in the parent stage of the two sibling stages in question.
Referring to plan items up-stage or down-stage, however, is possible. For example, the CMMN engine evaluates the following model correctly:
1.2.6. Parameters
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 with entries representing the plan item(s) that triggered the current plan item:
-
A single entry in this map represents a single input parameter.
-
Each parameter represents a source plan item (or case file item), namely the item of each on-part that triggered the target plan item.
-
A map entry key holds the source plan item (or case file item) model ID.
-
A map entry value holds the item’s run-time client ID (edoras Work Item ID).
This map is available to developers of plan item extensions via the TransitionData parameter. In edoras one Work Items (Human task, process task and Case task Work Items), the map is available to modelers under variable name _triggerItems.
Example:
As task B-ID is triggered (started or enabled), it will receive the following input parameter map:
"_triggerItems" : { "<A-ID>" -> "<A-ID's client ID, i.e. Work Item ID>" } |
Current limitation: 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.
In addition, please note a possible ambiguity with respect to multiple sentries: Multiple sentries represent a logical OR. If multiple such ORed sentries trigger simultaneously, the exact sentry passed in "_triggerItems" is not defined.
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).
-
Provide low-level custom implementations for plan item transitions.
The following sections describe the two 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 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 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:
-
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 handler method responding to the handler’s plan item transition. (The occur method for the OccurHandler - there is a consistent naming pattern for the handlers and their methods.)
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. 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
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 | CaseTask | Milestone | UserEventListener | |
---|---|---|---|---|---|---|---|
create |
Creates and starts a Case Work Item for the CMMN case represented by the CasePlanModel. |
||||||
enable |
|||||||
manualStart |
Starts the HumanTask (see 'start'). |
Starts the ProcessTask (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. |
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 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. |
||||
fault |
|||||||
reactivate |
|||||||
terminate |
Completes the Case Work Item. |
Terminates the case represented by the CaseTask. |
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.3. REST API
2.3.1. Available CMMN REST Calls
Plan Item Transition
/rest/cmmn/CAS/{caseClientId}/{sourcePlanItemId}/{planItemTransition}/planItemTransition (method GET)
Trigger a transition on a plan item and subsequently re-evaluate the state model.
Plan Item Transition with Form Data
/rest/cmmn/CAS/{caseClientId}/{sourcePlanItemId}/{planItemTransition}/planItemTransitionWithFormData (method PUT)
Similar to the method above, but allows to pass form data in the request body. For example, this call is used to manually start a task with an init form.
Case File Item Transition
/rest/cmmn/CAS/{caseClientId}/{caseFileItemId}/{caseFileItemTransition}/caseFileItemTransition (method GET)
Trigger a transition on a case file item and subsequently re-evaluate the state model.
Case File Item Transition with Form Data
/rest/cmmn/CAS/{caseClientId}/{caseFileItemId}/{caseFileItemTransition}/caseFileItemTransitionWithFormData (method PUT)
Similar to the method above, but allows to pass form data in the request body. For example, this call is used to manually create a case file item of type edorasDataItem.
Discretionary Item Planning
/rest/cmmn/CAS/{caseClientId}/{sourcePlanItemId}/discretionaryItemPlanning (method GET)
Plan a discretionary item (move it from the planning table into the run-time model by creating a corresponding plan item in the run-time model).
State Update
/rest/cmmn/CAS/{caseClientId}/stateUpdate (method GET)
This re-evaluates the state model (entry criteria, exit criteria, applicability rules, (auto-)completion of stages). Calling this method makes sense when you have a state change in the back-end which is used in a back-end expression in your CMMN model and you want the back-end expression to be re-evaluated.
2.3.2. Description of REST Call Parameters
{caseClientId}
The edoras case Work Object ID.
{sourcePlanItemId}
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). 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.
{planItemTransition}
The transition to apply (the names of enum PlanItemTransition)
{caseFileItemId}
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. If there exists a work object for the case file item of interest, you can also pass the edoras Work Object ID.
{caseFileItemTransition}
The transition to apply (the names of enum CaseFileItemTransition). Currently only CREATE and UPDATE are supported.
2.4. CMMN Service
The standard edoras one Spring configuration contains a bean named "cmmnService". The bean exposes methods that allow client projects (like edoras one Bootstrap based projects) to invoke actions on CMMN case instances.
The TransitionData parameter in the method calls below can be used to pass init form data along with the call. Simply construct a new TransitionData object (using either the empty constructor or the one accepting a parameter map) and pass it along with your call.
2.4.1. Available CMMN Service Calls
Invoke a plan item transition on a CMMN case instance
void handlePlanItemTransition(CaseId caseId, String planItemId, PlanItemTransition planItemTransition, TransitionData transitionData);
Invoke a case file item transition on a CMMN case instance
void handleCaseFileItemTransition(CaseId caseId, String caseFileItemId, CaseFileItemTransition caseFileItemTransition, TransitionData transitionData);
Invoke a discretionary item planning action on a CMMN case instance
void handleDiscretionaryItemPlanning(CaseId caseId, String discretionaryItemId);
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 case variables only (see Parameters, below)
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.
Human tasks
Ad-hoc human tasks can be placed in a model and wired up using connectors and sentries. Input/output is handled via case variables only (see Parameters, below).
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 file items
Case file items can be placed in a model. Currently two types of case file items are 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 Item. 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 modeler. 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.
DefinitionType: edorasDataItem. These types of case file items are represented by their own run-time edoras work item. For these case file items, an init form and a work form can be defined. New case file items can be created via the Case Actions menu (in the case of case file items that have the necessary multiplicity property).
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 UserEvents. As of sprint 84, user event listeners can be configured to be invoked more than once. See See CMMN Extensions (Repetition of User Events).
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 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
-
FAULT
-
REACTIVATE,
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
-
OCCUR
is supported for Milestones and Event listeners:
Connectors to case file items are also supported (case file item on-parts). Supported transitions:
-
CREATE
-
UPDATE
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. Parameters
The configuration of formal CMMN parameters is not supported. Information can be passed via case variables. In addition to that, we implemented a type of implicit input parameters called "trigger items". See CMMN Extensions.
3.1.6. 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.
3.1.7. 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.8. Custom PlanItem properties
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
3.2. CMMN Stage and Milestone Visualization
3.2.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.2.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.2.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.2.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.
3.3. Modeling Options
3.3.1. CasePlanModel
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.
3.3.2. Stage
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.
3.3.3. All Tasks
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.
4. Tutorial
4.1. Auto-start task
We have a case model containing a single human task. The human task is started as the case is started. Completing the task completes the case.
4.2. Manual-start of task
We have a case model containing a single human task. The human task is set to state ENABLED as the case starts. Selecting the task from the list of available actions manually starts (activates) the task.
4.2.1. 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 are prompted submit the form to start the task.
-
If the task has no init form, it immediately starts and becomes available under "Active Work Items"
4.3. Sentry condition
We have a case model containing a single human task. The numan task is started as soon as the user sets the name of the case to "task".
4.3.1. 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
4.4. Sentry on-part
We have a case model containing two human tasks. One task starts upon completion of the first task.
4.5. Sentry-OR
We have a case model containing three human tasks. Tasks "A" and "B" are started as the case is started. Completing any of the tasks starts task "A or B completes".
4.6. Sentry-AND
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 completes".
4.6.1. 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
4.7. Starting multiple task instances by Manual Repetition
We have a case model containing a single human task. Multiple task instances can be started at the user’s discretion.
4.7.1. 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 started, a new instance is created and put in state ENABLED
-
The new instance can be started at any time by clicking on it from the "Active Work Items" list
4.8. Starting multiple task instances using a User Event Listener
We have a case model containing a single human task and a user event listener. Both the user event listener and the task are repeatable. The task has a sentry and a connection (on-part) to the user event listener, listening to the OCCUR event. Clicking the user event listener starts the task.
4.8.1. Interaction
-
Start the case → this set the user event listener "Start task" to state ENABLED
-
Select 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 for clicking in the "Case Actions" list
4.8.2. Remarks
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 is goes from CREATED straight to ACTIVE. 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.
4.9. Starting multiple task instances - one at a time
We have a case model containing a single human task. The task starts as the case is started. By completing the task, a new instance of the task is created and started.
4.9.1. Interaction
-
Start the case → this starts the task (due to the fact that it has an empty sentry with no condition which immediately fires)
-
Select the task from the "Active Work Items" list and complete the task
-
This triggers the on-part of the task to itself and immediately starts a new instance of the task
4.10. Case File Item - respond to case variable updates
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.
4.10.1. 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 yet to another value → a new instance of task "Repeat on update" is started
4.11. Milestones
We have a case model containing a task and a milestone. As the task completes, the milestone is reached.
4.11.1. 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. Its visual representation changes accordingly
4.12. Stage with exit sentry
Stages can be used to model blocks of related processing or to model special phases during the life-cycle of a case. 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
4.12.1. 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
4.13. Task with exit sentry
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
4.13.1. 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
4.14. Stages and Plan Fragments
Stages can be nested to any level. They can be fitted with entry and exit sentries and connected via on-parts (connector lines). Stages have a life-cycle and a GUI representation (AVAILABLE/ACTIVE/COMPLETED). Plan Fragments are merely a means to group model elements. They don’t have a run-time representation.
4.14.1. 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
4.15. Case and Stage completion
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 or ENABLED 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. In addition, the property "Completion neutral" on event listeners can be used to help with auto 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".
4.15.1. 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 also completes as the task is completed