Models Management

Semarchy supports out of the box metadata versioning.
When working with a model in the Semarchy Workbench, the developer works on a Model Edition, that is a version of the model.

Model management includes all the operations required to manage the versions of the models.

Introduction to Metadata Versioning

A Model Edition is at a given point of time either Open or Closed for editing.
Branching allows you to maintain two or more parallel Branches (lines) of model editions.

Model Editions and Branches

Version Numbers

A model has a version number that is automatically generated with the Branch ID number and Model Edition number. The branch and model numbers start at zero and are automatically incremented as you create new branches or model editions.
A model edition appears in the following format: <Model Name> [<branch>.<edition>]. For example, the first model edition in the first branch has the version [0.0]. The fourth edition of the CustomerAndFinancialMDM model in the second branch is named CustomerAndFinancialMDM [1.3].

A Chronological Example

The following example shows the chronological evolution of a model through editions and branching:

The following schema illustrates the timeline for the edition and branches. Note that the changes is the two branches are totally decoupled. Stars indicate changes done in the model editions:

Month    : January       March      April   May        June     August
Branch 0 : [0.0] -***-> [0.1] -*-> [0.2] ----------*-> [0.3] ----------->
Branch 1 :                    +-branching-> [1.0] -**-**-****-> [1.1] --->

At that stage, two editions on two different branches remain and are open: CustomerHub [1.1] and CustomerHub [0.3].

Working with Model Editions and Branches

Model edition and branching can be managed from the Model Administration perspective.

To access the data administration perspective:

  1. Select the Overview perspective the toolbar.
  2. In the Overview, click the Manage Model Editions... link in the Administration section. The Model Administration perspective opens.

Creating a New Model

Creating a new model creates the model with the first model branch and model edition.

To create a new model:

  1. In the menu, select File > New > New Model.... The Create New Model wizard opens.
  2. In the Create New Model wizard, check the Auto Fill option and then enter the following values:
  3. In the Description field, optionally enter a description for the Model.
  4. Click Finish to close the wizard. The new model is created, with a root branch and a first edition.
  5. Model Edition perspective opens on the new model.

Closing and Creating a New Model Edition

This operation closes the latest open model edition in a branch and opens a new one. The closed model edition is frozen and can no longer be edited, but can be deployed to production environments.

Warning: It is only possible to close an open edition. This edition is the latest one from a branch.

Warning: It is only possible to close an edition that is valid.

To close and create a new edition:

  1. In the Model Editions view of the Data Administration Perspective, expand the model and the model branch containing the edition that you want to close.
  2. Right-click the latest model edition of the branch (indicated as opened) and select Close and Create New Edition.
  3. Click OK to confirm closing the model edition.
  4. The Enter a comment for this new model edition dialog, enter a comment for the new model edition. This comment should explain why this new edition was created.
  5. Click OK. The model is validated, then a new model edition is created and appears in the Model Editions view.

Important: Be cautious when closing a model edition. Closing an edition cannot be undone, and a closed edition cannot be reopened.

Branching a Model Edition

Branching a model edition allows restarting modifying a closed edition of a model. Branching creates a new branch based on a given edition, and opens a first edition of this branch.

Warning: It is only possible to branch from closed model editions.

Info: When creating a model, a first branch named <model_name>_root is created with the first model edition.

To create a new branch:

  1. In the Model Editions view of the Data Administration Perspective, expand the model and the model branch containing the edition from which you want to branch.
  2. Right-click closed the edition from which you want to branch and select Create Model Branch From this Edition. The Create New Model Branch wizard opens.
  3. In the Create New Model Branch wizard, check the Auto Fill option and then enter the following values:
  4. In the Description field, optionally enter a description for the Model Branch.
  5. Click Finish to close the wizard.
  6. In the Model Branch Created dialog, click Yes to open the first edition of this new branch.
  7. The newly created edition opens.

Model Localization

When designing a model, labels, descriptions and other user-facing text strings are entered to provide a user-friendly experience. These strings are natively externalized in Semarchy Convergence for MDM, and can be translated (localized) in any language.

A user connecting an application created with Semarchy Convergence for MDM will see these strings (label of the entities, attributes, list of values, etc.) translated in the locale of his web browser if such translation is available. If no translation is available in his locale for a given text, the default string (for example, the label or description specified in the model) is used. These default strings are the base translation.

Warning: make sure to translate the entire model in a given language to avoid partially translated user interfaces.

Translation Bundles

Strings translation is performed using Translation Bundles, attached to model editions. A translation bundle is a properties file that contains a list of key/value pairs corresponding to the strings localized in a given locale. The translation bundle file is named translations_<locale>.properties, where is the locale of the translation.

The following example is a sample of a translation bundle file for the English language ( translations_en.properties). In this file, the label for the Employee entity is the string “Staff Member”, and its description is “A person who works for our company”.

...
Entity.Employee.Label=Staff Member
Entity.Employee.Description=A person who works for our company.
Attribute.Employee.FirstName.Label=First Name
Attribute.Employee.FirstName.Description=First name of the employee
Attribute.Employee.Picture.Label=<New Key TODO>
...

Translating a Model

To translate a model:

  1. The translation bundles are exported for the language(s) requiring translation in a single zip file.
  2. Each translation bundle is translated by a translator using his translation tooling.
  3. The translated bundles are re-imported into the model edition (either each file at a time, or as a single zip file).

To export translation bundles:

  1. In the Model Editions view ( Model Administration perspective), expand the model edition that you want to localize.
  2. Right-click and then select Export Translation Bundles.... The Export Translation Bundles wizard opens.
  3. Select the languages that you want to translate.
  4. Select Export Base Bundle if you also want to export the base bundle for reference. The base bundle contains the default strings, and cannot be translated.
  5. Select the Encoding for the exported bundles. Note that the encoding should be UTF-8 unless the language that you want to translate or the translation tooling has other encoding requirements.
  6. Select in Values to Export the export type:
  7. Select in Default Values the value to set for new keys (keys with no translation in the language).
  8. Click the link to download the translation bundles in a zip format and then Close to close the wizard.

To import translation bundles:

  1. In the Model Editions view ( Model Administration perspective), expand the model edition that you want to localize.
  2. Right-click and then select Import Translation Bundles.... The Import Translation Bundles wizard opens.
  3. Click the Open button and select the translation file to import. This file should be either a properties file named translations_<locale>.properties or a zip file containing several of these properties files.
  4. In the Language to Import table, select the language translations that you want to import.
  5. Select the Encoding for the import. Note that this encoding should correspond to the encoding of the properties files that you import.
  6. Select Cleanup Removed Keys During Import if you want to remove the translations for the keys that are no longer used in the model. This cleanup remove translation no longer used by the model.
  7. Click Finish to run the import.

The translations for the model edition in the selected languages are updated with those contained in the translation bundles. If the Cleanup Removed Keys During Import was selected, translations in these languages no longer used in the model are removed.

Translation and Model Edition Lifecycles

The lifecycle of the translations is entirely decoupled from the model edition and deployment lifecycle:

Tip: Decoupling the translation lifecycle from the model edition avoids binding the critical model development and release process to the translation process, as the latter frequently is managed by a separate team. This also allows adding new translations or fixing translations without having to re-deploy a new model edition.

Warning: When creating a new model edition, the translations from the previous model edition are not copied to the next edition. It is necessary to export and import translations between editions.