DeepClone Demystified: A Guide for Mendix Developers 

As Mendix developers, we often encounter scenarios where we need to duplicate data, whether it’s copying an object for a new record, creating a template, or preserving an original state before modifications. The Community Commons module, a staple in the Mendix Marketplace, offers a powerful tool for this: the DeepClone Java action. Unlike a simple clone, DeepClone goes beyond surface-level copying by replicating an object, its associations, and even referred objects. In this blog post, I’ll walk you through how to use DeepClone, explain its parameters, and share practical tips to make the most of it in your Mendix projects. 

What is DeepClone? 

The DeepClone Java action is part of the Community Commons module, a collection of reusable Java methods designed to extend Mendix’s capabilities. While the basic Clone action copies an object’s attributes and optionally its associations, DeepClone takes it further by recursively cloning associated objects and optionally traversing associations referring to the object. This makes it ideal for complex data structures where you need a fully independent copy of an entity and its relationships. 

One key difference to note: DeepClone commits all cloned objects to the database, whereas Clone does not. This behavior is crucial to understand when planning your logic.

Using DeepClone in Your Project 

Before you can use DeepClone, make sure you have installed the Community Commons module in your Mendix project: 

• Download from the Marketplace: Open Mendix Studio Pro, go to the Marketplace, search for “Community Commons,” and import it into your app. 
• Sync Your Project: After importing, synchronize your project to make the module’s actions available in your microflows. 

With the module in place, you’re ready to leverage DeepClone in your microflows. 

How to Use DeepClone – Example Case

Let’s break down how to implement DeepClone step by step using a practical example. In our example, we have an equipment maintenance app. In the app, an administrator can create processes for maintenance technicians to perform. 

In our domain model, Process represents a maintenance procedure for a piece of equipment (e.g., “Oil Change”). Each Process can have multiple ProcessVersions, which in turn contain ProcessSteps (e.g., “Check oil level”). Each ProcessStep has associated InputFields (e.g., a dropdown for “Oil Type”), and if the input field is of type dropdown, it links to the available ListOption entity (e.g., “Synthetic,” “Conventional”). This data structure is not dissimilar to the Mendix questionnaire module and is common for requirements involving runtime configurable forms. 

We have a requirement for an administrator to be able to create a new “version” of a process, without affecting existing or in-flight processes that technicians might have. To do this, we will create a new ProcessVersion and duplicate all of the existing data from the current ProcessVersion. 

Please note that the module is named ProcessManagement in the example application.  There is a separate module named EquipmentManagement that manages the equipment that the processes are associated with. Cross-module associations exist between Process and Equipment (Process_Equipment) and ProcessStep and Action (ProcessStep_Action). 

DeepClone Implementation 

Step 1: Create a Microflow 

Start by creating a microflow to handle the cloning. Let’s call it ACT_ProcessVersion_Duplicate. 

Step 2: Add Input Parameters 

The microflow needs the original ProcessVersion to clone. Add an input parameter—say, SourceProcessVersion—of type ProcessVersion. 

Step 3: Create the Target Object 

DeepClone requires a target object to copy the data into. Add a “Create Object” activity in your microflow to create a new ProcessVersion entity.  Name this variable TargetProcessVersion.  Since DeepClone copies everything, you don’t need to set any attributes yet—it’s just a placeholder. 

Step 4: Add the DeepClone Action 

Now, drag a “Java Action” activity into your microflow: 

• From the toolbox, select “Java Action.” 
• In the dialog, search for DeepClone (under the Community Commons category). 

DeepClone Configuration 

Step 5: Configure DeepClone Parameters 

DeepClone offers several parameters to control the cloning process. Below, you can find all the parameters and their uses.

To properly clone ProcessVersion in the example, DeepClone should skip the VersionNumber attribute as we’ll set a new version number manually. At the same time, it should keep the ProcessManagement.ProcessVersion_Process association unchanged (so the new version still links to the same process. Also, make sure to handle the reverse associations ProcessManagement.ProcessStep_ProcessVersion,  ProcessManagement.InputField_ProcessStep, and ProcessManagement.ListOption_InputField to duplicate the process steps and their associated input fields. And finally, exclude the  EquipmentManagement module. 

Your configuration should look like this: 

• Source: $SourceProcessVersion 
• Target: $TargetProcessVersion 
• MembersToSkip: ‘VersionNumber’ 
• MembersToKeep: ‘ProcessManagement.ProcessVersion_Process’ 
• ReverseAssociations: ‘ProcessManagement.ProcessStep_ProcessVersion,ProcessManagement.InputField_ProcessStep,ProcessManagement.ListOption_InputField’ 
• ExcludeEntities: empty 
• ExcludeModules: ‘EquipmentManagement’ 

A note on behavior, if EquipmentManagement was not excluded, DeepClone would traverse the ProcessStep_Action association and replicate the Action, Equipment, and Location objects in the EquipmentManagement module.  An alternative to excluding the module in this case would have been to add ProcessManagement.ProcessStep_Action to MembersToKeep. 

Step 6: Update the Version Number 

After cloning, the TargetProcessVersion will have all the ProcessStep, InputField, and ListOption data copied over. Since we skipped VersionNumber, we set it manually in the microflow. For example, increment the original version number: 

• Add a “Change Object” activity for TargetProcessVersion. 
• Set VersionNumber to $SourceProcessVersion/VersionNumber + 1. 

Step 7: Handle the Output 

DeepClone returns a Boolean (true if successful). You can use this for error handling if needed. For simplicity, let’s assume it succeeds and proceed. 

Step 8: Use the Cloned Object 

After the DeepClone action, $TargetProcessVersion is a fully independent copy of SourceProcessVersion, including its ProcessStep, InputField, and ListOption objects and associations. All the objects are committed by the java action. You can now modify it further or display it to the user. 

Here’s a summary of the microflow: 

• Input: SourceProcessVersion (ProcessVersion entity). 
• Create: TargetProcessVersion (new ProcessVersion entity). 
• Java Action: DeepClone with the parameters above. 
• Change: Set TargetProcessVersion/VersionNumber to $SourceProcessVersion/VersionNumber + 1.  Commit and refresh. 

Practical Tips and Best Practices 

• Test with Small Data First: Test with a small data set first to ensure it works as expected.  It’s easier to spot errors with fewer records. 
• Mind the Commits: Since DeepClone commits all cloned objects, avoid using it in transactions where you don’t want immediate persistence. Use Clone instead if you need an uncommitted copy. 
• Keep your DeepClone parameters up to date: As your application evolves, review your DeepClone to make sure it’s copying and excluding appropriately. 
• Use MembersToSkip Sparingly: Skipping too many members might leave your cloned object incomplete—double-check your requirements. 
• Autonumbers: If your entities have autonumber attributes, DeepClone generates new values automatically, avoiding conflicts. 
• Debugging: If something goes wrong, check the Mendix logs. Community Commons actions often log helpful details. 

When to Use DeepClone vs. Clone 

Use DeepClone when you need a complete, independent copy of an object and its related objects (e.g., duplicating a ProcessVersion with its steps and input fields). When you need an uncommitted copy of a single object’s attributes, with an option to include associations as references set on the cloned object, you use Clone.

Conclusion 

The DeepClone Java action is a powerful tool for Mendix developers needing to do complex data duplication, but due to its power and automated behavior, it can pose a risk of misuse or unexpected behavior. By understanding its parameters and integrating it into your microflows, you can save time and ensure data integrity in your applications. Next time you need to replicate multiple related objects, give DeepClone a try—it’s a reliable solution when used properly!