Skip to main content

List Based Scope

The List-based Scope is a straightforward design pattern for managing Atomicity in transactions. In this pattern, the transaction scope is defined by a collection of Microflow variables (lists). The core of this pattern is to explicitly passing this scope -the set of lists- as parameters throughhout the microflow chain.

1. How It Works (Process Flow)​

image-20251124-115357.png

1.1. Scope Creation​

Creation of the scope is implemented in two places:

  1. Touchpoint Microflows (initial input): For every object that is created or changed by the touchpoint (e.g. user input), the touchpoint microflow initializes an empty list variable and immediately adds the mutated objects on these lists. This list is then passed to the orchestration (ORC) microflow.
  2. Top Orchestration Microflows (Non-Touchpoint Changes): For objects that are not mutated by the touchpoint, but are instead mutated later by an operation- (OPR) or consumed API (CON) microflow, the Top Orchestration microflow (ORC) is responsible for initializing and passing an empty list variable in the the microflow hierarchy.

The combination of the lists created in the Touchpoint and the Top Orchestration microflows forms the complete List-based Scope.

1.2. Scope Population​

As objects are mutated (created, updated, or marked for deletion), the microflow responsible for the change must also add the changed object to its corresponding list variable within the scope.

warning

Be aware that an object can be on a list twice!

Suppose an object is retrieved from database and added to a list. If this object is changed and added to the list again, the list contains two version of the same object. To prevent inconsistent commits, ensure that only the last version of an object is on the scope.

A solution is to create a special ‘add to scope’ microflow for each entity that removes the old version from the list first.

1.3. Scope Validation:​

All lists within the populated List-based scope are passed to the dedicated Commit Microflow Typology (CMT). The CMT microflow iterates through these lists and executes the necessary business rules by calling the validation microflows (VAL) for each object on the scope.

1.4. Scope Commit:​

After a successful validation, the CMT executes the final commit and delete actions on every object in the list, ensuring an "all or nothing" result for the transaction.

1.5. Scope Rollback:​

When a validation fails, only ‘non-touchpoint changes’ must be rolled back. These objects, are mutated by the microflow hierarchy, and resides on the commit lists that are created by the top-orchestration microflow.

Important: Notice mutations that represent direct user input must be preserved (not rolled back), guaranteeing that the initial user input (touchpoint data) is never lost. These mutated objects are on the commit list(s) created by the touchpoint microflow.

info

A more robust rollback solution would be the ability to reset all objects in the server Transaction Memory to their state at the start of the transaction. However, this is not possible with the standard Mendix platform.

An advanced solution to handle this will be detailed in version 2 of the Menditect Testability Framework.

2. Implementation Choice​

You must make a choice about how to manage actions:

  • Option A: Separate Lists: Use dedicated lists for objects intended for Commit (create/update) and separate lists for those intended for a Delete.
  • Option B: Single List: If you opt for one combined list for all actions, you must add a Boolean or Enumeration attribute (e.g., a MutationType attribute) to the objects. This attribute will indicate the intended action (Create, Update, or Delete) so the CMT microflow knows how to process the object correctly.

3. Advantages & Disadvantages​

The List-based Scope pattern has the following key characteristics:

  • Advantage: Explicit Control: The entire scope is explicitly visible in the microflow input parameters, making it easy to track the objects involved in the transaction.
  • Disadvantage: Parameter Overload: Microflows can quickly accumulate a large number of input parameters if the transaction involves many different entity types, which can clutter the logic.
info

It is strongly advised to use a special naming convention like <entityname>_toCommit to separate microflow input parameters from the scope parameters.