®

@MAGNOLIA_CMS 2

Best Practices for Migrating to Magnolia 5

@MAGNOLIA_CMS 3

Nicolas BarbéSenior Consultant

@MAGNOLIA_CMS 4

AgendaWhy Make the Move? Navigate With our Expertise Migration Overview Recommendations Migrating from 4.4 to 4.5 Migrating from 4.5 to 5

@MAGNOLIA_CMS 5

Why Make the Move?Latest Features

Intuitive Interface (Desktop or tablet devices) Apps framework Pulse and Favorites REST API jBPM workflow Personalization DAM and CMIS integration JCR agnostic App

@MAGNOLIA_CMS 6

Navigate With Our ExpertiseServices

Migration Audit Migration Workshop Migration Assistance

Magnolia Conference 2015 Migration Workshop

Free Resources Documentation documentation.magnolia-cms.comAcademy academy.magnolia-cms.com

Preparation is the Key!

@MAGNOLIA_CMS 8

Migration OverviewMagnolia

4.4Magnolia

4.5Magnolia

5.3

• New Security Layer • Content API deprecation • STK new concepts • Templating changes

• DMS replaced by DAM • Data module

deprecation • New dialogs layout

Recommendations

@MAGNOLIA_CMS 10

Recommendation #1 Clean your data

Before migrating, remove all obsolete content, duplicated information especially if this information is already stored in an external master system.

Migrating obsolete or non-critical data adds complexity, increases the risk of your project and slows down the migration process.

@MAGNOLIA_CMS 11

Recommendation #2

Build a "test" repository

Building a test database is cheaper than restarting the production database several times a day. In

addition, a test database can be enriched with any specific use cases.

@MAGNOLIA_CMS 12

Recommendation #3 Test your migration on a real production

repository Don’t wait until the last minute to test your migration on a real production environment.

Newly identified issues must be reported into your test database.

@MAGNOLIA_CMS 13

Recommendation #4

Use Version Handlers

Understanding and using version handlers

correctly is mandatory if your migration

cannot be done in a single step in production.

@MAGNOLIA_CMS 14

Recommendation #5 Crawl your website

Don’t open each individual web page to test your project.

Crawl the website automatically and track any stack-traces in the

catalina.out log file.

@MAGNOLIA_CMS 15

Recommendation #6Involve your editors

Magnolia 5 is a big change for the end-users. Involve them at the beginning of the project.

Refine the initial requirements and define acceptance tests up-front. This will guide you during the migration

project.

@MAGNOLIA_CMS 16

Recommendation #7

Test Campaign Drive a test campaign with your end-users before the

Go-Live.

@MAGNOLIA_CMS 17

Last Recommendation

Read the migration logs

Most of the issues can be anticipated

with a detailed analysis of the first

migration logs. WARN and ERR log

levels must be read carefully.

@MAGNOLIA_CMS 18

From 4.4 to 4.5

@MAGNOLIA_CMS 19

What has changed?New templating mechanisms

Explicit Area New tags and templating functions

New STK API Node API replacing the Content API New security layer

@MAGNOLIA_CMS 20

New templating mechanismsTemplating mechanism improvements

Template definitions and scripts are deeply impacted by these new features and must be migrated.

Explicit Area Additional tags

- @cms:init - @cms:area - @cms:component

Templating functions - cmsfn - stkfn

Structural changes in the template definition

@MAGNOLIA_CMS

STK API evolves to introduce new concepts

MagnoliaTemplatingUtilities & STKUtil is deprecated and must be replaced:

- STKTemplatingFunctions (stkfn) - TemplatingFunctions (cmsfn)

21

New STK API

Deprecated Class ReplacementSTKTemplate STKPage

ParagraphManager TemplateDefinitionRegistry

TemplateManager TemplateDefinitionRegistry

Paragraph TemplateDefinition

Template TemplateDefinition

@MAGNOLIA_CMS 22

javax.jcr.Node APIjavax.jcr.Node is the recommended approach to manipulate any JCR content The Content API is now deprecated

Content API Node APIContent Node

NodeData Property

ContentFilter Predicated

ContentVersion VersionNode

Convenient methods exist to switch between both APIs

@MAGNOLIA_CMS 23

Security Changes

Authentication and authorisation are directly managed by the JCR

Jackrabbit settings must be updated

@MAGNOLIA_CMS 24

Migration Process

Update configuration

and code

Update repository and

webapp

Run the migration tool

Work on the delta

Test Go Live

Finalize

4.4 4.5

Start Magnolia !

@MAGNOLIA_CMS 25

Step 0 - Prerequisites Your Magnolia instance must use at least the version 4.4.6

Upgrade your Magnolia instance to the latest version (4.4.13) if you are using a version below 4.4.6

@MAGNOLIA_CMS 26

Step 1 - Update Configuration and Code 1. Update your pom files

• Magnolia Version : The latest one (4.5.23) • Update your module dependencies • Update artifact and group Ids

2. Update deprecated code (Javadoc) and API replacements (documentation).

3. Update your module descriptor 4. Add the migration tasks to your version

handler • Migrate content : ContentModuleMigrationTask • Migrate definition

• TemplatingRelatedModuleMigrationTask • SimpleSTKRelatedModuleMigrationTask

