Hello everyone,
Currently, Module A contains more than 34 entities, which is creating a technical debt classified as a monolithic structure in Aimentor. I would like to know if anyone has successfully migrated entities along with all their records to a new module.
I tried following the instructions for the "Refactor" plugin I found in Forme, but it only provides guidance on copying the entity to the target module—this process does not include the records.
I would greatly appreciate any advice or best practices to ensure a successful migration of some entities.
Thanks in advance for your help!
Hello Ananias,
Hope you're doing well.
The question here is: do you really need to move your entities? Why don't you keep the entities and move everything else (logic, UI, etc.) instead? :)
When you move entities to a new module, the OutSystems platform will recreate them from scratch. This means you will need to migrate all existing data from old entities to the new ones (eventually for all environments), which can become complex, especially if you must preserve entity IDs to maintain data consistency and foreign key relationships. Additionally, the old entities will remain in the physical database, resulting in duplicated tables (they will not be deleted automatically).
In most refactoring scenarios, the best practice is to keep the entities in the original module and move the logic and UI components into separate modules. This approach allows you to gradually break down the monolith safely and efficiently, without data loss or downtime.
Kind regards,
Rui Barradas
The Refactor module *does* move the records. Well, kind of. Basically... it's a hack. It goes into the underlying metamodel for OutSystems, and updates the database so that the new Entities in the module they are "copied to" reference the ORIGINAL database tables from the module they were "copied from".
Does it work? YES. Yes it does. Are there other ways to do this that aren't hacks? YES. But they involve writing a lot of code to copy the data from one table to another and then update the referencing data, it's extremely time consuming and prone to failure.
THAT SAID:
1. To echo Rui's thoughts above... why not just move the non-data items to a new module instead?
2. Just because Discover or AI Mentor Studio says "this is a monolithic module!" does not mean that it actually is a monolithic module, or that it should be split apart. These tools follow rules without human insight, and may be wrong. The module may be fine.
3. Monolithic modules are not the worst thing in the world, and they are certainly much better than a botched refactoring which loses data or causes hours or days of downtime. (Ask me how I know.)
J.Ja
Hi @Rui Barradas ,
Most of the logic has already been migrated to the new module; only about 13 public server actions remain, which act as maintainers. These maintainers cannot be migrated unless I set the entity property Expose Read Only = No, but doing so would compromise data integrity because it would allow updates from any module.
Ananias G.
You don't need to set the Expose Read Only property to No.
You just need to create some CRUD actions that encapsulate the Entity actions and define them as Public (Public property set to Yes).
Hi
Step 1: Identify and Plan the Split
Before moving anything:
Identify which entities belong together logically (for example, all related to "Customer Management" or "Payments").
Make sure dependencies (references between entities) are well understood — use Dependency Analyzer for this.
Plan a new module (e.g., CustomerDataCore) that will contain those entities.
Step 2: Create the Target Module (Module B)
Create a new module of type Core or Library (usually a “Core Data” module if it contains entities).
Add any required structures, static entities, or dependencies that the moved entities need.
Step 3: Copy the Entities (Structure Only)
You can do this manually or using the Refactor Plugin:
The plugin (or manual copy-paste) will recreate the entity definitions in the target module.
Do not delete the original entities yet.
The entity GUID (identifier) changes when recreated in the new module. Therefore, OutSystems sees it as a new entity, and existing data will not automatically migrate.
Step 4: Move the Data (Records)
There are three safe options to migrate the data from the old entity to the new one:
Option 1: SQL Script Migration (recommended for large datasets)
After publishing the new module with the target entities, both old and new tables exist in the database.
Use Service Center → Monitoring → SQL Tool or SQL Management Studio to run SQL scripts like:
INSERT INTO OSUSR_XXXX_NEWENTITY (Id, Field1, Field2, ...)SELECT Id, Field1, Field2, ...FROM OSUSR_YYYY_OLDENTITY;
Publish the app again after verifying the data.
Keeps all record IDs and relationships consistent.
Option 2: Temporary Server Action (for smaller datasets)
If you don’t have direct database access:
Create a Server Action in the old module to read data from the old entity.
Use CreateOrUpdate actions to insert it into the new entity.
Run it once, then delete it after successful migration.
Example:
ForEach GetOldEntity.List CreateOrUpdateNewEntity(...)End
Option 3: Data Migration Plugin (Forge)
There’s a Data Migration Manager component on Forge that provides a UI for managing such migrations safely between environments/modules.
It can:
Export records from one entity
Import into another (if structure matches)
Step 5: Update References
After data is safely migrated:
Update all modules referencing Module A’s old entity to reference the new entity in Module B.
Use “Find Usages” → update references → republish.
Step 6: Clean Up
Once all references are updated and tested:
Remove the old entities from Module A.
Archive old data if needed.
Perform a full publish to ensure no broken references remain.
Karan Shinde