Synchronization of global IDs

When objects (tagtypes, datasources or object property definitions) were created independently on different systems, they will always be treated as different objects, which might lead to unwanted duplicates when using export and import. In such cases, it is possible to use a command line tool to synchronize the global IDs between systems (i.e. to change the global IDs on one system to match the global IDs on the other system).

1 Usage

It is strongly recommended to stop the Tomcat on the target system before using the Tool. If this is not done, and modifications happen while the tool is used (even in between different steps), data may be corrupted.

Synchronization is done in multiple steps:

1.1 Read the info from the source system

/cms$ java -cp cms-server.jar com.gentics.contentnode.tools.GlobalIdSync -read construct,objprop,datasource -out info.json

This will connect to the database (connection properties are read from the given config url), will read the global IDs of all objects of the specified type and will output the result in JSON format into the file info.json

The format of the file info.json is as follows:


{
	"constructs" : [
		{
			"globalid" : "A547.69478",
			"keyword" : "textshort",
			"name" : "Text (kurz)",
			"parts" : [
				{
					"globalid" : "A547.69484",
					"keyword" : "text",
					"name" : "Text",
					"value" : {
						"globalid" : "A547.69485",
						"keyword" : "text"
					}
				}
			],
			...
		},
		...
	],
	"objprops" : [
		{
			"globalid" : "A547.69486",
			"name" : "object.sortorder",
			"type" : 10002,
			"descriptivename" : "Sortierung",
			"prop" : {
				"globalid" : "A547.69497"
			}
		},
		...
	],
	"datasources" : [
		{
			"globalid" : "CA9B.74723",
			"name" : "[Basic] Floating",
			"entries" : [
				{
					"globalid" : "A547.75173",
					"key" : "Left / Links"
				},
				...
			]
		},
		...
	]
}

1.2 Transfer the file info.json to the target system

The file info.json must be copied to the target system. All following steps are done on the target system.

1.3 Activate maintenance mode and stop tomcat on target system

While doing all following steps, it is mandatory, that absolutely no data is changed on the target system. It is best to activate the maintenance mode and stop the tomcat to achieve this. Failing to do so may lead to data inconsistencies!

1.4 Match the objects

/cms$ java -cp cms-server.jar com.gentics.contentnode.tools.GlobalIdSync -match info.json -out match.json

This will read the information from the file info.json, will match the objects against the database (connection property read from the given url) and will output matching information into the file match.json in JSON format.

The file match.json contains data similar to the file info.json with additional attributes replaces that contains the global IDs of the matching objects on the target system.

For example:


{
	"objprops" : [
		{
			"globalid" : "A547.74284",
			"name" : "object.copyright",
			"type" : 10011,
			"descriptivename" : "Copyright",
			"prop" : {
				"globalid" : "A547.74293",
				"replaces" : "3D6C.79029"
			},
			"replaces" : "3D6C.79020"
		}
	]
}

Which means that the object property definition with global ID A547.74284 on the source system matches the object property definition with global ID 3D6C.79020 on the target system. When the synchronization is done, the global ID A547.74284 will replace global ID 3D6C.79020.

The file match.json will only contain objects, that have different global ID, but are likely to be matching.

The file should be inspected closely before doing the actual synchronization. Incorrect matches must be removed from the file.

1.4.1 How the matching is done
1.4.1.1 Tagtypes

Tagtypes are matched if the keyword is the same. For matching tagtypes, also the parts will be matched by identical keywords. It may well be, that not all parts of the tagtype in the source system have matching parts of the tagtyp in the target system. If the source tagtype is imported into the target system (after the synchronisation), the source tagtype will overwrite the target tagtype. Superfluous parts will be removed and missing parts will be added.

1.4.1.2 Datasources

Datasources are matched if they have identical names. For matching datasources, the entries will be matched by identical keys.

1.4.1.3 Object Property Definitions

Object property definitions are matched if they have identical names (tagnames, not the descriptive names).

1.5 Check and possibly modify the file match.json

In this step, the file match.json may be modified by removing incorrect matches.

It is strongly recommended to not do any other alterations to the file, especially not to change global IDs, as the result may be unexpected.

1.6 Generate update SQL

/cms$ java -cp cms-server.jar com.gentics.contentnode.tools.GlobalIdSync -sql match.json -out update.sql

This will read the matching information from file match.json and will generate the SQL statements necessary to synchronize the global IDs. The SQL statements will be written to the file update.sql.

1.7 Generate and execute update SQL

/cms$ java -cp cms-server.jar com.gentics.contentnode.tools.GlobalIdSync -exec match.json -out update.sql

Same as the previous step, but will also execute the statements. This is the only step, that will actually change data in the database.

1.8 Restart tomcat and disable maintenance mode

This will reactivate the system. After restarting the tomcat and before enabling the maintenance mode, the system may be tested for errors.

2 Command Line Parameters

Parameter Description
-out [file] Filename for writing output (depending on the current action)
-read [file] Read the object info for the given object types (possible are construct, objprop, datasource)
-match [file] Match the object info read from the file
-sql [file] Create SQL Statements for updating the globalids
-exec [file] Create and execute SQL Statements for updating the globalids