Staging of projects

With the import / export, project parts (nodes, tag types, …) can be ex- and imported. By this you can realize a staging of CMS projects by exporting content- and layout elements out of the development environment and importing them into a production system.

1 Introduction

Here You can find detailled information about staging and a short presentation:

Before continuing reading you should have read the pages about [export] and [import].

1.1 Object identity

When an object is created in Gentics CMS (page, folder, …), it gets a global unique ID assigned. This global ID will be used for export and also for the import, to correctly synchronize the various objects between different Gentics CMS installations.

With this global ID you always know on which system an object was created. The first 4 digits of the Gentics CMS system license key are used to generate this ID. That’s why it is very important, that a different license key is assigned to every Gentics CMS installation.

1.2 Dependencies (references)

The most objects have certain dependencies. When exporting a page, the export system also exports all tag types, because otherwise the page wouldn’t be correctly rendered on the target system (where the page is imported), when this tag type is missing there. For this reason all dependencies of the page (Tag types, templates, object properties) will be added automatically by the export dependency calculation.

There are also other “optional references”: For example if a tag with a “URL (Page)”-part inside a page, links to another page, this other page will not be added to the export automatically, because this behavior is normally not wanted. However since these linked pages (e.g.: CSS page) might be needed to correctly display the page, these “optional references” will be added as warnings after calculating the export dependencies and have to be confirmed before the export file is created.

2 Tutorial

The dialogs of the import / export all have lots of describing texts in the assistant and are therefore self-explaining. Should you however still have problems, there are two great articles, about how to do an export and an import:

3 Traps doors & risks

3.1 Best care and backup

Data can get lost (deleted) during import. For instance a changed imported tag type can lead to content loss in pages when they are using it and a certain part of this tag type was deleted. You should always keep sure to make backups.

3.2 Worse system performance

Long running imports ad exports can have an affect on the system performance. Reason: Because the imports are running inside a MySQL transactions and tables are automatically locked on update / deletion sometimes for longer times the users might get a timeout or SGB (system error page). The locks are kept as short as possible by the import system, however they can still cause problems. You should plan imports of very large export files at times when the CMS is not used a lot.

3.3 Duplicate objects

When objects (e.g.: pages, folders, files, tag types, object properties, etc.) are created on a system, they get unique global IDs, which make this objects unique across all systems.

These global IDs are kept when the objects are imported on another system. However, when similar objects (same name / folder) are created by the user on different systems (e.g.: on the test and production system), they will get different global IDs and are handled as different objects by the import system.

If you transfer these objects from one system to another using export + import, then the objects can’t be matched to each other, even when they have the same name though, because they have different global IDs. They will be treated as different objects by the system. For tagtypes, object property definitions and datasources, it is possible to synchronize the global IDs between systems (before doing an export and import) with the GlobalIdSync Tool.

You can avoid this problem by doing an export + import of the objects first. Then the objects can be modified on any of the systems and the import system will treat the objects as the same in future imports. Example: A tag type A was created on the test system and then exported to the production system. Then A is modified on the test system and exported/imported again to the production system. The tag type change of A will now be taken over by the production system.

3.4 Memory usage

The import / export process can consume allot of system memory. Especially big export files (e.g.: whole nodes and web projects) can increase the memory consumption a lot. Please have a look at this manual how to increase the Tomcat memory limits. Depending on the size of the export file, we recommend a value of 2GB or even a lot more. The memory consumption can be very different across projects, and largely depends on the specific implementation. A rough rule of thumb is to estimate a size of between 50kB and 300kB per object. With a simple formula of *50kB * times the objects (pages, folders, files, …) to 300 kB * times the objects you can project the total size. You should also consider that additional imports of objects that already exist on the target system will take more memory than the first initial import of those objects.

3.5 Duplicate license key

It is very important that you use a different license key for every system. Apart from the license regulations aspects this also has technical reasons. If two installations of Gentics CMS use the same license key, it can happen that two newly created objects will get the same global ID and this can cause serious problems (internal system errors).

4 Permissions

Imports will be run with the permissions of the groups the current user is in or the import group that has been set when creating the import. If the group(s) don’t have sufficient privileges the import will fail and no data will be modified on the target system.

5 Management URLs

By using Management URLs it’s possible to create an export file for an already existing export or to run an update of it.

The URLs have the following syntax:


The username and the password have to be entered for all Management URLs. All further parameters are depending on the specific operation that is currently executed.

5.1 Generic parameters

These parameters are required for all operations:

  • login: Please enter the user name of the user who has sufficient privileges on the import.
  • Password: Password of that user.
  • cmd: The action that should be excuted. Possible values are the following: “createbuild”, “update” and “updatezip”.

5.2 Parameters for “createbuild”

createbuild creates a new export file of an export.

  • bundle_id: The ID of the export for which to to create a new export file. You can find the ID in the tool tip of the specific export in the export list.
  • changelog: The changelog-text that will be used for the new created exported file.

5.3 Parameters for “update”

Please note that the “update” is only available for import files that have been imported using the download-URL. Please use “updatezip” if you want to update imports that have been created by uploading a zip file.

  • bundle_id: The ID of the import that you want to update. You can find out the ID of the import in its tool tip in the list of imports.
  • conflictbehavior: Specifies the behavior for conflicts. “ignore” tells it to do not touch objects that have been modified locally. “overwrite” tells it to overwrite the local object with the object from the import file. “copy” will create a new object and not touch the local object.

5.4 Parameters for “updatezip”

You can use “updatezip” for updating import files that have been created by uploading a zip file. In order for this to work, the URL for the ZIP-archive file has to be accessible directly via HTTP.

  • url: URL where the ZIP file is located.
  • conflictbehavior: Specifies the behavior for conflicts. “ignore” tells it to do not touch objects that have been modified locally. “overwrite” tells it to overwrite the local object with the object from the import file. “copy” will create a new object and not touch the local object.