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.
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):
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 interfaceCmmnExtensions
or extendingDefaultCmmnExtensions
. -
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 nameextensionType
. (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
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' |
Same as for 'exit' |
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);
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.
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:
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:
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
todependent task
. Completingtask #1
ortask #2
will trigger a new instance ofdependent task
withinparent stage #1
. -
An up-hierarchy on-part from
task
todependent task
via an exit sentry. Completingtask #1
ortask #2
will terminate all instances ofdependent task
withinparent stage #1
(but notparent 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
tosub-stage
. Completingtask #1
ortask #2
will trigger a new instance ofsub-stage
withinparent stage #1
. -
An up-hierarchy on-part from
task
tosub-stage
via an exit sentry. Completingtask #1
will terminatesub-stage #1
(but notsub-stage #2
as that stage represents a different branch of the run-time hierarchy). Note, by completingtask
, its parent (sub-stage
) auto-completes. However, termination via the modeled exit sentry happens first and thus determines the final state ofsub-stage #1
. -
A cross-hierarchy on-part from
task
todependent sub-stage
. Completingtask #1
ortask #2
will trigger a new instance ofdependent sub-stage
withinparent stage #1
. -
A cross-hierarchy on-part from
task
todependent sub-task
. Completingtask #1
ortask #2
will trigger any available instance ofdependent sub-task
in all active instances ofdependent sub-stage
ofparent stage #1
. Note: the event has a memory effect. Subsequently starting an instance ofdependent sub-stage
withinparent stage #1
will automatically start thedependent 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
todependent sub-stage
via an exit sentry. Completingtask #1
ortask #2
will terminate all instances ofdependent sub-stage
withinparent 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:
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:
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.
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 likeparametersMap.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 forinstanceIntId
). -
instanceId
- the instance Id (see Instance Ids). -
instanceIntId
- the instance number (synonym forindex
). -
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
(orworkObject
) - 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). Returnsnull
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. Returnsnull
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
- returnstrue
if the current Case was created from a Case task. Returnsfalse
otherwise. -
subCaseTask
- returnstrue
if the current Case was created from a Case task and is of type sub-case. Returnsfalse
otherwise. -
rootCaseTask
- returnstrue
if the current Case was created from a Case task and is of type root-case. Returnsfalse
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. Returnsnull
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. Returnsnull
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. Returnsfalse
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 booleanautoComplete
value passed in the method call. Returnsfalse
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 |
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 |
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 aCOMPLETE
transition on Existing task and as a result will have Remaining task in stateACTIVE
(provided the sentry mode isEvent 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 theEXIT
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.
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:
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.
Attribute Name | Description |
---|---|
Auto complete |
See Auto complete attribute of Stage |
Key | Value |
---|---|
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.
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. |
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. |
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. [#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. |
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. |
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. |
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'. |
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). |
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. |
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.
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. |
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. |
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. [#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. |
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. |
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. |
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. |
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). |
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.
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. |
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. |
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. [#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. |
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. |
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. |
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). |
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.
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. |
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. |
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. [#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. |
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. |
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). |
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.
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. |
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. |
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. [#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. |
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. |
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 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 |
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. |
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.
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. |
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. |
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. [#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. |
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. |
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. |
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.
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. |
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. |
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. [#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. |
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. |
Init variables |
Define the list of variable initializations here. Each line in this property editor will initialize one variable. The
|
Overwrite if existing |
If set to true, the values of already defined variables will be overwritten. Otherwise, already initialized variables are skipped. |
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).
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. |
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. |
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. [#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. |
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. |
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). |
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.
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. |
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. |
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. [#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. |
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. |
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). |
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.
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. |
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. [#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. |
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. |
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. |
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.
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. |
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.
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. |
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. |
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. [#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. |
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. |
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. |
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. |
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. |
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).
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 |
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).
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 |
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.
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. |
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.
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. |
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. [#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. |
Key | Value |
---|---|
visibility |
|
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).
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. |
Key | Value |
---|---|
visibility |
|
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.
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. |
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. [#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. |
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.
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.
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".