Gentics CMS Content Staging

This feature allows transporting content (nodes, channels, folders, pages, images, files and forms) by

1 Configuration

This feature requires an extra activation for your Gentics CMS license key. Please contact your account manager for details. To activate Content Staging for your installation add the following setting to your node.conf and restart your application or container server, where Gentics CMS is hosted.

conf/features.yml

feature:
  content_staging: true

The content staging packages are located at the filesystem under /cms/content-packages.

2 Usage

2.1 Packages manipulation

If the feature is configured properly, a new Content Staging item appears under Administration UI - Operations:

Content Staging window allows basic operation over Content Staging packages:

  • Creation
  • Removal
  • Rename
  • Metadata edit

Supported package content functions:

  • Import into CMS: the package content is to be imported into CMS content
  • Export from CMS: the package content is to be refreshed from CMS contents
  • Download: the package is downloaded in form of ZIP archive, for further local content altering.
  • Upload: the content ZIP archive can be uploaded into an existing package

2.2 Content manipulation

In order to add / remove content against the Content Staging package, use the Content Staging button under Product Tools in the Editor UI:

In the following modal, you can select the content package to modify:

This switches the Editor UI in the Content Staging Mode for the selected package, and the context menu for entities will now show actions to add and remove the entity.

When you are done with the content package, use the button labelled Leave Content Staging to switch back to the normal mode.

3 Implementation details

3.1 Adding objects

When objects are added to content packages, they will immediately be written to the filesystem (in their current state). If objects are modified afterwards, their stored representation in the content package will not be updated automatically.

To make sure that all objects in the content package are up to date with the objects in the CMS, the action “Export from CMS” needs to be executed.

3.2 Staging of folder structures

When objects are added to a content package, their parent folders will also be added to the content package (up to and including the node or channel). Importing the content package to the target system will always import the whole folder structure, not only a single object.

3.3 Staging of nodes/channels

For nodes and channels, not all of the attributes are handled in the same way when it comes to staging.

Attribute Import Overwrite Note
Name
Description
Https
Hostname
Publish directory segments
Mesh Preview URL
Allow insecure Mesh Preview URL
Disable publishing New nodes will have the “disable publishing” flag set after importing
Publish files to filesystem
Publish pages to filesystem
Publish files to CR
Publish pages to CR
Publish folders to CR
Publish directory (pages)
Publish directory (files)
Omit page extensions
Page language code placement
Page URLs rendering
File URLs rendering
Activated node features
Node languages
Assigned constructs Already assigned constructs will never be unassigned by an import.
Assigned object properties Already assigned object properties will never be unassigned by an import.
Assigned content repositories Already assigned content repositories will not be unassigned by an import, if the node does not have a content repository assigned in the content package.
Assigned devtool packages Already assigned devtool packages will never be unassigned by an import.

3.4 Staging of page/form versions

When a page or form is added to a content package, all relevant versions of the object will be stored in the content package:

  1. Published version (if the page/form is currently published)
  2. Planned version (if the page/form is planned to be published at a certain time in the future)
  3. Current version (this version always exists)

When importing the content package to the target system, all versions contained in the content package will be imported and set in the correct state:

  1. If a published version exists in the content package, it will be imported and published
  2. If a planned version exists in the content package, it will be imported and planned for the stored timestamp
  3. The current version from the content package will be imported

Note: Version numbers and dates will not be stored in the content package but will be created during import. So they are very likely to be different in the source and target systems.

3.5 Implementation check

Content Staging does a very strict check for consistency of the “implementation entities”, which are used for exported objects.

Implementation entities are

  • Templates of pages
  • Constructs used by pages or object properties
  • Object property definitions
  • Datasources used in constructs

When exporting a content object, that references implementation entities, md5 hashes will be generated for all those implementation entities and stored with the content object. Importing will only be possible, if

  1. All referenced implementation entities exist in the target system (identified by their global IDs)
  2. All referenced implementation entities are implemented exactly like they were in the source system (md5 hashes must match)

If at least one implementation entity does not match, the import will fail (nothing will be changed in the target CMS) and a list of all mismatching entities is shown to the user.

It is advisable to use devtool packages for transport of the implementation entities between source and target systems to make sure that the implementation is identical.

3.6 Import Errors

To better solve import errors, a import check can be performed in the content staging module of the administrator user interface.

3.6.1 Error Types

All errors that would occurs when doing the actual import are listed and can be inspected. The errors are categorized in different error classes.

Error Type Description
MISMATCH The implementations used in the content package have changed.
EXCEPTION General error. Occurs when, for example, tag types are not available in the target system.
DUPLICATION The object is already present multiple times in the target system.
NOT_FOUND When objects referenced in the content package, such as images, are not found.
OTHER Catch-all category for all other errors.
3.6.2 NOT_FOUND and EXCEPTION

Make sure that the object is available in the CMS and then synchronize the package again in the file system.

Tag types

  1. import all implementation packages (DevTool packages) whose objects are used in the content package into the target system first.
  2. use the consistency check to ensure that the implementation packages are complete.
  3. now perform the package check again.

Images & files

  1. make sure that the referenced file exists in the source system.
  2. make sure that the file has been added to the content package of the source system.
  3. synchronize the content package from the source system to the file system.
  4. replace the customized content package in the file system of the target system.
  5. now perform the package check again. You can find more information on troubleshooting in our guides.
3.6.3 MISMATCH

Make sure that the content package uses the current implementations.

  1. synchronize all implementation packages (DevTool packages) whose objects are used in the content package from the source system to the file system first.
  2. transfer them to the file system of the target system.
  3. synchronize the new implementation packages from the file system to the target system.
  4. thereafter synchronize the content package from the source system to the file system and import it into the target system.
  5. now perform the package check again.
3.6.4 DUPLICATION

Delete one of the two objects that caused the conflict.

3.6.5 OTHER

No recommendation can be given for this error. Please take a look at the error description.