mendix · MarkvanMents · Mar 17, 2026 · Mar 17, 2026 · Mar 19, 2026 · Mar 20, 2026
diff --git a/...gic/microflows-and-nanoflows/activities/object-activities/committing-objects.md b/...gic/microflows-and-nanoflows/activities/object-activities/committing-objects.md
@@ -10,10 +10,10 @@ This activity can be used in both microflows and nanoflows.
 
 ## Introduction
 
-The **Commit object(s)** activity works on one or more objects. For persistable entities, committing an object stores it in the database. Committing non-persistable entities stores the current attribute values and association values in memory. This allows a rollback to revert to those values. See also [Persistability](/refguide/persistability/). External objects cannot be committed. To store changed values of external objects, use the [Send External Object](/refguide/send-external-object/) activity.
+The **Commit object(s)** activity works on one or more objects. For persistable entities, committing an object writes it to the database. Committing non-persistable entities stores the current attribute values and association values in memory. This allows a rollback to revert to those values. See also [Persistability](/refguide/persistability/). External objects cannot be committed. To store changed values of external objects, use the [Send External Object](/refguide/send-external-object/) activity.
 
 {{% alert color="info" %}}
-A Mendix commit does not always behave like a database commit. See [How Commits Work](#how-commits-work), below, for more information.
+A Mendix commit does not always behave like a database COMMIT. See [How Commits Work](#how-commits-work), below, for more information.
 {{% /alert %}}
 
 ## Properties
@@ -103,21 +103,53 @@ When inside a [nanoflow](/refguide/nanoflows/), the object is refreshed across t
 
 ## How Commits Work{#how-commits-work}
 
+In understanding commits, it is important to remember that each persistable object has two states:
+
+1. The state in the database where the values are shared with every other user of the app. This is the state you get when you retrieve an object which is not already in the app's memory.
+2. The state in memory where values changed by the app can be seen.
+
+Non-persistable entities behave like the in-memory version of a persistable object.
+
 ### Committing Objects
 
-When you commit an object, the current value is saved. This means that you cannot roll back to the previous values of the object using the rollback object activity of a microflow.
+When you commit an object which is in memory, all changes to the database values are saved. Once it is committed, you cannot roll back to the previous values of the object using the **Rollback object** activity of a microflow.
-When you commit an object which is in memory, all changes to the database values are saved. Once it is committed, you cannot roll back to the previous values of the object using the **Rollback object** activity of a microflow.
+When you commit an object which is in memory, changes to the values are saved in the database. Once it is committed, you cannot roll back to the previous values of the object using the **Rollback object** activity of a microflow.
-When you commit an object which is in memory, all changes to the database values are saved. Once it is committed, you cannot roll back to the previous values of the object using the **Rollback object** activity of a microflow.
+When you commit an object which is in memory, changes to the values are saved in the database. Once it is committed, you cannot roll back to the previous values of the object using the **Rollback object** activity of a microflow.
 
-However, a Mendix commit is not the same as a database commit. For an object of a persistable entity, the saved value is not committed to the database until the microflow and any microflows from which it is called, complete. This means that errors in a microflow can initiate a rollback. If a microflow activity errors and has **Error handling** set to **Rollback** or **Custom with rollback**, the value of the object is rolled back to the value it had at the start of the microflow. See [Error Handling in Microflows](/refguide/error-handling-in-microflows/) for more information.
+However, a Mendix commit is not the same as a database (SQL) COMMIT. When you use a **Commit object(s)** activity, Mendix actually performs an INSERT or UPDATE on the database. For an object of a persistable entity, the database COMMIT is not performed until the microflow and any microflows from which it is called, complete. This means that, although a retrieve from the database by the end-user's app will see the updated version of the object, the updated object will not be seen globally by other end-users until the microflows end.
 
-Mendix mimics this behavior for non-persistable entities. Committing a non-persistable entity means that you cannot use a rollback object activity to go back to the previous values, although the rollback error handling in a microflow rolls back to the original values.
+Another consequence of this distinction is that, in contrast to an explicit **Rollback object** call, which rolls back to the last Mendix commit, errors in a microflow can initiate a database rollback. If a microflow activity errors and has **Error handling** set to **Rollback** or **Custom with rollback**, the value of the object in the database is rolled back to the value it had at the last savepoint. See [Error Handling in Microflows](/refguide/error-handling-in-microflows/) for more information.
-Another consequence of this distinction is that, in contrast to an explicit **Rollback object** call, which rolls back to the last Mendix commit, errors in a microflow can initiate a database rollback. If a microflow activity errors and has **Error handling** set to **Rollback** or **Custom with rollback**, the value of the object in the database is rolled back to the value it had at the last savepoint. See [Error Handling in Microflows](/refguide/error-handling-in-microflows/) for more information.
+Another consequence of this distinction is that, in contrast to an explicit **Rollback object** call, which rolls back to the last Mendix commit, errors in a microflow can initiate a database rollback. If a microflow activity errors and has **Error handling** set to **Rollback** or **Custom with rollback**, the value of the object in the database is rolled back to the value it had at the last savepoint. The object in memory will, however, keep any changes to the values. See [Error Handling in Microflows](/refguide/error-handling-in-microflows/) for more information.
-Another consequence of this distinction is that, in contrast to an explicit **Rollback object** call, which rolls back to the last Mendix commit, errors in a microflow can initiate a database rollback. If a microflow activity errors and has **Error handling** set to **Rollback** or **Custom with rollback**, the value of the object in the database is rolled back to the value it had at the last savepoint. See [Error Handling in Microflows](/refguide/error-handling-in-microflows/) for more information.
+Another consequence of this distinction is that, in contrast to an explicit **Rollback object** call, which rolls back to the last Mendix commit, errors in a microflow can initiate a database rollback. If a microflow activity errors and has **Error handling** set to **Rollback** or **Custom with rollback**, the value of the object in the database is rolled back to the value it had at the last savepoint. The object in memory will, however, keep any changes to the values. See [Error Handling in Microflows](/refguide/error-handling-in-microflows/) for more information.
 
-{{% alert color="warning" %}}
-Deleting an object and then committing it can have different outcomes depending on whether the object has already been committed or not. If the object has already been committed, the delete will remove the object from the database, and the subsequent commit will have no effect. If the object is new (that is, it has not been committed before), the delete will do nothing, but the commit will store the object in the database. Therefore, this sequence of actions (a delete followed by a commit) may lead to unexpected results if the object has not been committed before.
-{{% /alert %}}
+#### What Gets Committed
+
+When you work on an object in memory, Mendix records whether the object has been changed. When you perform a **Commit object(s)** activity, changes to the current values are written to the database and Mendix marks the object as unchanged in memory. This has a couple of consequences that you might not expect:
+
+* If you commit an object which is then rolled back due to an error, committing the object again will not write the latest version to the database. You can understand this as the following sequence (see [Error Handling in Microflows](/refguide/error-handling-in-microflows/) for a more detailed discussion of how rollbacks work during error handling):
-* If you commit an object which is then rolled back due to an error, committing the object again will not write the latest version to the database. You can understand this as the following sequence (see [Error Handling in Microflows](/refguide/error-handling-in-microflows/) for a more detailed discussion of how rollbacks work during error handling):
+* If you commit an object and the transaction is then rolled back due to an error, committing the object again will not write the latest version to the database. You can understand this as the following sequence (see [Error Handling in Microflows](/refguide/error-handling-in-microflows/) for a more detailed discussion of how rollbacks work during error handling):
-* If you commit an object which is then rolled back due to an error, committing the object again will not write the latest version to the database. You can understand this as the following sequence (see [Error Handling in Microflows](/refguide/error-handling-in-microflows/) for a more detailed discussion of how rollbacks work during error handling):
+* If you commit an object and the transaction is then rolled back due to an error, committing the object again will not write the latest version to the database. You can understand this as the following sequence (see [Error Handling in Microflows](/refguide/error-handling-in-microflows/) for a more detailed discussion of how rollbacks work during error handling):
+
+    1. Your microflow starts and creates a savepoint.
+    1. You change your object in memory – it is marked as changed.
+    1. You perform a **Commit object(s)** activity which sends the changes to the database – the object in memory is marked as unchanged.
+    1. An error occurs after the **Commit object(s)** has successfully sent changes to the database – the microflow ends and data in the database is rolled back to the savepoint.
-    1. An error occurs after the **Commit object(s)** has successfully sent changes to the database – the microflow ends and data in the database is rolled back to the savepoint.
+    1. An error occurs in an activity after the **Commit object(s)** activity has successfully sent changes to the database – the microflow ends and data in the database is rolled back to the savepoint.
-    1. An error occurs after the **Commit object(s)** has successfully sent changes to the database – the microflow ends and data in the database is rolled back to the savepoint.
+    1. An error occurs in an activity after the **Commit object(s)** activity has successfully sent changes to the database – the microflow ends and data in the database is rolled back to the savepoint.
+    1. You perform a **Commit object(s)** on the object again, but the changes are not written to the database because:
+
+        * The object in memory still has your changes but it was marked as unchanged after your previous commit
-        * The object in memory still has your changes but it was marked as unchanged after your previous commit
+        * The object in memory still has the updated values but it was marked as unchanged after your previous commit
-        * The object in memory still has your changes but it was marked as unchanged after your previous commit
+        * The object in memory still has the updated values but it was marked as unchanged after your previous commit
+        * The **Commit object(s)** activity does not see the changed marker and so does not recognize that your object in memory has changes which need to be written.
+
+    If you want to keep the changes in the version which is in memory, you will have to work around this behavior by creating a new object which contains the changes.
-    If you want to keep the changes in the version which is in memory, you will have to work around this behavior by creating a new object which contains the changes.
+    If you want to keep the changes in the version which is in memory, you will have to work around this behavior by modifying the object again.
-    If you want to keep the changes in the version which is in memory, you will have to work around this behavior by creating a new object which contains the changes.
+    If you want to keep the changes in the version which is in memory, you will have to work around this behavior by modifying the object again.
+
+* Deleting an object and then committing it has different outcomes depending on whether the object has already been committed or not:
+
+    * If the object has already been committed, the delete will remove the object from the database, and the subsequent commit will have no effect.
+    * If the object in memory is new (that is, it has not been committed before you delete it), the delete will do nothing. However, the subsequent commit will write the object to the database. Therefore, this sequence of actions (a delete followed by a commit) may lead to unexpected results if the object has not been committed before.
+
+#### Committing Non-Persistable Entities
+
+Mendix mimics this behavior for non-persistable entities. This means that:
+
+* Performing a commit on a non-persistable entity means that you cannot use a **Rollback object** activity to go back to the previous values
+* If an error occurs in a microflow, and you have error handling which does a rollback, the values roll back to the state a the previous savepoint.
-* If an error occurs in a microflow, and you have error handling which does a rollback, the values roll back to the state a the previous savepoint.
+* If an error occurs in a microflow, and you have custom error handling, it will always act as a custom without rollback as persistable entities do not have a separate state in the database.
-* If an error occurs in a microflow, and you have error handling which does a rollback, the values roll back to the state a the previous savepoint.
+* If an error occurs in a microflow, and you have custom error handling, it will always act as a custom without rollback as persistable entities do not have a separate state in the database.
 
 ### Autocommit and Associated Objects {#autocommit-and-associated-objects}
 
-When an object is committed through a default **Save** button, a commit activity, or web services, it always triggers the commit events. The platform also evaluates all associated objects. To guarantee data consistency, the platform may also autocommit associated objects.
+When an object in memory is committed through a default **Save** button, a commit activity, or web services, it always triggers the commit events. The platform also evaluates all associated objects. To guarantee data consistency, the platform may also autocommit associated objects.
 
 An autocommit is an automatic commit from the platform, which is done to keep the domain model in sync. If your application ends up having autocommitted objects, then you will have a modeling error. Since an association is also a member of an object, the association is stored in the database as well. This means that if you create an order line inside an order and the order line is the parent of the association, when you commit the order line, the order is autocommitted.
 

diff --git a/...guide/modeling/application-logic/microflows-and-nanoflows/events/error-event.md b/...guide/modeling/application-logic/microflows-and-nanoflows/events/error-event.md
@@ -10,15 +10,19 @@ This event can only be used in **Microflows**.
 
 ## Introduction
 
-An error event defines where a microflow will stop and throw an error that occurred earlier. If you call a microflow, you may want to know whether any errors occurred within the microflow or not. This event throws the error again, so the caller of the microflow can catch them. When you use this event, all database actions within the current transaction will be rolled back (for more information, see [Error Handling in Microflows](/refguide/error-handling-in-microflows/)).
+An error event defines where a microflow will stop and throw a new error based on the error that occurred earlier. If you call a microflow, you may want to know whether any errors occurred within the microflow or not.
+
+When you use this event, it creates a new error with the same information as the original error. Because this is a new error, even if the error that occurred earlier was caught **without rollback**, all database actions within the current transaction will be rolled back (for more information, see [Error Handling in Microflows](/refguide/error-handling-in-microflows/)).
-When you use this event, it creates a new error with the same information as the original error. Because this is a new error, even if the error that occurred earlier was caught **without rollback**, all database actions within the current transaction will be rolled back (for more information, see [Error Handling in Microflows](/refguide/error-handling-in-microflows/)).
+When you use this event, it creates a new error with the same information as the original error. Because this is a new error, even if the error that occurred earlier was caught **without rollback**, all database actions within the current microflow will be rolled back (for more information, see [Error Handling in Microflows](/refguide/error-handling-in-microflows/)).
-When you use this event, it creates a new error with the same information as the original error. Because this is a new error, even if the error that occurred earlier was caught **without rollback**, all database actions within the current transaction will be rolled back (for more information, see [Error Handling in Microflows](/refguide/error-handling-in-microflows/)).
+When you use this event, it creates a new error with the same information as the original error. Because this is a new error, even if the error that occurred earlier was caught **without rollback**, all database actions within the current microflow will be rolled back (for more information, see [Error Handling in Microflows](/refguide/error-handling-in-microflows/)).
 
 {{% alert color="warning" %}}
-You can only use an error event if an error is in scope: Studio Pro does not accept it if you connect the normal execution flow to an error event, because there would not be an error to pass back to the caller.
+You can only use an error event if an error is in scope: Studio Pro does not allow you to connect the normal execution flow to an error event, because there would not be an error to pass back to the caller.
 {{% /alert %}}
 
-In this example, an error occurs while committing an object to the database. It is caught, and the flow continues to the error event where the error is passed back to the caller of the microflow. So you can implement your error handling on multiple levels.
+## Example of Error Event
+
+In the example below, an error flow is defined when performing a Mendix commit. Any error is caught, and the flow continues to the error event where the error is passed back to the caller of the microflow. This allows you to implement your error handling on multiple levels.
 
-{{< figure src="/attachments/refguide/modeling/application-logic/microflows-and-nanoflows/events/error-event/error-event.png" class="no-border" >}}
+{{< figure src="/attachments/refguide/modeling/application-logic/microflows-and-nanoflows/events/error-event/error-event.png" class="no-border" alt="A microflow with a parameter of 'MyEntity'. It has a single action committing 'MyEntity' which has an error flow ending in an error event and the normal flow ending in an end event" >}}
 
 {{% alert color="info" %}}
 When adding an error event, you need to add an [error handler](/refguide/error-handling-in-microflows/#errorhandlers) for an activity before the error event. Link an error event and an activity which has an error handlers set on it with a [sequence flow](/refguide/sequence-flow/) and select **Set as error handler** for the sequence flow.