Chapter 8. Stages

Case management stages are a collection of tasks. A stage is an ad hoc subprocess that can be defined using the process designer and may include other case management nodes, such as a milestone. A milestone can also be configured as completed when a stage or a number of stages are completed. Therefore, a milestone may be activated or achieved by the completion of a stage, and a stage may include a milestone or a number of milestones.

For example, in a patient triage case, the first stage may consist of observing and noting any obvious physical symptoms or a description from the patient of what their symptoms are, followed by a second stage for tests, and a third for diagnosis and treatment.

There are three ways to complete a stage:

  • By completion condition.
  • By terminal end event.
  • By setting the Completion Condition to autocomplete, which will automatically complete the stage when there are no active tasks left in the stage.

8.1. Defining a stage

A stage can be modeled in BPMN2 using the process designer. Stages are a way of grouping related tasks in a way that clearly defines activities that, if the stage is activated, must complete before the next stage of the case commences. For example, the IT_Orders case definition can also be defined using stages in the following way:

Figure 8.1. IT_Orders project stages example

IT_Orders - stages


  1. From the process designer, click 3897 on the left of the palette to open the Object Library. Open the Subprocesses object list, drag and drop an Ad-Hoc node onto the design canvas and provide a name for the stage node.
  2. Define how the stage is activated:

    • If the stage is being activated by an incoming node, connect the stage with a sequence flow line from the incoming node.
    • If the stage is instead being activated by a signal event, configure the SignalRef on the signal node with the name of the stage that you configured in the first step.
    • Alternatively, configure the AdHocActivationCondition property to activate the stage when the condition has been met.
  3. Re-size the node as required to provide room to add the task nodes for the stage.
  4. Add the relevant tasks to the stage and configure them as required.
  5. (Optional) Configure a completion condition for the stage. As an ad hoc subprocess, stages are configured as autocomplete by default, which means that the stage will automatically complete and trigger the next activity in the case definition once all instances in the stage are no longer active.

    To change the completion condition, select the stage node and open the Properties panel on the right. Modify the Completion Condition property field in the with a free-form Drools expression for the completion condition you require. For more information about stage completion conditions, see Section 8.2, “Configuring stage activation and completion conditions”.

  6. Once the stage has been configured, connect it to the next activity in the case definition using a sequence flow line.

8.2. Configuring stage activation and completion conditions

Stages can be triggered by a start node, intermediate node, or manually using an API call.

You can configure stages with both activation and completion conditions using free-form Drools rules, the same way that milestone completion conditions are configured. For example, in the IT_Orders sample project, the Milestone 2: Order shipped completion condition (org.kie.api.runtime.process.CaseData(data.get("shipped") == true)) can also be used as the completion condition for the Order delivery stage represented here:

Figure 8.2. IT_Orders project stages example

IT_Orders - stages

Activation conditions can also be configured using a free-form Drools rule to configure the AdHocActivationCondition property to activate a stage.


  • You have created a case definition in the Business Central process designer.
  • You have added an ad hoc subprocess to the case definition that is to be used as a stage.


  1. With the stage selected on the case design canvas, click 3898 to open the Properties panel on the right.
  2. Open the AdHocActivationCondition property editor to define an activation condition for the start node. For example, set autostart: true to make the stage automatically activated when a new case instance is started.
  3. The Completion Condition is set to autocomplete by default. To change this, open the property editor to define a completion condition using a free-form Drools expression. For example, set org.kie.api.runtime.process.CaseData(data.get("ordered") == true) to activate the second stage in the example shown previously.

For more examples and information about the conditions used in the IT_Orders sample project, see Getting started with case management.

8.3. Adding a dynamic task to a stage

Dynamic tasks can be added to a case stage during run time using a REST API request. This is similar to adding a dynamic task to a case instance, but you must also define the caseStageId of the stage to which the task is added.

The IT_Orders sample case project can be defined using stages instead of milestones.

itorders stages

Use the following procedure to add a dynamic task to a stage in the IT_Orders sample project available in Business Central using the Swagger REST API tool. The same endpoint can be used for REST API without Swagger.


  • The IT_Orders sample project BPMN2 case definition has been reconfigured to use stages instead of milestones, as demonstrated in the provided example. For information about configuring stages for case management, see Defining a stage.


  1. Start a new case using the Showcase application. For more information about using Showcase, see Using the Showcase application for case management.

    Because this case is designed using stages, the case details page shows stage tracking:

    case with stages showcase

    The first stage starts automatically when the case instance is created.

  2. As a manager user, approve the hardware specification in Business Central under MenuTrackTask Inbox, then check the progress of the case.

    1. In Business Central, click MenuManageProcess Instances and open the active case instance IT-0000000001.
    2. Click Diagram to see the case progress diagram:

      case with stage diagram view
  3. In a web browser, open the following URL:


  4. Open the list of available endpoints under Case instances :: Case Management.
  5. Click click the following POST method endpoint to open the details:


  6. Click Try it out to complete the following parameters:

    Table 8.1. Parameters







    Order delivery

    The caseStageId is the name of the stage in the case definition where the dynamic task is to be created. This can be any dynamic or service task payload. See Creating a dynamic subprocess using the REST API or Creating a dynamic service task using the REST API for examples.

After the dynamic task has been added to the stage, it must be completed in order for the stage to complete and for the case process to move on to the next item in the case flow.