Part 2: Tasks and Plan Items

Overview

In part 2 of the CMMN modeling series, we will learn one of the core elements of CMMN: Plan Items and one specific plan item type: Tasks.

Plan Item Lifecycle

A Plan Item is a very generic element in CMMN and almost all elements (like stages and tasks) are in fact all plan items. Therefore, it makes sense to look a bit into the details of a plan item to understand the basic concepts.

A plan item instance follows a very specific lifecycle:

(Source: CMMN 1.0 Standard, Section 7.4.2)

Whenever a new plan item instance is created by the case engine, it goes into available state and if it is started directly (no entry-sentries), it will even end up in the active state (see create and then start transition in the diagram, ending up in active state).

If a plan item has an entry-sentry (we will have a closer look to sentries in Part 3: Sentries), the plan item instance is not started directly, but remains in the available state as it is available to be started as soon as the entry-sentry (kind of its starting guard) is triggered and tells the case engine to actually start the plan item which then transitions from available to active state (if it has not manual activation, see next section).

If a plan item has manual activation (but no entry sentry), it is not started, but enabled and transitions from available into enabled state and waits for being manually activated (usually through a user at some later point in time).
Of course manual activation can also be combined with an entry sentry and in this case, the plan item instance first goes into available state and waits for its entry-sentry (or even more than one) to be triggered and then transitions from available to enabled state and waits until manually activated to then transition from enabled into active state.
While being in enabled state, a plan item instance can also be disabled and at a later point re-enabled again to return to enabled state.

As you can see, a plan item instance most important state is the active one, regardless whether directly activated at creation time or at a later point if guarded through one or more entry-sentries or even having manual activation, but eventually, it will end up in active state where its "work" will be executed which obviously depends on the type of the plan item, like a human task or a service invocation.

Once a plan item instance is activated and hence in active state, it can be "finished" in several ways:

• the regular way: through completion (e.g. a human task was worked on and is completed or a service task was executed successfully)
• through termination, either through an exit-sentry or by terminating its parent (e.g. a stage)
• if there is a failure during execution for instance, the plan item instance goes into failed state (through the fault transition) and might be reactivated to return into active stage for re-execution again

A finished plan item instance will either be completed (regular ending) or terminated (through an exit-sentry or when its parent is terminated).

This was a lot of theory around the lifecycle of a plan item, but as we are moving forward, you will see that it is an essential part to understand the lifecycle to come up with the necessary mechanisms and modeling practices to let the case engine do whatever is needed.

Manual Activation

As we have seen in the details of the lifecycle of a plan item and explored in Part 1 of this CMMN series, by default when plan item instances are created, they will directly hit the activated state.
But with the manual activation flag, we can mark them to first enter the enabled state and wait for them to be manually activated.
Think of a task that might be needed, but not in every case, and it is up to the caseworker to decided whether and when to actually start that task. That is a typical use-case for a manually activated plan item.

We can test this behavior by creating a new app, named Tutorial App - Part 2 and then a new case model named Tutorial Case Part 2 with a single stage and two tasks, one of them being manually activated. The model should look something like this:

If you select Task B and open the Manual activation property in the Human Task Control tab (with the play icon), you can turn on manual activation:

Beside turning manual activation on or off, if turned on, there are several further options available like the name of the action for the manual start rendered in the Flowable Work UI or its order, if there are more than one available. You can even choose the icon used for the manual activation action button.

The manually activated task (Task B) has this kind of "play" icon which is the CMMN notation standard to mark a plan item as manually actiavated.

When you deploy and create an instance of this case model, you will see Task A being created and activated right from the start of the case and there is a button in the header of the case in the Flowable Work UI named Task B where you can start that task by clicking that button and if you do so, Task B is started as well and will show up in the open task section of the case.

tip

A good way to learn the mechanics of CMMN is by using Flowable Inspect, a debugging tool directly built into the Flowable Work UI.
Here you can see behind the scenes of a case or process instance such as see its data, plan items event registrations and many more details.
More details on Flowable Inspect can be found in the first part of this CMMN Modeling Series.

Starting this case model in Flwoable Work and opening Flowable Inspect, you can see the following scenario when you switch to the plan item instances view:

As discussed earlier in this part, we see Stage A and Task A being active as they are immediately started by the case engine, however, Task B is in enabled state, as we marked it with manual activation and according the lifecycle diagram, it was created and directly got from available to enabled state, now waiting for being manually activated.
As soon as you click that Task B button in the case, the task will be "triggered" and will start and move from enabled into active state as well.

