Stumped with Migration to Magnolia 4.5 or Magnolia 5? Add your question as a comment on this page.

General

How long does it take to migrate my project?

It really depends on how your project is structured and how many of Magnolia provided components, templates or dialogs do you use. It is our aim that migration should not take more then 20% of the time initially invested into your project. We are updating documentation and preparing tooling to make sure majority of the projects should fit within this margin.

There is a tool which can help you estimate the amount work by listing differences between your project and clean instance.

Do I need to migrate every Author and Public instance I have?

You definitively need to migrate your author instance and at least one public instance. The rest of your public instances you can just re-create from the one you have migrated or you can migrate them as well, depending what is less effort in your situation. We provide set of scripts and tools to help you with the migration, if you follow those scripts and write your own migration tasks along what we provide as additional scripts or additional blocks of code in existing scripts, you should be able to perform migration automatically on any instance hosting your project you choose. This should make it easy and simple to test migration process in development environment and then re-run it in your QA, test and production environments on all the instances you have.

How do I update my Eclipse based webapp?

Similarly to any other updates. You need to change dependencies from the old versions of modules to the new ones. If your project in eclipse is Maven based, it should be as simple as updating the pom with correct version (plus adding the migration module) and then following steps described on the Using the migration tool page.

Which Magnolia versions are recommended for the migration?

We recommend to use the following Magnolia versions before executing the migration process:

• From Magnolia 4.4 to Magnolia 4.5: Magnolia 4.4.6+
• From Magnolia 4.5 to Magnolia 5: Magnolia 4.5.12+

If you are using a previous version, please upgrade to the latest one.

We are using Magnolia CE, which versions are relevant in my case?

If you are using Magnolia CE, the same versions recommendations apply.

Can we skip the first migration step from Magnolia 4.4 to 4.5?

No, the migration from Magnolia 4.4 to 5 must be executed into two distinct steps:

• From Magnolia 4.4 to 4.5
• From Magnolia 4.5 to 5

Do you recommend migrating from 4.5 to 5, or do a complete new build of the site using 5?

It really depends on the complexity of your project or your customizations. You will have to estimate and compare the cost of a migration against a reimplementation. Do not hesitate to contact us, we can help you to assess those estimations. 

We would like to see a sample for a VersionHandler ?

Here are two samples of version handlers:

• From Magnolia 4.4 to 4.5

  final Delta deltaFor1019 = DeltaBuilder.update("1.0.19", "All updates for 1.0.19")
      .addTask(new SimpleSTKRelatedModuleMigrationTask("Migration task: Migrate Config", "Migrate Configuration", "acme-website", false, Arrays.asList("/modules/extended-templating-kit/config/sites/home")))
      .addTask(new ContentModuleMigrationTask("Migration task: Migrate Content", "Migrate websiteContent",  "acme-website", "website", Arrays.asList("/home"), false, true));
   
  register(deltaFor1019);
  
  

• From Magnolia 4.5 to 5

  final Delta forMigrationTo5 = DeltaBuilder.update("2.0", "")
          // DMS Migration
          .addTask(
                  new IsModuleInstalledOrRegistered("Migrate DMS Repository to DAM", "", "dms",
                          new MoveDataWorkspaceToDamMigrationTask("Migration task: Migrate DMS content to DAM", "Migrate DMS to DAM",
                                  Arrays.asList("/resto", "/demo-docs"), null, "dms")))
          .addTask(
                  new IsModuleInstalledOrRegistered("Change Website reference", "", "dms",
                          new ChangeWebsiteDmsReferenceToDamMigrationTask("Migration task: Migrate Identifier ID to point to DAM", "",
                                  "website", Arrays.asList("/home"))))
          .addTask(
                  new MoveContentToDamMigrationTask("Migration task: Migrate Uploaded content to DAM repository", "",
                          "website", Arrays.asList("/home"), "/moved_uploaded", null))
          .addTask(
                  new MoveFCKEditorContentToDamMigrationTask("Migration task: Migrate Uploaded content to DAM repository", "",
                          "website", Arrays.asList("/home"), "/moved_uploaded_fck", null))
          .addTask(
                  new CleanContentForDamMigrationTask("Migration task: Clean Content repository", "",
                          "website", Arrays.asList("/home")))
          .addTask(
                  new MoveAclPermissionsBetweenWorkspaces("Move ACL define for the DMS workspace to the DAM workspace", "",
                          "dms", DamConstants.WORKSPACE, null, false))
          // DATA migration
          // needed because image are now in DAM and reference must be updated.
          .addTask(new ChangeWebsiteDmsReferenceToDamMigrationTask(
                  "Migration task: Migrate Identifier ID to point to DAM", "Of Data module", "data", Arrays.asList("/recipe")))
  
  		// Move image from Data To Dam
          .addTask(new MoveContentToDamMigrationTask(
                  "Migration task: Move image of Recipe from Data To Dam", "Migrate Data to DAM", "data", Arrays.asList("/recipe"), "/moved_from_data", null))
  
  		// MoveFileContentToDamMigrationTask
          .addTask(new MoveFileContentToDamMigrationTask(
                  "Migration task: Move image uploaded by a 'file' or 'dataFile' control from Data To Dam", "Migrate Data to DAM", "data", Arrays.asList("/recipe"), "/moved_from_data2", "photo"));
  register(forMigrationTo5); 

  Additional details and explanations can be found inside the Migration exercise 4.4 to 4.5 or the academy course M8 Project migration.

