CMMN Documentation

1. Design & Implementation Notes

1.1. CMMN Specification Issues (and interpretations)

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

1.1.1. ManualActivationRule

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

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

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

1.1.2. Sentry Evaluation

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

Triggering plan items

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

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

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

An individual sentry triggers under the following conditions:

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

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

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

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

Repeated triggering of plan items

Plan items can be repeatable. The first instance triggers according to the rules defined above. Subsequent instances only trigger if one or more on-parts trigger. (There is an extension in place allowing to manually trigger repeatable plan items if they are configured for manual activation.) Repeatedly triggering on merely a condition (no on-part) is not supported.

Current implementation

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

The first instance of a plan item with one or more on-parts may trigger merely based on a sentry condition turning to true, provided the on-parts are satisfied.

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

For simplicity and predictability we are currently considering to disable this exception. There is also a forum topic on this https://forum.edorasware.com/t/cmmn-sentry-evaluation-semantics/89

1.1.3. Implementing the RepetitionRule

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

1.1.4. On-Parts and Repetition (Multiplicity)

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

1.1.5. The sentryRef Dilemma

The following is a legal diagram fragment:

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

1.1.6. Parent Termination of Event Listeners and Milestones

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

1.1.7. Discretionary Items and Sentries

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

1.2. CMMN Extensions

1.2.1. Custom Attributes

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

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

The elements for which custom attributes are supported are:

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

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

1.2.2. Automatic repetition

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

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

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

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

repetition

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

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

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

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

repetition = cmmnStandard

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. Cross-Stage Plan Item On-Parts

There is no conceptual reason to disallow plan item on-parts referring to plan items outside the sentry’s stage (as CMMN spec 1.0 does). The current implementation of the CMMN engine allows such connections as long as the plan item on-parts refer to plan items within the same stage hierarchy.

Plan item on-parts between plan items residing in sibling stages are currently not supported by edoras one CMMN. Such connections must be modeled using an intermediate plan item (like a milestone) residing in the parent stage of the two sibling stages in question.

Referring to plan items up-stage or down-stage, however, is possible. For example, the CMMN engine evaluates the following model correctly:

crossStagePlanItemOnParts

2. Developer Documentation

2.1. Integrating Custom Extension Code

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

Invoke custom code by means of a service task (by evaluating a runtime expression).
Provide low-level custom implementations for plan item transitions.

The following sections describe the two options in more detail:

2.1.1. Execute custom code by means of a Service Task

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

2.1.2. Provide custom implementations for plan item transitions

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

Define a bean with name cmmnExtensions implementing interface CmmnExtensions or extending DefaultCmmnExtensions.
In your CmmnExtensions class, implement the method of you choice to return your handler implementation. E.g. implement method getOccurExtension(..) to return your implementation of an OccurHandler.
Your implementation of the handler must extend the appropriate abstract handler (e.g. the OccurHandler) and implement the handler method responding to the handler’s plan item transition. (The occur method for the OccurHandler - there is a consistent naming pattern for the handlers and their methods.)

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

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

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

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

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

2.2. Standard CMMN State Transition Implementations

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

A generic CMMN engine implmenentation
Edoras one integration code

See: Design & Implementation Notes.

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

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

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

CasePlanModel

Stage

HumanTask

ProcessTask

CaseTask

Milestone

UserEventListener

create

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

enable

manualStart

Starts the HumanTask (see 'start').

Starts the ProcessTask (see 'start').

Starts the CaseTask (see 'start').

start

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

Creates and starts a Process Work Item.

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

occur

complete

Completes the Case Work Item (archives the case).

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

exit

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

Cancels the process.

Terminates the case represented by the CaseTask.

fault

reactivate

terminate

Completes the Case Work Item.

Terminates the case represented by the CaseTask.

Case auto-completion handling

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

2.3. REST API

2.3.1. Available CMMN REST Calls

Plan Item Transition

/rest/cmmn/CAS/{caseClientId}/{sourcePlanItemId}/{planItemTransition}/planItemTransition (method GET)

Trigger a transition on a plan item and subsequently re-evaluate the state model.

Plan Item Transition with Form Data

