Page tree
Skip to end of metadata
Go to start of metadata

Module for migrating definitions from M5.X UI to M6.2 UI.


Only Dialogs are currently supported.


Installation

Maven is the easiest way to install the module. Add the following dependency to your bundle:

<dependency>
  <groupId>info.magnolia.migration</groupId>
  <artifactId>migration-tools</artifactId>
  <version>1.0.1</version>
</dependency>

Versions

1.0.1 Magnolia 6.2

Features

This module includes a content app called migration tool, which is registered in the Edit menu:

The app lists all definitions with UI5 elements registered in Magnolia:

Definitions can be filtered out by:

  • Title
  • Module
  • Origin
  • Problem Severity

A single definition can be previewed before the migration (5UI)

And after the migration 6UI

The migration of all definitions can be done at once with the action "Migrate Dialogs"

All definitions will be saved as YAML files inside the light modules registered folder, in a subfolder called "migration". Inside this folder there will be a subfolder for each module that contains a migrated definition and the YAML will be inside:

~/magnolia/light-modules/migration $ tree .
.
├── angularEndpoints-light-module
│   └── dialogs
│       └── components
│           ├── edwin.yaml
│           ├── edwinDouble.yaml
│           ├── edwinLink.yaml
│           ├── edwinLinkContent.yaml
│           ├── edwinLinkPath.yaml
│           ├── edwinMultiText.yaml
│           ├── edwinMultivalue.yaml
│           ├── edwinOption.yaml
│           ├── edwinSelect.yaml
│           ├── edwinSwitchable.yaml
│           └── edwinUpload.yaml
├── commenting-app
│   └── dialogs
│       ├── edit.yaml
│       └── view.yaml


The converted YAML files will include as comments the original definition and the decorations processed. Example converted definition:

/test-module/dialogs/components/dialog.yaml
label: Test Dialog Decorated 2
width: medium
form:
  name: Test Dialog Decorated 2
  properties:
  - name: doubleText
    label: Test Title
    type: java.lang.Double
    converterClass: com.vaadin.data.converter.StringToDoubleConverter
    $type: textField
# form:
#   label: Test Dialog
#   tabs:
#     - name: tabMain
#       label: Test Content
#       fields:
#         - name: doubleText
#           fieldType: text
#           label: Test Title
#           type: Double
# actions:
#   commit:
#     label: save changes
#     class: info.magnolia.ui.admincentral.dialog.action.SaveDialogActionDefinition
#   cancel:
#     label: cancel
#     class: info.magnolia.ui.admincentral.dialog.action.CancelDialogActionDefinition
#
#
#
# Decorations found:
# /test-module1/decorations/test-module/dialogs/components/dialog.yaml/
# /test-module2/decorations/test-module/dialogs/components/dialog.yaml/

FAQS

What if my definition is decorated?

The migration tool converts definitions in the registry. The migration process will take into account all decorations applied to the original definition. The converted YAML will include as addional info the decorations processed by the registry.

What if my definition uses include files?

The files included will be converted into a unique YAML file, since, the migration tool converts definitions in the registry (which already applies all includes in one final definition). The migration tool does not override the original definition files(s), so you can easily recreate the previous structure of include files using the data from the converted YAML.

What if my definition uses inherits?

The converted YAML will not keep the inherit structure. The migration tool converts definitions in the registry. The migration process will take into account all inherits applied to your definition and produce a fully expanded YAML file, repeating the configs inherited. The migration tool does not override the original definition files(s), so you can easily recreate the previous structure of inherits using the data from the converted YAML.

What if I use blossom definitions?

Blossom definitions are not fully supported by the definitions app and the registry, which is used as a datasource in migration tool app. Since Blossom dialogs can't be detected, the migration tool app cant migrate them.

Warnings

  • This module is at INCUBATOR level.

Changelog

  • Version 1.0 - Initial release of the module.
  • Version 1.0.1 - decorations processed included as part as the converted YAML file.
  • No labels

2 Comments

  1. What happens if a definition cannot be properly converted - for example it uses a custom field?
    It seems this would be important/helpful to callout in a clear way. Maybe in comment in yaml with searchable text 'COULDNOTCONVERT' Maybe in Magnolia UI - "4 definitions could not be converted"? Maybe as an additional text file in the export? "couldnotconvert.txt"?

    1. I have tested two scenarios where a definition cannot be properly converted (there could be more tbh):

      1.- The old definition has SEVERE problem detected by the registry/Definitions app. In this case the tool will skip these definitions since there is no proper way to convert something that is not properly configured. When this happens the module will place an info message in the logs:

      log.info("Definition with SEVERE problems found and won't be processed: " + ((DefinitionBean) registry).getTitle());
      2.- A custom field was used and the "converter" from the companitbility module doesnt support it. In this case a non working field is generated with the following description:
      description: No converter for old class info.magnolia.ui.form.field.definition.ConfiguredFieldDefinition.
      Its a nice idea what you suggest (summary in comments/txt file) for not converted fields but this will depend on how these exceptions are handled in the converter util (info.magnolia.ui.form.definition.DefinitionConverter) which resides outside (magnolia-ui-framework-compatibility).