Should I update the version of the magnolia modules in the pom file?

Yes, if you are migrating from Magnolia 4.4 to Magnolia 4.5. The Release notes can help you to identify which module versions must be declared inside the dependencyManagement section of your pom file.

No if you are migrating from Magnolia 4.5 to Magnolia 5. We are now using the maven import scope which will automatically load the correct module versions.

In order to use this feature, declare this dependency inside your parent pom file:

<dependency>
    <groupId>info.magnolia.bundle</groupId>
    <artifactId>magnolia-bundle-parent</artifactId>
    <version>${magnoliaVersion}</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>

Do you have any recommendations about browser compatibility for the different versions?

Please see the certified browsers

Migration to Magnolia 4.5

Templating and STK

How can I migrate non-STK based websites?

If your website does not use STK but still uses basic templating, you need to migrate it. Follow the process for migrating STK-based websites. Perform the following steps:

1. ID creation
2. Update primary type
3. Update template ID

Complete step 4 "Transform" if you changed the structure of your template definitions in the three steps above. The content structure must match the template definition structure. See the STK example in step 4 where we modified the template definition by moving breadcrumb to another area. Did you do a similar change in your template definition? If yes, then structure the content correspondingly.

Is the old-way templating still supported?

No, old-way templating is not supported on 4.5. If you want to migrate to 4.5, you need to update your templates. Magnolia ships magnolia-4.5-migration.jar module in the add-ons folder of the bundle that should assist you with migrating your configuration. We are also in the process of preparing another module that will assist also with the migration of the template scripts. More on this on conference in September.
If you desperately need to run old templates and Magnolia 4.5 together, we have started an effort to bring up old templating engine in Magnolia 4.5. This effort is (will be) shared on Forge as a set of magnolia-compatibility-* modules. Even though we provide initial code to kick-start this effort, old templating engine is by no means supported in Magnolia 4.5 by Magnolia. This project is purely community driven and whether it will live or not depends on the interest of community and number of contributors that will jump in to finish the effort.

Will my projects in their present form work after the update?

If your project provides templating features, either based on basic templating or the STK, it will not work without migration. If you don't use any templating feature, your project likely does not need to be migrated.

Is there only a change in the structure of the definition of the templates or also in the structure of the content?

 The definition of the templates and the content in the website have a new JCR structure and must be migrated.

Template scripts, JSP and Freemarker

How is it with the jsp support?

JSP is still supported on Magnolia as much as before. However old tag libraries have been replaced with the functions that provide same or better functionality. See Tags migration for 4.5 for details on what replaces which tag. Those tags that are without replacement will be still supported.

Does Magnolia offer the same set of helping functions exposed to jsp scripts, as it does for freemarker?

Yes, underlying functions have exactly the same code. This was not always the case prior Magnolia 4.5, but now functions provided by Magnolia to Freemarker and to JSPs are exactly the same. The only limitation is for those functions that are overloaded. Unfortunately JSP doesn't support overloading of the functions yet so we had to choose most useful function to expose in JSP for those that are overloaded. However you are still able to access underlying class in JSP and execute other variants of the functions directly in the JSP scriptlet so you are not missing out on any of the functionality.

Page editor and the implicit rendering of bars, how does it work? How can I force a new/edit bar to be rendered explicitly?

The bar tags have been deprecated. Bars are now injected into editable areas and components automatically. If you have a case where the bars are not injected as you wanted, such as due to an unusual layout, you have the possibility to mark an HTML element inside the area. A bar is injected into the marked element.

Here is an example what the markers look like:

