Goal
- Your project is updated with the changes that happened between 4.5 and 5.
- You have a task in your version handler for each migration task covered by the migration tool.
- You have a task in your version handler for each custom migration task that is not covered by the migration tool.
Process
Follow this process for migrating from 4.5 to 5:
- Update project dependencies to match 5.x dependencies.
- Update deprecated code if your IDE turns red.
- For all the topics you identified in your analysis.
- Add the corresponding migration tasks in the version handler of your modules as shown below.
- Create your own migration tasks for things that are not covered by the migration tool such as defining a custom workflow.
- Start Magnolia for the first time on the saved repository and check the migration result.
- Improve your version handler by adding post-migration tasks. For example, grant permissions to the apps that were created during Data module migration.
- Add tasks to remove old configuration such as the Extended Templating Kit (ETK) module.
- Test your migration tasks again on the saved repository until your are happy with the result.
- Test your migration tasks with data from production.
- Build your WAR file.
Update project dependencies
What changed:
- Some group and artifact IDs changed.
How to migrate:
- Update dependencies in your project POM file to match the changed group and artifact IDs.
Update group IDs
Group IDs of the following artifacts have changed. Update dependencies in your project POM.
Artifact | Old group ID | New group ID |
---|---|---|
CE bundle | info.magnolia | info.magnolia.bundle |
Enterprise webapps | info.magnolia | info.magnolia.eebundle |
<dependency> <groupId>info.magnolia.bundle</groupId> <artifactId>magnolia-bundled-webapp</artifactId> </dependency>
<dependency> <groupId>info.magnolia.eebundle</groupId> <artifactId>magnolia-enterprise-webapp</artifactId> </dependency>
Update module artifact IDs
Artifact IDs of the following modules have changed. Update dependencies in your project POM.
Module | Old name | New name |
---|---|---|
Multisite | extended-templating-kit | magnolia-module-multisite |
DAM | magnolia-module-dms | magnolia-dam |
<dependency> <groupId>info.magnolia.multisite</groupId> <artifactId>magnolia-module-multisite</artifactId> <version>1.0</version> </dependency>
Update deprecated code
If your IDE turns red, update the deprecated code. Enable warnings on deprecated API. Here is an example from Eclipse.
Deprecated code to look for:
- DAM asset manipulation. See Migrate DMS to DAM below.
- Command interface changed.
- Old workflow code
Migrate dialog definitions
What changed:
- Dialog definition structure:
How to migrate:
- If you have custom save handlers, replace them with a custom action or a custom property transformer.
- If you have custom controls, replace them with an existing Vaadin field or create a custom field. See Concept - Dialog Migration from 4.5.x to 5.x for scenarios and code examples.
Add a dialog migration task to your version handler.
DialogMigrationTask in version handler.addTask(new DialogMigrationTask("your_module_name"));
Migrate metadata to mixin node types
What changed:
- Metadata used to be stored in subnodes. It was replaced with special mixin node types. This change was implemented in the Magnolia node type definition.
- Same name sibling nodes are no longer allowed.
How to migrate:
- If you have custom code the uses JCR queries to search for metadata such as
metaData/template
, rewrite these queries. The Magnolia core module contains a metadata migration task that is triggered during the update. You don't need to add it to your version handler.
ConvertMetaDataUpdateTask in version handler.addTask(new ConvertMetaDataUpdateTask("Convert meta data", "Done on all workspaces."))
Same name sibling nodes are no longer allowed. This restriction was implemented in the Magnolia node type definition. The migration tool performs this update automatically for all Magnolia workspaces. If you have custom workspaces, add the following task to your version handler.
IdentifySameNameSiblingNodesTask in version handler.addTask(new IdentifySameNameSiblingNodesTask("your_custom_workspace", "/", "nt:base"));
The task accepts the following attributes:
-
workspace
: Your custom workspace name. -
path
: A valid path in the workspace. Use/
to find everything under the workspace root. -
node type
: A valid JCR node type. The query goes through all node types but the results are filtered to the type you specify. Usent:base
as a "wildcard".
-
For details and usage examples see Concept - metaData content & nodeTypeDefinition migration task.
Migrate DMS to DAM
What changed:
- New module
magnolia-dam
replaced themagnolia-module-dms
module. - New workspace
dam
replaced thedms
workspace. - All assets such as images and videos should now be stored in the DAM. There is no possibility to store an asset directly in website content by uploading it directly or by uploading in the CKEditor.
How to migrate:
- If your code manipulates assets, rewrite it to use the new DAM API.
Example: DAM API usage
Old code | New Code |
---|---|
| "data" |
| // First inject in your constructor:
// Then
|
DAMSupport.VARIATION_ORIGINAL | ImagingSupport.VARIATION_ORIGINAL |
[#if model.caption??]${model.caption}[/#if] | The behavior of the asset returns by In this example, [#if content.imageCaption?? || model.caption??]${content.imageCaption!model.caption}[/#if] |
- Add the migration tasks shown below into your version handler. The tasks will:
- Move assets from
dms
workspace todam
workspace. - Move assets from
website
workspace todam
workspace. - Move uploaded assets to
dam
workspace. - Update UUID references so they point to the asset's new location.
- Update permissions (ACLs) from DMS to DAM.
- Move assets from
The example tasks below are for a typical website where binary content resides all over the place: in the DMS, in the website and in the FCKEditor. You may not need to add all these migration tasks in your version handler. See Usage of the DMS to DAM migration task for a complete list of tasks.
Post-migration task:
- Organize your DAM assets. The migration tool moves assets from the
website
workspace to the DAM. The structure created by the migration tool follows the old website workspace structure, which is probably not what your editors expect. Go to the DAM app and re-organize the assets in a way that makes sense. - The old
dms
workspace and its configuration are still present. We recommend that you check that all the configuration and assets are correctly moved and then remove the old workspace and configuration with a dedicated task in the version handler.
Recreate workflow
What changed:
- jBPM workflow engine replaced the OpenWFE engine. You need to recreate any custom workflow definitions you have.
Before you start:
- Get familiar with jBPM and the BPMN2 workflow modeler. Read Magnolia's workflow documentation and jBPM documentation.
- Activate everything.
- Check that there are no running workitems left in the repository.
How to create a new workflow definition:
- See Workflow on how to work with the new jBPM workflow engine.
Replace custom data types with content apps
What changed:
The Data module should not be used anymore. Replace your custom data types with content apps.
Magnolia has already replaced the demo data types (Contact, Company, RSS, Category) with content apps.
How to migrate:
- The Data module will create a new content app for each of your custom data types during the update.
- It stores the new app configuration in
/modules/data/apps
. - It stores the app data in the
data
workspace.
- It stores the new app configuration in
- If you used images from the DMS with your data items:
- Move the images to the
dam
workspace withMoveDataWorkspaceToDamMigrationTask
. - Update the references in the data workspace with
ChangeWebsiteDmsReferenceToDamMigrationTask
.
- Move the images to the
- If you used images that were uploaded and stored in the
website
workspace using the dam control:- Use
MoveContentToDamMigrationTask
to move the images to the DAM.
- Use
- If you have JCR queries in your code, rewrite them.
- If you have custom menu items in AdminCentral that display pages, replace the pages with content apps or standard apps. You need to create the apps yourself.
Example:
Documentation:
Post-migration tasks:
Once the migration task are completed, you can work with your data in content apps. But you can make the migration even better.
- Add a task to move the content of each data type out of the
data
workspace to a dedicated workspace.- Register the workspace upfront in your module descriptor.
- Task:
info.magnolia.ui.contentapp.setup.AbstractDataTypeMigrationTask
. - Implementation example:
info.magnolia.module.categorization.setup.migration.CategorizationDataTypeMigrationTask
- Update the content app's workbench definition and editor definition and any field definitions (e.g. Link) with the new workspace.
- Update access control lists .
- Set correct permissions to the content app in the app descriptor and app launcher layout.
Starting with Magnolia 5.4, the Data module is no longer included. If for any reasons you still have a dependency to this module after the migration, you must update your pom file to explicitly include this module in your project. It can be the case if you decided to not migrate your import handlers.
Clean up obsolete configuration and workspaces
After the update to 5 you still have obsolete configuration for the DMS and ETK modules. We recommend that you verify that everything is moved to its new place and then remove the configuration with info.magnolia.module.delta.RemoveNodeTask.
Move ACLs
If you move content from one workspace to another, add a task in your version handler to grant permissions to the new content, for example:
.addTask(new MoveAclPermissionsBetweenWorkspaces("Move ACL define for the DMS workspace to the DAM workspace", "", "dms", DamConstants.WORKSPACE, null, false))
You then also need a dependency to magnolia-security-app:
<dependency> <groupId>info.magnolia.security</groupId> <artifactId>magnolia-security-app</artifactId> <version>5.2-SNAPSHOT</version> </dependency>
When you replace AdminCentral pages with content apps, convert the ACLs:
.addTask(new ConvertAclToAppPermissionTask("Convert permissions for 'Categories' app", "Convert ACL permissions for old 'Categories' menu to new 'category' app permissions.", "/modules/adminInterface/config/menu/data/category", "/modules/categorization/apps/categories", true))
6 Comments
Cedric Reichenbach
This article doesn't explicitly say that, but before starting DMS -> DAM tasks, you need to
Is that correct? If so, maybe you could add this to the article.
Cheers,
Cedric
Magnolia International
Your Magnolia 4.5 must have the DMS module installed for technical reasons. Even if you don't have any assets managed by the DMS in 4.5.
In Magnolia 5, you should not have any DMS module, since you have removed its dependency. See 10Migratefrom45to5-UpdatemoduleartifactIDs
However, the DMS workspace will still be available, but it should be empty.
Yann Roth
Possible lack of information in Update group IDs:
Is it possible that you forgot to mention that the bundled webapp now has a new id info.magnolia.bundle ?
Would be great to complete the documentation!
Antti Hietala
Hi Yann, CE bundle group ID changed in Magnolia 5.2. Added to Update group IDs section. Thanks for noticing!
Daniele Biagi
"This change was implemented in the Magnolia node type definition." look above in the page, the link to node type definition is broken
Christoph Meier
Thank you Daniele for spotting this one.
I have fixed the link to the node type definition.