Skip to main content
Version: 4.3

Usage Manual

This page describes how to use the Data Model Synchronization plugin to export, compare, and synchronize CMDBuild data models across different environments.

The Data Model Synchronization plugin allows administrators to:

  • Export the schema of a CMDBuild instance
  • Compare different schema versions
  • Identify configuration differences
  • Apply schema changes to another environment

The plugin is primarily intended for:

  • Environment alignment
  • Configuration deployment
  • Migration activities
  • Plugin installation procedures

Supported objects include:

  • Classes and Attributes
  • Processes
  • Domains
  • Lookup Types and Lookup Values
  • DMS Models
  • DMS Categories
  • Context Menu JavaScript Components

Prerequisites​

Before using the plugin:

  • Verify that the Data Model Synchronization plugin is installed and enabled
  • Ensure that the user has administrative privileges
  • Create a database backup before applying any schema changes

Initial Operations​

After the plugin is installed, the administration page provides two available actions:

  • Download the current data model
  • Upload a JSON file

Downloading the Data Model​

This operation generates a JSON file containing the schema configuration of the current system.

The exported file includes:

  • Classes
  • Attributes
  • Processes
  • Domains
  • Lookup Types
  • Lookup Values
  • DMS Models
  • DMS Categories
  • JavaScript Components
  • Error messages

For systems that use workflows, the export also includes the process definitions required to recreate them in another environment.

During the export process, the plugin extracts the latest XPDL definition of each process and stores the files in a ZIP archive.

Both the JSON file and the XPDL archive are stored in the CMDBuild temporary directory.

Uploading a JSON File​

In this case, a data model exported from another environment is uploaded and compared with the current configuration.

The comparison output contains differences for the following object types:

  • Classes
  • Domains
  • Lookups
  • Processes
  • DMS Categories
  • DMS Models

For each category, three types of changes may be detected:

  • New objects: includes both the object definition and its attributes, when applicable. It is possible to accept or reject the creation of the object and each individual attribute

  • Removed objects: includes both the object definition and its attributes, when applicable. Only the removal of the object can be accepted or rejected because attribute removal is handled automatically as a cascade operation

  • Modified objects: for each modified object, up to four additional sections may be displayed, depending on the object type. These sections allow individual or complete acceptance of changes:

    • Modified properties
    • Added attributes or values
    • Modified attributes or values
    • Removed attributes or values

    For modified objects, the system does not display all values directly. Instead, a grid shows:

    • The modified property
    • The current value
    • The new value

Each entry can be expanded to inspect long values. Changes can be accepted or rejected individually.

Dedicated actions are also available to accept or reject:

  • All changes within a specific category
  • All detected changes

Applying Schema Changes​

After all required changes have been accepted or rejected, the current instance data model can be updated using the corresponding action.

Before proceeding, verify the following:

  • Create a complete database backup
  • Verify that all required files are available
  • Verify that the XPDL archive generated during export is still available
  • Verify that custom SQL triggers or functions do not interfere with object creation

The plugin applies only the required changes and preserves unchanged configuration elements.

Important Limitation​

Schema synchronization is not transactional.

If an error occurs during execution, changes that have already been applied are not automatically rolled back.

For this reason, creating a database backup before every synchronization activity is strongly recommended.

How Changes Are Managed​

During synchronization, the plugin automatically manages dependencies between objects and applies changes in the correct order.

For example:

  • Lookup definitions are created before attributes that use them
  • Classes are created before their attributes
  • Domains are created before reference attributes that depend on them

This approach allows complex data models to be synchronized safely and consistently.

Objects are deactivated rather than physically deleted. This helps preserve consistency and prevents accidental data loss.

Process Synchronization​

Processes are synchronized together with their workflow definitions.

During export:

  • The process configuration is collected
  • The latest XPDL files are exported
  • MD5 hashes are generated to identify workflow changes efficiently

During synchronization:

  • The XPDL archive must be available
  • Missing XPDL files generate warnings
  • Synchronization continues whenever possible

Error Messages​

During export, comparison, or synchronization, the plugin may detect configuration issues.

These messages do not necessarily stop execution.

Examples include:

  • Missing Lookup Types
  • Missing Domains
  • Missing target Classes for FOREIGNKEY attributes
  • Missing XPDL files
  • Missing Groovy scripts used by FORMULA attributes
  • Missing JavaScript Components

These issues are reported as validation messages to help administrators identify and correct configuration problems.

Whenever possible, processing continues so that the maximum amount of configuration can still be transferred.