<ul>
    [#list components as component ]
        [@cms.component content=component /]
    [/#list]
    [#if cmsfn.editMode]
	    <li cms:add="bar"></li>
    [/#if]
</ul>

The cms:add="bar" is a marker. It tells the page editor to inject the edit bar inside the <li> element. You can pass two possible arguments: bar or box. bar is only the bar, like in the /templating-kit/components/links/linkListArea.ftl script. box adds a placeholder box below the bar.

How do I access node's properties in scripts? Is the dot notation still supported?

Groovy

When calling piece of Java code in a Groovy script you can use the API of the specific library. To get a property of a node use:

node.getProperty("propertyName")

The output of this method will be of type Property from which you can get the value of a desired type. For example:

MgnlContext.getJCRSession("website").getNode("/site1/page1").getProperty("text").getValue().getString()

This will output a string representation of the property text located under the page1 node.

Freemarker

${ctx.getJCRSession("website").getNode("/site1/page1").getProperty("text").getValue().getString()}

The ctx templating support object is in this case MgnlContext.

Is there a similar functionality to universal stkfn.homeLink when I don't use STK?

You can use the following functions that are exposed in the cmsfn tag for this: ${cmsfn.link(cmsfn.root(content, "mgnl:page"))}.

Is there any successor of cmsu.simpleNavigation tag that would allow you build the navigation easily up?

Not right now (Jul 20, 2012) but replacement functionality will be provided. Watch the Tags migration for 4.5 page.

How can I replace cms.contentNodeIterator, cms.query and cms.out tags, eventually the actpage object?

The cms.contentNodeIterator, cms.query and cms.out tags are deprecated. See Tags migration for 4.5 for replacement functionality.

Others

How can I set the instance up to get it working again?

Follow the Migration process of module configuration and websites.

Is this or that Magnolia module migrated to 4.5? When can we expect that one or all of them?

The 4.5.x modules migration page gives you the migration status for modules maintained by Magnolia. Community contributed modules on the Forge are not included in the list. If you depend on a non-listed module, contact the module author.

How can I get a node by identifier when it's not provided by TemplatingFunctions?

As before you can access context and from context you can access JCR session on given workspace to retrieve the node you need. ${ctx.getSession("data").getNodeByIdentifier("1234-123456-...")}

My login / adminCentral are not working after the automatic config migration tasks, what happened?

Make absolutely sure that you are not using any old/outdated pre-4.5 code fragments anywhere anymore. Also check the classes folder for eventual hot fixes/patches.

What is the best way of migrating the jackrabbit and JAAS configuration files?

You can update the configuration files manually or run the mprop.py Python script available in the add-ons folder of  magnolia-4.5-migration bundle. If you are using several public instances, the script will reduce the operation risk. Do not hesitate to edit the script in order to fit your requirements.

Migration to Magnolia 5

General

Will it be possible to directly migrate from 4.5 to 5.3 ?

Yes, this migration process applies whatever the Magnolia version is. Please use always the latest Magnolia version.

Is page version history migrated?

No. Versions in JCR are defined as "Not mutable/changeable dataitems". Non-mutability has the benefit that when a node is versioned you can be sure it reflects the state when the version was made. But non-mutability also has a downside: when content structure changes, old versions are no longer renderable.

We changed the structure of meta:data from a subnode to a mixin between Magnolia 4.5 and 5. For migration this means versions created in 4.5 cannot be migrated as they are not changeable. This is a general versioning issue that occurs whenever the content structure changes. For example, if you decide to rename an area and update the page's content to the new area name, the old version won't be renderable anymore. Your current scripts will try to render an area of the new name and not the old name.

You can restore old versions that were created before the content structure was changed but the restored content cannot be rendered.

Workflow

Can the workflow be migrated using scripts?

No, we do not provide any migration script to convert an OpenWFE workflow into jBPM. You must rewrite your workflow using the jBPM framework if you are using a custom workflow. Please see the official documentation for more information.

Dialogs

Is Blossom impacted by the migration?

 Yes, if you are using Blossom to define your dialogs, your code must be updated in order to reflect the changes in the structure of the dialogs.

Digital Asset Management (DAM)

After migrating to Magnolia 5, what happens to my assets stored inside the DMS workspace, should I remove them manually?

The task MoveDataWorkspaceToDamMigrationTask is responsible for moving the assets from the DMS to the DAM workspace. If you call this task inside your module's version handler, your assets will be automatically migrated, no need to remove them manually from the DMS. Note that the DMS workspace itself won't be deleted.

The DMS workspace remains in place after migration. Is it visible through the v5 UI to retrieve anything that has not been migrated correctly?

Yes, the DMS workspace is still visible in the Magnolia UI. You can use the developer tool JCR Query to check the content of this workspace.

Templating

How can i use the DAM Templating functions because most of the STK Functions are deprecated in M5?

For Magnolia 5 all getAsset... templating methods provided by STKTemplatingFunctions are deprecated. Use the new get... methods provided by DamTemplatingFunctions instead.

[#assign asset = damfn.getAssetForId(content.link)]
[#assign assetMap = damfn.getAssetMapForAssetId(content.link)]

AssetMap provides access to Asset and metadata properties using DamTemplatingFunctions. For example:

[#assign assetMap = damfn.getAssetMapForAssetId(content.link)]    
 
<br>assetMap.title = ${assetMap.title}
<br>assetMap.metadata.dc.title = ${assetMap.metadata.dc.title}

Data types and Content Apps

We have many custom data types in our project. Can this be migrated easily to the new contentApp? Are there any migration task?

The data module is in charge of migrating all data types including their dialogs. No need to call any specific task. At the end of the migration, each data type will have its own Content App created automatically.

Authors can't see the Content Apps created by the Data module at the end of the migration?

By default, the migration of the Data module does not set any permissions to the Content Apps. You will have to set them explicitly inside your version handler using the task SetPropertyTask.

Infrastructure

Reloading a page in the editor causes a 404 error

When you open a page for editing and reload it in the browser, an extra semicolon is added to the URL fragment and the server returns a 404 error. Every subsequent reload adds another semicolon. This issue occurs with older versions of the Tomcat application server. To resolve this issue, upgrade to Tomcat 7.0.47+.

Which Tomcat version should I use with Magnolia 5?

We recommend to use Tomcat 7.0.47 in order to avoid the issue described here: MGNLUI-2426 - Getting issue details... STATUS .