@MAGNOLIA_CMS 27

Step 2 - Update Repository and Webapp

1. Update security definition in the web app and the repository • Jackrabbit security • JAAS config

2. Update web.xml

3. Backup your repository

A script can be used to automate those modifications

Use only this backup for the rest of the process

@MAGNOLIA_CMS 28

Step 3 - Start Magnolia

Start Magnolia!

What’s happening? Each Magnolia module is migrated Your module is (partially) migrated

Your template scripts must be migrated

@MAGNOLIA_CMS 29

Step 4 - Run the Migration Tool Run once the migration tool to update your template scripts

A migration report is generated

Nothing is magic - The migration tool only migrates well-known patterns. Specificities must be migrated manually.

@MAGNOLIA_CMS 30

Step 5 - Work on the DeltaIterate through every page on the test repository One iteration covers one page Open the page and identify what is broken

Update the template script Update the configuration (Version Handlers) Update the content (Version Handlers) Update your code

@MAGNOLIA_CMS 31

Step 6 - TestUse your production content Test strategies

- Crawl and compare the result - Acceptance tests - Test campaign involving the end-users

Any issue? - Add the use-case to your test-repository - Go back to Step 5 and enrich the version handler

@MAGNOLIA_CMS 32

Step 7 - Finalize the MigrationUpdate your bootstraps in your project

Configuration Samples

Build and release your project

You are now ready to deploy your project on production!

@MAGNOLIA_CMS 33

From 4.5 to 5

@MAGNOLIA_CMS 34

What has changed?Dialog Definition DMS replaced by DAM Metadata as a Mixin Content App instead of Data module New workflow engine

@MAGNOLIA_CMS 35

Dialog Definition

If you are using Blossom, your code is also impacted by this change.

@MAGNOLIA_CMS 36

Digital Asset Management

All assets are centrally stored and managed in the DAM

@MAGNOLIA_CMS 37

Metadata as a MixinMagnolia 4.5 Magnolia 5

@MAGNOLIA_CMS 38

Data Module replaced by ContentAppContentApp is the recommended approach to manage content (Data)

The migration process automatically creates ContentApp

Magnolia 4.5Magnolia 5

@MAGNOLIA_CMS

OpenWFE replaced by jBPM Manual migration required in case of custom OpenWFE workflow

New Workflow Engine

A

B

C D

E

@MAGNOLIA_CMS 40

Migration ProcessJust like any standard Magnolia upgrade

Update pom files, module descriptor and replace deprecated code Complete your module version handler

Dialog migration task DMS to DAM migration tasks Data migration tasks

Test and Deploy!

@MAGNOLIA_CMS 41

Step 0 - PrerequisitesYour Magnolia instance must use at least the version 4.5.12.

Tomcat Users - Version must be at least 7.0.47

Upgrade your Magnolia instance to the latest version (4.5.23) if you are using a version below 4.5.12

@MAGNOLIA_CMS 42

Step 1 - Update your project 1. Update your pom files

A. Magnolia Version : The latest one (5.3.5) B. No need to specify dependencies in

DependencyManagement anymore C. Update artifact and group Ids

2. Update deprecated code 3. Update your module descriptor 4. Start !

Your Magnolia instance is now running Magnolia 5. Now you must migrate your own modules.

@MAGNOLIA_CMS 43

Step 2 - Version Handlers Objective Tasks

DialogsMigrating your module dialogs DialogMigrationTask("your_module_name")

Migrating your custom controls and save handlers Rewrite them as a field type and declare them to the DialogMigrationTask using ControlMigratorsRegistry

DAM

Migrate DMS content to the DAM MoveDataWorkspaceToDamMigrationTask();

Move uploaded assets from a workspace to the DAM MoveContentToDamMigrationTask(“ws_name”)

Move uploaded assets using FCKEditor to the DAM MoveFCKEditorContentToDamMigrationTask(“ws_name”)

Update asset references in a workspace to point to the new asset’s location

ChangeWebsiteDmsReferenceToDamMigrationTask(“ws_name”)

Clean workspace and update reference format CleanContentForDamMigrationTask(“ws_name”)

Apply DMS permissions (ACL) to the DAM MoveAclPermissionsBetweenWorkspaces

DataCreation of ContentApp Automatically done during the migration of the Data module

Application permissions SetPropertyTask

WorkflowIn 4.5, if you were using the default workflow None

In 4.5, if you have your custom workflow Workflow must be migrated to jBPM manually

@MAGNOLIA_CMS 44

Step 3 - TestUse your production content Test strategies

- Crawl and compare the result - Acceptance tests - Test campaign involving the end-users

Any issue? - Add the use-case to your test-repository - Go back to Step 2 and enrich the version handler

@MAGNOLIA_CMS 45

Step 4 - Finalize the MigrationUpdate your bootstraps in your project

Configuration Samples

Build and release your project

You are now ready to deploy your project on production!

@MAGNOLIA_CMS 47

What’s next?Contact Us

http://www.magnolia-cms.com/campaigns/migration.html

Our Services - Migration Audit - Migration Assistance - Migration Workshop (Conference 2015)

@MAGNOLIA_CMS 48

Questions?