NF6.2 Migrate ID - Revision history

CarlosRuiz at 10:36, 25 June 2025

2025-06-25T10:36:03Z

CarlosRuiz at 10:33, 25 June 2025

2025-06-25T10:33:58Z

CarlosRuiz: Warning about AD_Client_ID

2025-06-25T10:27:02Z

Warning about AD_Client_ID

CarlosRuiz: typo

2025-02-25T09:58:53Z

typo

CarlosRuiz: Update documentation with release-11 information

2023-11-21T09:30:58Z

Update documentation with release-11 information

CarlosRuiz: /* Description */ fix typo

2020-08-05T13:31:35Z

Description: fix typo

CarlosRuiz: /* Process */ fix typo

2020-08-05T13:29:55Z

Process: fix typo

CarlosRuiz: /* Usage */

2019-07-12T12:13:22Z

Usage

CarlosRuiz: doc

2019-03-14T11:05:05Z

doc

New page

= '''Feature:''' Migrate an ID or UUID =

'''Goal:''' Technical

'''Developers:''' [[User:CarlosRuiz|Carlos Ruiz]]

'''Sponsors:''' [https://www.fh.com.br/ FH]

== Description ==

This functionality allows to change the ID or UUID of a record.

There are some cases where an implementation requires to change these keys, for example:
* changing ID
** when a dictionary object was created in an implementation but then it's created officially, in this case is good idea to keep the ID in sync with the official ID
*when migrating a record with 2Pack to a different database, but because of hardcoded references in programs you need to preserve the IDs (NOTE this is not a recommended practice, your hardcodes must better point to the UUID which is preserved by 2Pack between installations)
* changing UUI
** when two developers created the same dictionary object - 2Pack usually collides, one of them needs to change the UUID
** samely when managing multiple environments (development, qa, stage, production) sometimes you find conflicts in UUID that needs to be solved to upload 2Packs properly

== Usage ==

* Log in as System
* Open the process '''Migrate ID'''
* Fill the parameters properly as explained below in detail

[[Image:01_MigrateID.png]]

== Parameters ==

'''Table:''' This is the table that requires the ID/UUID change

'''Record ID:''' The record ID to be changed

'''To Record ID:''' The target record ID, if empty it will be generated using the table sequence

'''Source UUID:''' The UUID to be changed

'''Target UUID:''' The target UUID, if empty it will generate a new random UUID

Change ID or UUID are excluyent, you can change ID or UUID, but not both at the same time

== Process ==

Changing the UUID is simple, just an update as the UUID is not kept as foreign key.

Changing the ID is more complex as it requires to update the whole database:
* Migrate all children tables related
* Migrate special references for data types Location, Account, Locator, Attribute, Assignment, Image, Color and Chart
* Migrate weak references based on AD_Table_ID+Record_ID
* Migrate weak references in AD_Peference table

<span style="color:red">'''WARNING!'''</span>
* The full foreign key discovery is based on dictionary, not in database, so, it can be problematic if you dictionary is not accurate
* Special data types like SingleSelectionGrid and MultipleSelectionGrid are not supported, they are not migrated
* Custom data types that represent a foreign key are not migrated - Note if you have a custom data type is better to use it in AD_Field instead of AD_Column to avoid problems with these programs
* Other weak references are not migrated, for example if you use IDs or UUIDs in AD_SysConfig or other tables, they are NOT migrated, you must check for that condition manually

'''Technical Info:''' [https://idempiere.atlassian.net/browse/IDEMPIERE-3916 IDEMPIERE-3916]

[[Category:New Features|T]]
[[Category:New Features v6.2|T]]

@@ Line 57: / Line 57: @@
 * Other weak references are not migrated, for example if you use IDs or UUIDs in AD_SysConfig or other tables, they are NOT migrated, you must check for that condition manually
-== WARNING!!  SPECIAL NOTE ABOUT AD_Client_ID using keystore ==
+== WARNING!!  SPECIAL NOTE ABOUT AD_Client_ID ==
-Be careful when changing the AD_Client_ID key when using keystore (idempiere.ks and idempiere-ks.properties).
+Be careful when changing the AD_Client_ID key when using keystore encryption (idempiere.ks and idempiere-ks.properties).
-If you have encrypted columns and use the keystore approache (idempiere.ks), the encryption key is based on the AD_Client_ID, so, changing the AD_Client_ID can make your encrypted data useless.
+If you have encrypted columns and use the keystore approach (idempiere.ks), the encryption key is based on the AD_Client_ID, so, changing the AD_Client_ID can make your encrypted data useless.
 '''Technical Info:''' [https://idempiere.atlassian.net/browse/IDEMPIERE-3916 IDEMPIERE-3916]

@@ Line 57: / Line 57: @@
 * Other weak references are not migrated, for example if you use IDs or UUIDs in AD_SysConfig or other tables, they are NOT migrated, you must check for that condition manually
-== WARNING!!  SPECIAL NOTE ABOUT AD_Client_ID ==
+== WARNING!!  SPECIAL NOTE ABOUT AD_Client_ID using keystore ==
-Be careful when changing the AD_Client_ID key.
+Be careful when changing the AD_Client_ID key when using keystore (idempiere.ks and idempiere-ks.properties).
-If you have encrypted columns, by default in iDempiere the encryption key is based on the AD_Client_ID, so, changing the AD_Client_ID can make your encrypted data useless.
+If you have encrypted columns and use the keystore approache (idempiere.ks), the encryption key is based on the AD_Client_ID, so, changing the AD_Client_ID can make your encrypted data useless.
 '''Technical Info:''' [https://idempiere.atlassian.net/browse/IDEMPIERE-3916 IDEMPIERE-3916]

@@ Line 53: / Line 53: @@
 <span style="color:red">'''WARNING!'''</span>
-* The full foreign key discovery is based on dictionary, not in database, so, it can be problematic if you dictionary is not accurate
+* The full foreign key discovery is based on dictionary, not in database, so, it can be problematic if your dictionary is not accurate
 * Custom data types that represent a foreign key are not migrated - Note if you have a custom data type is better to use it in AD_Field instead of AD_Column to avoid problems with these programs
 * Other weak references are not migrated, for example if you use IDs or UUIDs in AD_SysConfig or other tables, they are NOT migrated, you must check for that condition manually

@@ Line 49: / Line 49: @@
 * Migrate special references for data types Location, Account, Locator, Attribute, Assignment, Image, Color and Chart
 * Migrate weak references based on AD_Table_ID+Record_ID
-* Migrate weak references in AD_Preference table
+* Migrate weak references in AD_Preference table when the attribute name is the same as the column name
 <span style="color:red">'''WARNING!'''</span>
 * The full foreign key discovery is based on dictionary, not in database, so, it can be problematic if you dictionary is not accurate
 * Custom data types that represent a foreign key are not migrated - Note if you have a custom data type is better to use it in AD_Field instead of AD_Column to avoid problems with these programs
 * Other weak references are not migrated, for example if you use IDs or UUIDs in AD_SysConfig or other tables, they are NOT migrated, you must check for that condition manually

@@ Line 15: / Line 15: @@
 ** when a dictionary object was created in an implementation but then it's created officially, in this case is good idea to keep the ID in sync with the official ID
 *when migrating a record with 2Pack to a different database, but because of hardcoded references in programs you need to preserve the IDs (NOTE this is not a recommended practice, your hardcodes must better point to the UUID which is preserved by 2Pack between installations)
-* changing UUI
+* changing UUID
 ** when two developers created the same dictionary object - 2Pack usually collides, one of them needs to change the UUID
 ** samely when managing multiple environments (development, qa, stage, production) sometimes you find conflicts in UUID that needs to be solved to upload 2Packs properly

@@ Line 22: / Line 22: @@
 * Log in as System
-* Open the process '''Migrate ID'''
+* Open the process '''[[Migrate_ID_(Process_ID-200111)|Migrate ID]]'''
 * Fill the parameters properly as explained below in detail