Maybe you also realized that Stage A only completes once you have manually started Task B and also completed it. Concerning the stage completion, manual activation did not change anything, the task still needs to be completed at some time, but you can define when it will show up in the task list of the case to work on that task and eventually complete it.

Auto-completion

As we have seen in the previous example, we still need Task B to be completed at some point, otherwise the stage will never complete. Although we delegated the start of the task to the case worker, there was no way to actually skip that task if not needed.

There is another option for stages or the case plan model as well: auto completion. As the name implies, if turned on, the stage or case plan model will automatically complete, if there is no more active or required plan item to be completed. Or in other words: turning on auto-completion will complete the stage, once there are only plan items remaining (if any) in either available or enabled state (and of course not marked as required).

Turn on auto completion for Stage A and run the case again, what happens once you complete Task A, but did not start Task B yet? Exactly, the stage is completed and hence the case as well!
But if you did start Task B before completing Task A, then you also have to complete it, as it turned into active state.

Of course this also means that you have to make up your mind concerning Task B BEFORE you complete Task A as there is no more time afterwards to manually start it.
This might also not be the ideal solution depending on the requirements, so we will learn some more sophisticated ways for stage and case completion later on in this CMMN Modeling Series.

Repetition

Next for plan items we want to see what repetition can be used for.

Obviously, with repetition, we can start and complete a plan item multiple times. By default, whenever a plan item with repetition is completed, it is started right away again.
With a combination of repetition and manual activation, you can manually start and complete a plan item as many times as you want / need, which might come in handy for a lot of use-cases (e.g. multiple ad-hoc tasks or multiple reviews / feedbacks, etc).

There is one problem though: how can we complete a stage having a plan item with repetition? As we learned before, a plan item with manual activation and its stage having auto-completion, the stage will complete once the plan item is in enabled state (not yet manually started). This does not change with additionally turn on repetition, however, if a "regular" plan item has repetition, its stage will never complete, even with auto-completion turned on.

In a later part, we are going to look into stage and case plan model completion in a lot of details to figure out various patterns on how best to model it.
For now, we are just looking into one more, very useful feature of the Flowable case engine: impact on parent completion.

Impact on parent completion

A very useful property for a plan item concerning its parent stage or case plan model completion is impact on parent completion. It can be used to define how the case engine is looking at the plan item when it comes to its parent completion detection.

By default, we already learned that a plan item must be in a final state (e.g. completed or terminated) in order for its parent to be completable and with auto-completion turned on, it might even be in available or enabled state to not prevent the parent from being completed (as long as it is not required though).

The Flowable case engine is going one step further and allows you to define a more fine-grained approach. Of course by default, a plan item behaves exactly as the CMMN spec implies, but you can have more options with the impact on parent completion property.

Here is a list of all the options:

• default: as seen before, the default options is behaving exactly as the CMMN spec implies: the plan item needs to be in a final stage for its parent to be completable or in combination with the auto-completion in either available or enabled state and not required for the parent to be completable
• ignore: regardless of the state of the plan item, it will always be ignored when considering for the parent to be completable
• ignore if available: pretty similar to the auto-complete option, this one ignores the plan item, as long as it is in available state (e.g. has an entry sentry, and it was not yet triggered)
• ignore if available or enabled: pretty similar to the previous one; this option ignores the plan item, if it is either in available or in enabled state
• ignore after first completion: this option is very interesting in combination with repetition as it allows a plan item to be ignored, once it has been completed at least once
• ignore after first completion if available or enabled: this option ignores the plan item, if it was completed at least once and is currently no longer active, but only in available or enabled state (e.g. a plan item with manual activation and repetition being completed once and waiting for the next manual activation)

As you can see, with this option, we have way more possibilities to influence the parent completion with a plan item having repetition turned on.
But again, as said before, we will look into stage and case plan model completion in more details in a later part of this CMMN Modeling Series.
As for our Task B, we might want to either choose ignore if available or ignore after first completion if available or enabled, depending on the desired behavior of course.

A very useful way to use repetition is combining it with a collection of values for each one of it one instance of the plan item is created. We will look into this variation in a later part of this series.

Summary

In this part, we learned the most important element of the CMMN spec: the plan item and its very important lifecycle and how we can influence it by using options like manual activation and repetition. We also had a quick first look into a stage or case plan model completion and what (first) options we have to influence it.