/rest/cmmn/CAS/{caseClientId}/{sourcePlanItemId}/{planItemTransition}/planItemTransitionWithFormData (method PUT)

Similar to the method above, but allows to pass form data in the request body. For example, this call is used to manually start a task with an init form.

Case File Item Transition

/rest/cmmn/CAS/{caseClientId}/{caseFileItemId}/{caseFileItemTransition}/caseFileItemTransition (method GET)

Trigger a transition on a case file item and subsequently re-evaluate the state model.

Case File Item Transition with Form Data

/rest/cmmn/CAS/{caseClientId}/{caseFileItemId}/{caseFileItemTransition}/caseFileItemTransitionWithFormData (method PUT)

Similar to the method above, but allows to pass form data in the request body. For example, this call is used to manually create a case file item of type edorasDataItem.

Discretionary Item Planning

/rest/cmmn/CAS/{caseClientId}/{sourcePlanItemId}/discretionaryItemPlanning (method GET)

Plan a discretionary item (move it from the planning table into the run-time model by creating a corresponding plan item in the run-time model).

State Update

/rest/cmmn/CAS/{caseClientId}/stateUpdate (method GET)

This re-evaluates the state model (entry criteria, exit criteria, applicability rules, (auto-)completion of stages). Calling this method makes sense when you have a state change in the back-end which is used in a back-end expression in your CMMN model and you want the back-end expression to be re-evaluated.

Current States

/rest/cmmn/CAS/{caseClientId}/currentStates (method GET)

Gets a JSON array of the model’s current states (milestones and stages).

Available Actions

/rest/cmmn/CAS/{caseClientId}/availableActions (method GET)

Gets a JSON array of the model’s available actions. Each entry in this array is an action. An example of such an action would be an entry to manually start a task in state ENABLED.

2.3.2. Description of REST Call Parameters

{caseClientId}

The edoras case Work Object ID.

{sourcePlanItemId}

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

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

{planItemTransition}

The transition to apply (the names of enum PlanItemTransition)

{caseFileItemId}

The model element ID of the case file item. Append ~N (where N is the instance number) to address a particular case file item instance. If there exists a work object for the case file item of interest, you can also pass the edoras Work Object ID.

{caseFileItemTransition}

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

2.4. CMMN Service

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

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

2.4.1. Available CMMN Service Calls

Re-evaluate a case model

void handleStateUpdate(CaseId caseId, TransitionData transitionData);

Invoke a plan item transition on a CMMN case instance

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

Invoke a case file item transition on a CMMN case instance

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

Invoke a discretionary item planning action on a CMMN case instance

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

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

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

Get the list of available actions for a CMMN case instance

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

Get a list of plan item instances of a given type

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

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

List<CaseFileItem> getCaseFileItems(CaseId caseId, String definitionType, TransitionData transitionData);

Get a particular plan item instance by Id

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

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.

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 two types of case file items are supported:

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

DefinitionType: edorasDataItem. These types of case file items are represented by their own run-time edoras work item. For these case file items, an init form and a work form can be defined. New case file items can be created via the Case Actions menu (in the case of case file items that have the necessary multiplicity property).

Milestones

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

User events

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

TimerEvents

Support for TimerEvents is not yet implemented. Consider modeling timer events with the help of a Process task (edoras one BPMN Process).

Generic events

External system events can be modeled by means of a generic event listener symbol. Such events can be triggered by means of a REST call.

3.1.2. HTML template

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

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

Case File Items - For created case file items

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

3.1.3. Sentries and Events

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

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

CREATE
ENABLE
MANUAL_START
START
COMPLETE
EXIT
TERMINATE

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

The events

FAULT
REACTIVATE,

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

The transition

OCCUR

is supported for Milestones and Event listeners:

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

CREATE
UPDATE

3.1.4. Roles

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

3.1.5. Discretionary Items and planning

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

3.1.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 properties

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

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

3.2. CMMN Stage 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 Parameters

3.3.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 REST 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/REST call
'Param' scope - param scope parameters are available during the whole evaluation cycle (CMMN service/REST call)

Some background: The starting point for a CMMN model evaluation cycle is a CMMN service method invocation (either directly or via REST). The call wraps a model evaluation cycle. Within an evaluation cycle, multiple plan item transition may take place. For example, the REST endpoint "planitemTransition" applies 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.3.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.3.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.3.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.3.5. Updating parameters

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 Case Work Item.)
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.3.6. Implicit parameters

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

_planItem
_planItems
_triggerItems

See section Expression variables with special meanings for more information.

3.3.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. CMMN Expressions

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

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

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

`_planItem`

Use this variable to refer to the current plant 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.

`_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 query properties of the third instance of a model element "humantask", use the following expression:

#{_planItems['humantask~3']}

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

Properties exposed by plan items

activeCount - the number of instances of this plan item type that are active.
blocking - the value of the Blocking property.
casePlanModel - the plan item representing the case plan model.
clientId - the client Id as a string; may be null (see workItem).
completionCount - the number of instances of this plan item type that have been completed.
completionNeutral - the value of the Completion neutral property.
disabledCount - the number of instances of this plan item type that are disabled.
enabledCount - the number of instances of this plan item type that are enabled.
id - the static model Id.
instanceCount - the number of instances of this plan item type.
instanceId - the instance Id (see Instance Ids).
instanceIntId - the instance number, an integer >= 1.
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 model.
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").
terminationCount - the number of instances of this plan item type that have been terminated.
triggerCount - the number of instances of this plan item type that have been triggered (transitioned from AVAILABLE to either ACTIVE, ENABLED or OCCURRED).
workItem (or workObject) - a typed edoras one Work Object Id for the string stored under clientId; may be null.

`_triggerItems`

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

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

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")
isCaseFileItem - a boolean 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

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 ORed sentries trigger simultaneously, the exact sentry passed in _triggerItems is not defined.

3.4.3. 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 first instance of a plan item, the instance Id suffix can be skipped. I.e. "onehumantask" is a synonym to "onehumantask~1" in the example above.

3.5. CMMN Stage and Milestone Visualization

3.5.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.5.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.5.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.5.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.

4. CMMN Palette

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

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

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

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

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

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

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

4.1. Human task

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

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

4.2. Case task

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

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

4.3. Process task

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

Table 5. Specific attributes for Process tasks
Attribute Name	Description
Required	Select this option to mark the element as required (exclamation mark decorator). Required plan items must reach one of the states {Completed, Terminated, Disabled} in order for their parent stage to complete.
Required (RT)	An optional run-time expression (#{..} syntax) for the Required property. If empty, the setting of the Required flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Required flag. The expression is evaluated once at the point of creation of the plan item instance (i.e at the start of the parent stage or at repetition time). Evaluation context is the Case Work Item.
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 or when referring to a model element (i.e. plan item ID) in a CMMN REST call). For convenience, this ID can be edited.
Repetition	Select this option to mark the element as repeatable (fence-mark decorator). Repeatable plan items may exist more than once at run-time, each having their own life-cycle. The combination of this property, Manual activation and no entry sentry has a special meaning called Automatic repetition: As a previous instance of the plan item completes, a new instance is automatically created and set into state Enabled.
Repetition (RT)	An optional run-time expression (#{..} syntax) for the Repetition property. If empty, the setting of the Repetition flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Repetition flag. The value is evaluated on demand, i.e. at the point in time a plan item’s sentry fires (leading to the creation of a new instance if evaluated to true). Evaluation context is the Work Item associated with the task, or the Case Work Item if no more specific Work Item is available.
Manual activation	Select this option to mark the element to have manual activation (right arrow 'play' decorator). Plan items with Manual activation move from state Available to state Enabled once they trigger. A plan item in state Enabled exposes an action button that allows the user to manually start the plan item.
Manual activation (RT)	An optional run-time expression (#{..} syntax) for the Manual activation property. If empty, the setting of the Manual activation flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Manual activation flag. The value is evaluated on demand, i.e. at the point in time a plan item is triggered (moving out of state Available). Evaluation context is the Case Work Item.
Completion neutral	Select this option to mark the element to be 'completion neutral'. The flag can be used to influence the way the plan item’s parent stage completes. Background: plan items in state Available may prevent the parent Stage (or Case) from automatically completing. By checking this property, the plan item will behave neutral with respect to the completion of the parent container.
Blocking	Set this property to mark the task as blocking. Blocking is the default behaviour where a task plan item remains active until it is moved out of its active state as work on the case progresses. An example of a typical flow of action would be: the Work Item is started and remains active until the case worker completes it or until it is completed due to some external condition. By marking a plan item as non-blocking, the Work Item is started in the normal way. However, at the same time, the plan item representing the Work Item completes, allowing the Case model to move forward while the task’s Work Item is still active.
Process reference	The process model reference referring to the BPMN process that is to start as this Process task moves to state Active.
Process name	An optional RT expression for the name of the started Process Work Item. If left empty, defaults to the value of the Name attribute under Common Attributes.
In	An optional input parameter map. Allows to map parameters and variables onto the Process Work Item as it is started. See section CMMN Parameters.
Out	An optional output parameter map. Allows to map parameters and variables onto the Case Work Item as the Process Work Item completes. See section CMMN Parameters.
Process id	The name of the variable under which to store the process Work Object Id on the Case Work Item (i.e. to let the Case know the Id of the started process). The name is optional and, if provided, can be a back-end expression (#{..} syntax} resolving to the name of the variable (evaluation context is the Case Work Item). If your Process task is repeatable, append the variable name with a pair of brackets ('[]'). This will store the process Work Object Ids in a map keyed by Process task instance Ids.

4.4. Service task

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

Table 6. Specific attributes for Service tasks
Attribute Name	Description
Required	Select this option to mark the element as required (exclamation mark decorator). Required plan items must reach one of the states {Completed, Terminated, Disabled} in order for their parent stage to complete.
Required (RT)	An optional run-time expression (#{..} syntax) for the Required property. If empty, the setting of the Required flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Required flag. The expression is evaluated once at the point of creation of the plan item instance (i.e at the start of the parent stage or at repetition time). Evaluation context is the Case Work Item.
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 or when referring to a model element (i.e. plan item ID) in a CMMN REST call). For convenience, this ID can be edited.
Repetition	Select this option to mark the element as repeatable (fence-mark decorator). Repeatable plan items may exist more than once at run-time, each having their own life-cycle. The combination of this property, Manual activation and no entry sentry has a special meaning called Automatic repetition: As a previous instance of the plan item completes, a new instance is automatically created and set into state Enabled.
Repetition (RT)	An optional run-time expression (#{..} syntax) for the Repetition property. If empty, the setting of the Repetition flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Repetition flag. The value is evaluated on demand, i.e. at the point in time a plan item’s sentry fires (leading to the creation of a new instance if evaluated to true). Evaluation context is the Work Item associated with the task, or the Case Work Item if no more specific Work Item is available.
Manual activation	Select this option to mark the element to have manual activation (right arrow 'play' decorator). Plan items with Manual activation move from state Available to state Enabled once they trigger. A plan item in state Enabled exposes an action button that allows the user to manually start the plan item.
Manual activation (RT)	An optional run-time expression (#{..} syntax) for the Manual activation property. If empty, the setting of the Manual activation flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Manual activation flag. The value is evaluated on demand, i.e. at the point in time a plan item is triggered (moving out of state Available). Evaluation context is the Case Work Item.
Completion neutral	Select this option to mark the element to be 'completion neutral'. The flag can be used to influence the way the plan item’s parent stage completes. Background: plan items in state Available may prevent the parent Stage (or Case) from automatically completing. By checking this property, the plan item will behave neutral with respect to the completion of the parent container.
Expression	A back-end expression (#{..} syntax). The expression is evaluated as the Service task becomes Active. Evaluation context is the Case Work Item.
Result variable	The name of the variable under which to store the result of the expression evaluation. The name can be a back-end expression (resolving to the name of the variable). By default, the variable is stored on the Case Work Item. Use the `_param_` prefix in the variable name to store the result in memory for the duration of the current model evaluation cycle (see sections CMMN Parameters and CMMN Expressions).

4.5. Milestone

This element represents the CMMN Milestone plan item.

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

4.6. Case file item

Case file items are used to model references to external data. There are two types of Case file items (attribute Definition type):

edoras data item - this Case file item type is represented by an edoras one Work Item. Modeling such a Case file item will result in the creation of Work Items (currently of type Case) that are children of the Case plan model Work Item. These work items can be used as data containers. They can be created and managed by means of init- and work forms.
edoras case variable - this type of Case file item allows to define a reference to a variable of the Case Work Item. As the Case variable is created/updated/deleted, corresponding Case file item transitions will be triggered on the Case file item.

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

Table 9. Specific attributes for Case file items of type `edoras data item`
Attribute Name	Description
Initialize form reference	A reference to a form definition. The form is presented as the user clicks the Case file item’s action button, leading to the creation of a new instance of a Case file item Work Object upon form submission.
Work form reference	A reference to a form definition. The form allows to update variables and properties of the Case file item Work Item.

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

4.7. Stage

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

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

4.8. 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.9. Entry criterion

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

Table 12. Specific attributes for Entry sentries
Attribute Name	Description
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.10. Exit criterion

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

Table 13. Specific attributes for Exit sentries
Attribute Name	Description
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.11. 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].

Table 14. Specific attributes for User event listeners
Attribute Name	Description
Model ID	A unique ID for the element. The ID is used to refer to a model element from outside of the diagram (e.g. from a CMMN Action button in a form or when referring to a model element (i.e. plan item ID) in a CMMN REST call). For convenience, this ID can be edited.
Repetition	Select this option to mark the element as repeatable (fence-mark decorator). Repeatable plan items may exist more than once at run-time, each having their own life-cycle. The combination of this property, Manual activation and no entry sentry has a special meaning called Automatic repetition: As a previous instance of the plan item completes, a new instance is automatically created and set into state Enabled.
Repetition (RT)	An optional run-time expression (#{..} syntax) for the Repetition property. If empty, the setting of the Repetition flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Repetition flag. The value is evaluated on demand, i.e. at the point in time a plan item’s sentry fires (leading to the creation of a new instance if evaluated to true). Evaluation context is the Work Item associated with the task, or the Case Work Item if no more specific Work Item is available.
Completion neutral	Select this option to mark the element to be 'completion neutral'. The flag can be used to influence the way the plan item’s parent stage completes. Background: plan items in state Available may prevent the parent Stage (or Case) from automatically completing. By checking this property, the plan item will behave neutral with respect to the completion of the parent container.

4.12. 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 REST call or cmmnService bean call.

Table 15. Specific attributes for Event listeners
Attribute Name	Description
Model ID	A unique ID for the element. The ID is used to refer to a model element from outside of the diagram (e.g. from a CMMN Action button in a form or when referring to a model element (i.e. plan item ID) in a CMMN REST call). For convenience, this ID can be edited.
Repetition	Select this option to mark the element as repeatable (fence-mark decorator). Repeatable plan items may exist more than once at run-time, each having their own life-cycle. The combination of this property, Manual activation and no entry sentry has a special meaning called Automatic repetition: As a previous instance of the plan item completes, a new instance is automatically created and set into state Enabled.
Repetition (RT)	An optional run-time expression (#{..} syntax) for the Repetition property. If empty, the setting of the Repetition flag is used. When provided, the value of this expression is evaluated at run-time and will determine the value of the Repetition flag. The value is evaluated on demand, i.e. at the point in time a plan item’s sentry fires (leading to the creation of a new instance if evaluated to true). Evaluation context is the Work Item associated with the task, or the Case Work Item if no more specific Work Item is available.
Completion neutral	Select this option to mark the element to be 'completion neutral'. The flag can be used to influence the way the plan item’s parent stage completes. Background: plan items in state Available may prevent the parent Stage (or Case) from automatically completing. By checking this property, the plan item will behave neutral with respect to the completion of the parent container.

4.13. Connector

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

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

4.14. 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
Case file items of type edoras data item

Table 17. Activation attributes
Attribute Name	Description
Name	The name displayed in the action button. If empty, fall-back to attribute Name under Common attributes.
Name (RT)	The name displayed in the action button. It can be a mixed expression consisting of static text and run-time expressions like "My name is #{bunny-name}". It takes precedence over the Name property at run-time. Evaluation context is the Case Work Item.
Description	The description for the action button. Currently not used in the Case template.
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. Tutorial

5.1. Auto-start task

We have a case model containing a single human task. The human task is started as the case is started. Completing the task completes the case.

5.1.1. 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 task

We have a case model containing a single human task. The human task is set to state ENABLED as the case starts. Selecting the task from the list of available actions manually starts (activates) the task.

5.2.1. Interaction

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

5.3. Sentry condition

We have a case model containing a single human task. The numan task is started as soon as the user sets the name of the case to "task".

5.3.1. Interaction

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

5.4. Sentry on-part

We have a case model containing two human tasks. One task starts upon completion of the first task.

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

We have a case model containing three human tasks. Tasks "A" and "B" are started as the case is started. Completing any of the tasks starts task "A or B completes".

5.5.1. Interaction

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

5.6. Sentry-AND

We have a case model containing three human tasks. Tasks "A" and "B" are started as the case is started. Completing both of the tasks starts task "A and B completes".

5.6.1. Interaction

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

5.7. Starting multiple task instances by Automatic Repetition

We have a case model containing a single human task. Multiple task instances can be started at the user’s discretion.

5.7.1. Interaction

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

5.7.2. Remarks

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

5.8. Starting multiple task instances using a User Event Listener

We have a case model containing a single human task and a user event listener. Both the user event listener and the task are repeatable. The task has a sentry and a connection (on-part) to the user event listener, listening to the OCCUR event. Clicking the user event listener starts the task.

5.8.1. Interaction

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

5.8.2. Remarks

Multiple instances of the task can be started (made ACTIVE) at the same time by repeatedly clicking the action button. With this setup, the task is goes from CREATED straight to ACTIVE. Using 'Completion neutral' on the User event listener, case "more easily" auto-completes compared to the previous example as there is no new task instance in state ENABLED. Init forms configured on the task are ignored. In this setup, the task is immediately started once the event listener is selected.

5.9. Starting multiple task instances at the same time

We have a case model containing a single human task that is repeatable and has manual activation. By manually starting the task, a new instance of the task is created and enabled.

5.9.1. Interaction

Start the case → this starts the task (due to the fact that it has an empty sentry with no condition which immediately fires)
Select the task from the "Active Work Items". This starts the task
The 'manualStart' event from the previous action triggers the on-part of the task to itself and immediately creates and enables a new instance of the task

5.10. Case File Item - respond to case variable updates

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

5.10.1. Interaction

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

5.11. Milestones

We have a case model containing a task and a milestone. As the task completes, the milestone is reached.

5.11.1. Interaction

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

5.12. Stage with exit sentry

Stages can be used to model blocks of related processing or to model special phases during the life-cycle of a case. In this example, we have a case model containing a stage which can be prematurely terminated by means of a user event listener and exit sentry

5.12.1. Interaction

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

5.13. Task with exit sentry

Task elements can also be terminated by means of exit sentries. Similar to the previous example, by clicking the user event listener, the end of the stage’s life-cycle can be forced. However, this time indirectly

5.13.1. Interaction

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

5.14. Stages and Plan Fragments

Stages can be nested to any level. They can be fitted with entry and exit sentries and connected via on-parts (connector lines). Stages have a life-cycle and a GUI representation (AVAILABLE/ACTIVE/COMPLETED). Plan Fragments are merely a means to group model elements. They don’t have a run-time representation.

5.14.1. Interaction

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

5.15. Case and Stage completion

A stage automatically completes as soon as it finds all of its child elements in state COMPLETED or TERMINATED. Using default settings, a stage with children in states AVAILABLE or ENABLED will not automatically complete. A modeler however may choose to force auto-completion of a stage containing AVAILABLE or ENABLED children by setting the stage’s "Auto complete" property to true. In addition, the property "Completion neutral" on event listeners can be used to help with auto completion.

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

5.15.1. Interaction

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

Variation with "Auto complete"

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

Variation with "Completion neutral" on the event listener

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