Jahia Book
Chapter 7 - Maintenance
Jahia
9 route des Jeunes, CH-1227, Carouge Switzerland
http://www.jahia.com > The company web site
http://www.jahia.net > The community web site
Jahia Book - Chapter 6 - Maintenance
V ERSION
This table records the versions of this document and their last updates
Version
1.0
© 2007 Jahia Ltd. All rights reserved.
Author
Jonathan Coates
Date
2008-03-31
Modifications
Initial document
Page 2 of 56
Jahia Book - Chapter 6 - Maintenance
S UMMARY
Page
Version
2
Summary
3
Maintenance
Backup and Migration from dev to prod
6
6
Database
Jahia core data files
Jahia Templates
Web applications / Portlets
Configuration files
Others suggestions
6
6
7
7
7
8
Kill dead processes in Quartz
Howto correct ACLs in database
Howto remove pages in database
8
8
8
Monitoring
9
Monitoring Jahia internals in real-time
Activating / deactivating monitoring
Accessing the reporting user interface
Steps to completely deactivate the service interception.
Monitoring server memory, CPU usage, threads and sessions
Monitoring Tomcat and Jahia through LambdaProbe
9
9
10
10
11
11
Backup
12
Troubleshooting
What to do if I am in trouble with my Installation ?
13
13
1) Activating the Jahia System Logs
Internal Jahia log files
2) Jahia Free or Commercial Support
The Free Jahia Mailing lists
Technical FAQ
13
13
13
13
13
Which browsers are supported by Jahia ?
14
Windows
Mac
Linux
14
14
14
How can I Activate Mail Notification within the Workflow Process ?14
How to proceed if you want to modify the JSP of the Jahia engine files (the
edition pop-ups) ?
15
How to translate Jahia in a foreign language ?
16
How can I package new templates and deploy them in Jahia ?
17
Upgrading
Introduction
Disclaimer
Comparison of Jahia 4 with Jahia 5
Differences
Recommendations
© 2007 Jahia Ltd. All rights reserved.
19
19
20
20
21
23
Page 3 of 56
Jahia Book - Chapter 6 - Maintenance
Preliminary form
23
Migration from Jahia 5.0.x to Jahia 5.0.3
25
Migration from Jahia 5.0.0 to Jahia 5.0.1
Migration from Jahia 5.0.1 to Jahia 5.0.2
Migration from Jahia 5.0.2 to Jahia 5.0.3
25
28
29
Migration from Jahia 4.x to Jahia 5.x
Before started
Jahia 4.x Data Export
XML Export Operation
Procedure
Error messages
Structure of the exported archive
The site.properties file
The export.xml file
The users.xml file
The categories.xml file
The filesacl.xml file
Installation of Jahia 5 vs Jahia 4
LDAP configuration
Cluster Configuration
How to migrate webapps
Templates Migration
Migration methodology
Changes to be performed before deployment
actions.js
eventlistener.jsp
header.inc
Hardcoded PIDs
declarations.inc (and common_vars.inc )
Taglibs
Absolute fields
CHANGES TO BE PERFORMED AFTER DEPLOYMENT
Category.findCategoriesByPropNameAndValue()
Category.getChildCategories()
CategoryBean
ContentContainer.getLanguagesStatesWithoutChilds()
ContentPage.activeStagingEntries()
ContentPage.getContentPagePath()
FormDataManager.getInstance()
JahiaBaseACL.setGroupEntry()
JahiaBaseACL.setUserEntry()
JahiaSearchResultHandlerImpl
JahiaPageBaseService.getPageIDsWithTemplate()
PortletSetPersistanceManager.getPortletSet()
PortletSetPersistanceManager.setPortletSet()
ServicesRegistry. getJahiaApplicationsDispatchingService ()
Specific problems
You have some metadata in Jahia 4
Changes which can be performed after import
Search
Sitemap
Blogs
Data Migration
Import process of a Jahia 4.2 xml archive
Results analysis
Content Validation
New Functionalities
Administration bar
Operations buttons
© 2007 Jahia Ltd. All rights reserved.
31
31
34
34
34
34
35
35
36
36
37
37
38
38
38
38
40
40
41
41
41
41
41
42
43
43
43
43
44
44
44
44
45
45
45
46
46
46
47
47
47
48
48
48
48
49
49
50
50
51
53
54
54
54
Page 4 of 56
Jahia Book - Chapter 6 - Maintenance
Caches
Modifications in API
Workflow
ContentObject language states
ContentObject validation
© 2007 Jahia Ltd. All rights reserved.
54
55
55
56
56
Page 5 of 56
Jahia Book - Chapter 6 - Maintenance
M AINTENANCE
In this section, we will introduce the key notion about maintaining and updating a
Jahia Site.
BACKUP AND MIGRATION FROM DEV TO PROD
To prevent or minimize loss of data stored in your Jahia Server, backup
procedures should be used regularly. The same procedure could also be used
in order to migrate data from a development to a production server.
If you want to proceed to regular backups (say daily backup during the
night), you can backup the files and the database content with external tool.
You don’t need, however, to backup each time the whole Jahia installation
but only data, to minimize the size and time of each backup. Here are the
following information that needs to be backed-up:
Database
Almost all database servers provide their own tools to allow backup of
database content without having to shut down the database server. Databases
like MS SQL Server or Oracle provide tools for this task with scheduling
options, so that you can plan to backup at a time which is more convenient
for you. For others database servers like Postgres or MySQL, some command
line programs are provided to allow to “dump” content in a text file. These
programs, in conjunction with scheduling features of Operating Systems
(Cron jobs for Linux, the “Scheduled tasks” option for Windows) will offer
you all you need to proceed to unattended backups,
For example, if you want to dump the Jahia content of a MySQL database on
a Linux system, you can use the following syntax:
mysqldump database_name > filename
or, more concretely:
mysqldump jahia > jahia.sql
You may need to add additional information like username and password to
access this particular database.
This command could be included in a Cron jobs to provide unattended
backup or the database. The file produced can then be backup on another
machine or on a backup system like a tape backup.
Jahia core data files
© 2007 Jahia Ltd. All rights reserved.
Page 6 of 56
Jahia Book - Chapter 6 - Maintenance
Some content of Jahia is stored as files on disk, like content of BigText area or
files uploaded to Jahia. Here is the directory you should backup:
TOMCAT_HOME/webapps/jahia/WEB-INF/var/content/
This directory contains the “filemanager” directory, which contains all file
uploaded on your site though Jahia, and the “bigtext” directory, which
includes all BigText area content.
If you wish also backup extraction made with the method mentioned on
point 7.2.1, you should also backup this directory:
TOMCAT_HOME/webapps/jahia/WEB-INF/var/site_extraction/
Jahia Templates
Jahia templates should not change very often, so you may not need to backup
them on a daily basis. They can be found here:
TOMCAT_HOME/webapps/jahia/jsp/jahia/templates/
This directory contains all templates ordering by virtual sites, as well as all
images used inside the templates.
Web applications / Portlets
If you have no web applications (or portlets) used inside your Jahia server,
you can skip this part.
All default Jahia webapps are located here:
TOMCAT_HOME/webapps/
Each webapps directory name contains the name of the application. For
example, if you have added a “Time Reporting” the directory name will be:
“TimeReporting”
Webapps are accessible across any virtual sites.
You can backup all web applications or only the one you use. If you installed
other third party portlets, be sure to check on their respective documentation,
where they stored their content and what needs to be backup.
Configuration files
There is a few configuration files that you may want to backup also. The
directory containing all settings directly related to Jahia is:
TOMCAT_HOME/webapps/jahia/WEB-INF/etc/
The directory where Tomcat configuration files are stored is:
© 2007 Jahia Ltd. All rights reserved.
Page 7 of 56
Jahia Book - Chapter 6 - Maintenance
TOMCAT_HOME/conf/
Others suggestions
Here are some suggestions to backup your data:
•
Linux
First create the database dump, then use the “tar” command to create an
archive file (tar.gz or tar.bz2) containing the dump and all selected
directories. The archive file can then be copied to another disk or another
machine. You can create a small script to proceed to these actions and
produce an archive file with a unique name (like “jahia_dayOfMonth.tgz”)
that you can rotate over a month.
•
Windows
You can use a command line archival tool (like RAR from Rarsoft) inside a
batch file launched through the Windows Scheduler to backup all selected
directories to a single archive file. The RAR archiver also support variables
inside the archive name to produce a file with a unique name like
“jahia_Date_Time.rar”.
To restore content, you can either overwrite existing content of your Jahia
server with directories that have been backed up, or install a fresh copy of
Jahia and extract the files that you have backed up. You should also dump
and restore the database.
Make sure that the language encoding of the file system of the server you are
restoring you data to is the same as the source server, otherwise problems can
occur when editing existing text.
KILL DEAD PROCESSES IN QUARTZ
TODO : explain how to kill a process that seems to be stuck
HOWTO CORRECT ACLS IN DATABASE
TODO : detail procedure and SQL requests
HOWTO REMOVE PAGES IN DATABASE
TODO : detail procedure and SQL requests
© 2007 Jahia Ltd. All rights reserved.
Page 8 of 56
Jahia Book - Chapter 6 - Maintenance
M ONITORING
As Jahia is a complex system that uses many bricks, you may want to set-up
some monitoring tools to watch the web application server, front-end web
server if used, the database, available disk space or RAM. Free open source
tools like Nagios (www.nagios.org) exists to watch availability of various
services. Alerts can be sent via e-mail, pager or other user- defined methods.
Monitoring Jahia internals in real-time
Jahia now includes a tool to monitor in real-time the performance of it's
innards, in order to be able to better detect where time is spent, and to take
appropriate actions.
What this monitoring system provides is real-time gathering and reporting of
the time spent in Jahia's back-end services, as well as the number of times
they were called. It uses for this the excellent JAMon library, which provides
the facilities to generate HTML, XML or even Microsoft Excel reports. For
more information on this library, please check out their website.
In this first version, only monitoring of Jahia's services is possible, but we
might extend it to cover more code.
Activating / deactivating monitoring
By default the statistics gathering interceptor is already integrated into Jahia,
but does nothing until we change the logging level on it's particular
implementation. Jahia ships with this interceptor de-activated as the
activation can introduce some performance cost. Fortunately it is possible,
due to Jahia's automatic reloading of logging configuration at runtime, to
modify the configuration while Jahia is running.
To activate statistics gathering :
1. Modify the tomcat/webapps/jahia/WEB-INF/etc/config/log4j.xml to
change the logging level for the interceptor to DEBUG, as follows:
<category name="org.jahia.spring.aop.interceptor">
<!-- Set this to debug to activate JAMon monitoring -->
<priority value="debug"/>
</category>
2. Save the changes, Jahia will pick up the modified log4j configuration after 1
minute, and you will then be able to use the reporting interface to view
results.
To deactivate statistics gathering:
© 2007 Jahia Ltd. All rights reserved.
Page 9 of 56
Jahia Book - Chapter 6 - Maintenance
1. As in the previous step, simply change the logging level back to info and
save the file. After 1 minute, Jahia will pick up the change.
Accessing the reporting user interface
1. In Tomcat's users file, tomcat/conf/tomcat-users, make sure you have a
user that has the "manager" role. Here is an example :
<user username="Jahia" password="4Kz2kE2cy4" roles="manager"/>
Make sure you noted the username and password, because you will need it
to access the reporting JSP. If you don't have such an entry, you will have to
create it once, and then restart Jahia. Be sure you choose a password that is
strong, because the manager role also gives you access to Tomcat's
deployment interface.
2. You should now be able to browse to:
http://localhost:8080/jahia/monitor/JAMonAdmin.jsp
and use the username and password from the Tomcat configuration file.
The view presents a table with at the left the methods intercepted in the
services. You can see the number of call to those methods, as well as the
average and cumulative times spent in those
Steps to completely deactivate the service interception.
By default, Jahia is shipped with the service interceptor activated. The
performance cost of this system should be minimal, but you might want to
deactivate it to minimize processing on a production system that is operating
within it's target performance. We describe here how to completely remove
the overhead introduced by this system.
1. In the file tomcat/webapps/jahia/WEBINF/etc/spring/applicationcontext.xml comment the following lines :
<bean id="performanceInterceptor"
class="org.jahia.spring.aop.interceptor.SilentJamonPerformanceMonitorIntercep
tor">
<property name="useDynamicLogger"><value>false</value></property>
</bean>
2. Still in tomcat/webapps/jahia/WEBINF/etc/spring/applicationcontext.xml, in the txProxyTemplate bean,
comment the following lines :
<property name="preInterceptors">
<list>
<ref bean="performanceInterceptor"/>
</list>
</property>
© 2007 Jahia Ltd. All rights reserved.
Page 10 of 56
Jahia Book - Chapter 6 - Maintenance
Monitoring server memory, CPU usage, threads and sessions
Unfortunately though, JAMon will not give you more detailed information
about the status of sessions, memory, threads, etc. For this you can install
different tools on your server to help you out. First of all, there is
MessAdmin, which is quite minimal in functionality, but allows you to see
and track session data. You can also send messages to users, for example to
inform them that a maintenance will take place. MessAdmin does all this
through usages of filters, so not only is it quite transparent to install, but it is
also portable to a lot of application servers.
Some of the tools available in JDK 5 and 6 that are very interesting are
JConsole or VisualGC
One of the best tools, but is Tomcat specific, is LambdaProbe. If you activate
Tomcat's JMX interfaces, you can even monitor garbage collection internal
spaces, such as PermGen, Eden, etc..
Monitoring Tomcat and Jahia through LambdaProbe
If you want to monitor Jahia's execution with LambdaProbe or JConsole ,
modify your Tomcat's catalina.bat (catalina.sh) script to add the following :
-Dcom.sun.management.jmxremote
to the line :
set CATALINA_OPTS=%CATALINA_OPTS% -Dsun.io.useCanonCaches=false -Xms64m Xmx1024m -XX:MaxPermSize=128m -server -Dhibernate.jdbc.use_streams_for_binary
You can then view internal thread and memory processing of your server. If
you want to configure remote access monitoring, this is quite more
complicated, and the best thing is that you read the documentation provided
by Sun for monitoring JVMs.
You can then start your Jahia, and then start JConsole or use LambdaProbe to
view the current status of your server.
You can find installation instructions for LambdaProbe here. For JConsole it
is simply included in JDK 5 and up, so you just need to start it and connect it
to Tomcat once the above configuration in the catalina.bat(.sh) has been done.
© 2007 Jahia Ltd. All rights reserved.
Page 11 of 56
Jahia Book - Chapter 6 - Maintenance
B ACKUP
© 2007 Jahia Ltd. All rights reserved.
Page 12 of 56
Jahia Book - Chapter 6 - Maintenance
T ROUBLESHOOTING
WHAT TO DO IF I AM IN TROUBLE WITH MY INSTALLATION ?
1) Activating the Jahia System Logs
Internal Jahia log files
Please check Logs paragraph in the Advanced Java application server
Configurations section of this chapter.
2) Jahia Free or Commercial Support
The Free Jahia Mailing lists
First of all, please check the archive of the existing Jahia mailing lists. Several
answers to common installation or administration issues have already been
posted there.
If this is not the case, you can try to send a new request in the adequate
mailing list (please do NOT cross-post your questions in several mailing
lists). Please also try to send to the mailing lists as much information as
possible about:
- your system configuration (OS; JDK used; database used; app. server
version;...)
- the Jahia build you are using (check in the “about Jahia” interface in the
Administration Center)
- The full stack trace of the error (if any) in your console. Be sure to turn on
the logging system (explanation on logging).
Warning: these are free mailing lists. So please respect the community and
the fact that perhaps nobody will answer to you because nobody has the time
or the answer.
Technical FAQ
You may also try to check if some new answers to common questions have
been updated on the Jahia.org technical FAQ page. This page is available
here: http://www.jahia.org/faq
© 2007 Jahia Ltd. All rights reserved.
Page 13 of 56
Jahia Book - Chapter 6 - Maintenance
WHICH BROWSERS ARE SUPPORTED BY JAHIA ?
The following browsers are recommended to manage content on Jahia:
Windows
•
- Internet Explorer 6.0 or better
•
- Firefox 1.0 or better
Mac
•
Firefox 1.0 or better
•
Safari
Please not that the use of Java applets for editing content requires that the
browser support LiveConnect, which only Safari 1.2 seems to do correctly.
Please note also that Internet Explorer 5.2 for Mac can be used to browse a
Jahia site but is clearly not recommended to manage content.
Linux
•
Firefox
HOW CAN I ACTIVATE MAIL NOTIFICATION
WORKFLOW PROCESS ?
WITHIN THE
Jahia includes a simple workflow process. When an editor has finished
entering content, he can notify the manager of the page(s) that he is done.
This process is automatic when you use the workflow engine.
However, you need to have previously configured the server settings of
Jahia, either during the installation of Jahia or afterwards by going in the
"Server settings" option of the Administration panel of Jahia. If you don't set a
mail server and a valid sender's e-mail address there, mail notifications won't
be sent. Please note also that Jahia doesn’t currently support SMTP
authentication, so make sure the server running Jahia is authorized to access
the SMTP server you are using.
The mail notification process makes use of the e-mail address entered when
you create a new user in Jahia. Make sure you have set up a valid e-mail
address for each user, or at least for each user responsible for validating a
page or a section of the site.
Currently, you can not decide which person should receive the notification email. This e-mail will be sent to each person acting as administrator for the
given page(s).
© 2007 Jahia Ltd. All rights reserved.
Page 14 of 56
Jahia Book - Chapter 6 - Maintenance
HOW TO PROCEED IF YOU WANT TO MODIFY
JAHIA ENGINE FILES (THE EDITION POP-UPS) ?
THE
JSP
OF THE
The JSPs files containing the code for all engines (for example the login or the
update windows) are located in the following directory:
TOMCAT_HOME/webapps/jahia/jsp/jahia/engines/
For example, the JSP file corresponding to the login window, login.jsp, is
located in:
TOMCAT_HOME/webapps/jahia/jsp/jahia/engines/login/
However, Jahia is distributed with precompiled JSP files which are included
in the jahia.jar file, so modifying the previously mentioned login file will
have no visible effect.
To indicate to Jahia that you want to use a jsp file in the "engines" directory
instead of the precompiled JSP, you will need to edit the web.xml file located
in the following directory:
TOMCAT_HOME/webapps/jahia/WEB-INF/
In our example, we want to use and modify the login.jsp file, so we need to
remove or comment out the following part in the web.xml file:
<servlet-mapping>
<servlet-name>jsp.jahia.administration.login_jsp</servlet-name>
<url-pattern>/jsp/jahia/administration/login.jsp</url-pattern>
</servlet-mapping>
If you don't want to use the precompiled JSPs at all for any engines, just
comment out the whole part located between:
<!-Automatically created by Tomcat JspC.
Place this fragment in the web.xml before all icon, display-name,
description, distributable, and context-param elements.
-->
and
<!-All session-config, mime-mapping, welcome-file-list, error-page, taglib,
resource-ref, security-constraint, login-config,
security-role, env-entry, and ejb-ref elements should follow this
fragment.
--
© 2007 Jahia Ltd. All rights reserved.
Page 15 of 56
Jahia Book - Chapter 6 - Maintenance
HOW TO TRANSLATE JAHIA IN A FOREIGN LANGUAGE ?
All texts in the Jahia interfaces are taken from a basic text file called a
ResourceBundle. The ResourceBundle files contain a matching between the
key used in the code (for example the key for the "Select page to link" text
display when you add a link is
"org.jahia.engines.shared.Page_Field.selectPageToLink.label".
If you want to translate Jahia in another language, first make a copy of the
following 3 ResourceBundle files:
•
JahiaAdministrationResources.properties
•
JahiaEnginesResources.properties
•
JahiaMessageResources.properties
They are located in the following directory:
TOMCAT_HOME/webapps/jahia/WEB-INF/classes/
Then rename them by adding an underscore at the end of the name followed
by the language code of the language in which you want to translate Jahia.
Fox example, if you want to make a German translation of Jahia, you will
rename
JahiaAdministrationResources.properties
in
JahiaAdministrationResources_de.properties
Then, edit each one of the 3 files and translate the text mapped to each key.
For example, in the JahiaEnginesResources_de.properties, file, the line
org.jahia.engines.shared.Page_Field.selectPageToLink.label = Select page to
link
may be changed to
org.jahia.engines.shared.Page_Field.selectPageToLink.label = Wählen Sie die
Seite vor, um zu verbinden
© 2007 Jahia Ltd. All rights reserved.
Page 16 of 56
Jahia Book - Chapter 6 - Maintenance
HOW CAN I
JAHIA ?
PACKAGE NEW TEMPLATES AND DEPLOY THEM IN
To build a .jar template package once you have created a set of templates, you
will need to create a templates.xml file with the following format (taken from
the corporate portal templates package):
<?xml version="1.0" encoding="ISO-8859-1"?>
<tpml>
<parameter name="package-name">Corporate Portal</parameter>
<parameter name="root-folder">corporate_portal_templates</parameter>
<parameter name="classes-file">corporate_templates.jar</parameter>
<parameter name="provider">http://www.jahia.com</parameter>
<parameter name="thumbnail">corporate_portal_templates.gif</parameter>
<template browsable="1" visible="1" homepage="1">
<parameter name="name">Home</parameter>
<parameter name="filename">home.jsp</parameter>
<parameter name="display-name">Home</parameter>
</template>
<template browsable="1" visible="1">
<parameter name="name">Simple</parameter>
<parameter name="filename">simple.jsp</parameter>
<parameter name="display-name">Simple</parameter>
</template>
</tpml>
The global parameters include:
- package-name: Name of the package as it will appear in Jahia.
- root-folder: Name of the directory that will be created in
jsp/jahia/templates/yoursite/ when the templates are deployed.
- classs-files: Name of the jar file containing the languages resources bundles
(like Corporate_portal_templates_en.properties) which will be included in
the jar file of the template package.
- provider: Name of the provider of the set of templates
- thumbnail: a screenshot of the templates look can be used. It will be
displayed on the list of available template sets when you create a new virtual
site.
Attributes of the <template>tag include:
- browsable: Set to 1 if the template is listed when a user wants to add a new
page.
- visible: Set to 1 if the template is listed when a user wants to add a new
page. Set to 0 if the template should not be visible.
© 2007 Jahia Ltd. All rights reserved.
Page 17 of 56
Jahia Book - Chapter 6 - Maintenance
- homepage: If the template should be used for the home page of the site, add
the homepage=”1” value.
Parameters for each template are:
- name: The chosen name of the template
- filename: the name of the jsp file
- display-name: The name of the template as it will appear in the drop-down
list when adding a new page.
You can check the corporate_portal_templates.jar to see how it is constructed.
It is located in:
TOMCAT_HOME/webapps/jahia/WEB-INF/var/shared_templates/
Once you have created your package, you can copy it in the following
directory:
TOMCAT_HOME/webapps/jahia/WEB-INF/var/shared_templates/
When a new virtual site is created, your new template set will appear in the
list of available sets. If you want to deploy the templates in you current
virtual site, just copy the package to the following directory:
TOMCAT_HOME/webapps/jahia/WEB-INF/var/new_templates/current_site/
After a few seconds, the templates will be deployed and available.
© 2007 Jahia Ltd. All rights reserved.
Page 18 of 56
Jahia Book - Chapter 6 - Maintenance
U PGRADING
INTRODUCTION
You already use Jahia 5 and want to migrate your server to a newer release:
the first part of this document will guide you during this upgrade. Refer to
the changelog of the wanted version to discover the improvements and
corrections that you’ll benefit after this migration.
You’ve chosen to migrate your Jahia site(s) to version 5, congratulations!
You’ll discover in this new version a lot of features you were certainly
waiting for, since a long time. Driven and built by our customers’ requests,
Jahia 5 will open a new area in your enterprise content management policy.
Nevertheless, migrating from Jahia 4 to Jahia 5 is not a simple an easy task,
due to some changes demanded in terms of features but also architecture,
API, taglib and content structure.
The migration process must be launched with care and according to a very
strict methodology, in order to avoid data losses and extra time spent on it.
This document will guide you through the main steps of a migration :
Exporting content from Jahia 4
Converting templates to make them Jahia 5 compatible
Improving templates with Jahia 5 new features
Importing content into Jahia 5
This document will also focus on errors you could encounter, and emphasize
on environment constraints. Pay attention to all the details we point at, like
JVM version, DB encoding, LDAP connections and so on. As Jahia uses an
internal mechanism of import / export which relies on content structure
declarations to validate content before exporting and importing, all those
details may impact on final results.
If you encounter some difficulties during your migration or if your migration
effort seems to complex to be handled in-house, you can first try to get help
from Jahia public mailing-lists, or get consultancy from Jahia experts.
In any cases, except if your website is really simple, built using Jahia taglib
exclusively, we encourage companies willing to migrate to ask for a
minimum of support from Jahia teams in order to make the migration easier
and more secure.
© 2007 Jahia Ltd. All rights reserved.
Page 19 of 56
Jahia Book - Chapter 6 - Maintenance
Disclaimer: This document is ONLY FOR INFORMATION. Jahia Solutions
Group cannot be charged or be responsible of any trouble occurring during
or after the migration. Indeed, a so-called “Jahia project” is not done solely of
the JSSL code source or the basic corporate templates without any
modifications. Some specific code is more or less always implemented.
Further more, some technical specificities may required our expertise and are
not formalized in this document which does not pretend being exhaustive.
Last and not least, this paper is just a guide helping our clients and partners
performing a migration. We always recommend contacting us before starting
any migration, at sales@jahia.com
Comparison of Jahia 4 with Jahia 5
Jahia 4
Jahia 5
Fast & easy installation


Simple & powerful back office administration


In-site editing


Multilanguage capabilities


Categorization


Document Management


Integrated Search Engine


Validation Workflow


Blogs


Portal


XML Export


Versioning


Hibernate 3


Jetspeed 2


Jahia ESI Server – JSR 128


HTML Container Cache


Remote server publishing


Processing server


Time based publishing


Delayed indexation


XML Import


AJAX


Multi-level differential Workflow


© 2007 Jahia Ltd. All rights reserved.
Page 20 of 56
Jahia Book - Chapter 6 - Maintenance
Metadata (Dublin Core)


WAI checking


Web Clipping


Copy/Paste & Linked copies


Differences
Jahia ESI Server – JSR 128
Jahia version 5.0 integrates an ESI (Edge Side Includes) server and supports
the JSR 128 standard.
Benefits:
Frontal web cache by fragments allowing for high availability regardless
of the load on a clustered architecture.
Caching by HTML fragments (triggered by back office events) and
personalized per user/group.
Processing server
Jahia version 5.0 lets define a dedicated processing server in cluster
configuration. This server processes high cost operations (indexation,
workflow, import/export, …), so that other cluster nodes (browsing /
contributing servers) keep good performances.
It is also possible since Jahia version 5.0 SP3 to define dedicated browsing
servers. On such a server, no user can switch to edit mode, even if he has the
right to, so that this server delivers the best live performances.
Remote server publishing
Jahia version 5.0 integrates a remote server publishing platform that allows
for the definition of a public environment updated by a content creation
environment. It is thus possible to physically separate both environments.
Benefits:
Update by generation of a differential export based on the Jahia XML
import/export framework (creation of a ZIP bundling Multilanguage
content, access rights and files/media).
Webdav server Updated through HTTP
© 2007 Jahia Ltd. All rights reserved.
Page 21 of 56
Jahia Book - Chapter 6 - Maintenance
Hot update at the time of file detection
Ability to customize export profiles and select files for publication.
Ability to publish content on many remote servers simultaneously
Fine tuning and scheduling of remote publishing available

Sync management: Synchronization errors are automatically detected
and can be automatically fixed
AJAX
Jahia version 5.0 leverages the AJAX technology (Asynchronous JavaScript
and XML) to manage all edition menus (including rolling menus) and the
arborescence. This new interface development structure is based on web
standards and is used by major projects like Google.
Benefits:
Menus and trees are smartly loaded on-demand, thus speed and
performance are greatly improved in edit mode.

Only required elements are loaded: the system performs optimally.
Hibernate 3
Jahia version 5.0 embeds Hibernate. Initially based on version 2 of this open
source framework, the development comity decided to switch to version 3 in
order to leverage the recent upgrades to this powerful database relationship
management system (persistence layer).
Benefits:
Ability for Jahia to connect to all databases on the market
Increase in performance: the persistence layer acts as a cache for objects
stored in the database
Load optimization in production that prevents database saturation
Ability to store all Jahia objects in the database
Jetspeed 2
Jahia version 5.0 embeds Jetspeed 2, the portal framework from the Apache
foundation.
Benefits:
© 2007 Jahia Ltd. All rights reserved.
Page 22 of 56
Jahia Book - Chapter 6 - Maintenance
Jahia supports management and deployment of JSR 168 portlets.
Deployment of standard web applications (webapps) is still supported by
Jahia, allowing for coexistence of two types of web applications in the
portal.
Recommendations
Jahia Server 5 OS :




Windows NT / 2000 / XP
Linux
Solaris
Mac OSX
Suggested Min. Development Configuration :



Bi-Pro Pentium 2GHz or +
2 GB RAM
1 GB HD
Suggested Min. Production Environments:



Bi-or quadri Pro (64 bits CPU and OS)
4 or 8 GB RAM
100 GB HD
Warning: 32 bits JVM are limited in max memory (1.5 GB under Windows - 2
or 3 GB under Linux/Solaris). Jahia 5.0 tries to cache a maximum of data in
order to boost performance. So we highly recommend 64 bits environments
with enough memory available at least for all production environments.
In some exceptional cases, some out of memory errors have also been reported
during XML export of very big sites. In that case, you have no other choice
that to run a copy of your Jahia 4 server in order to perform the export.
Preliminary form
The following form lets estimate the amount of risk and the time necessary
for the migration. Some of those parameters may change with the migration.
Indeed, you can take the opportunity to modify some elements of your
configuration (database version/provider, …).
In the following form, refer to icons to differentiate point which let evaluate
migration complexity (
) and those which underline parameters
which have no consequence on migration complexity, but have to be
considered (
).
Which version of Jahia 4 do you currently use?
© 2007 Jahia Ltd. All rights reserved.
Page 23 of 56
Jahia Book - Chapter 6 - Maintenance
 You need to upgrade to Jahia 4.2 to benefit of the XML export feature.
This operation is simple if your version is 4.1.0 or more.
………………………………………………………………………………………….
Which jvm do you currently use (want to use after migration)?
 If you are using a jdk 1.4 before and after migration, you may encounter some templates
compilation problems in Jahia 5 due to a size limitation in your jvm.

In every instance, take care using same jvm in test environment as in production one.
………………………………………………………………………………………….
Which operating system do you currently use (want to use after migration)?

Take care using same OS in test environment as in production one.

Shifting OS has no consequence on migration complexity.
………………………………………………………………………………………….
Which database do you currently use (want to use after migration)?
Please also precise versions

Take care using same database (provider and version) in test environment as in
production one.

Shifting database has no consequence on migration complexity.

If you decide to use in-base files storage, don’t forget to configure your database so that
maximum store files size is big enough.
………………………………………………………………………………………….
Do you use a LDAP connection?

If you use a LDAP connection, your Jahia server need to be connected to your LDAP
server during export and import operations.
………………………………………………………………………………………….
How many different templates do you currently use?

The more templates you use, the more complex your migration will be.
………………………………………………………………………………………….
Are your templates adapted from Corporate Portal Templates, or developed
from scratch?

If your templates are adapted from Corporate Portal Templates, we will be able to support
you faster during your migration process, or to perform it faster if you decide to let us do
this migration.
© 2007 Jahia Ltd. All rights reserved.
Page 24 of 56
Jahia Book - Chapter 6 - Maintenance
………………………………………………………………………………………….
If developed from scratch, do you mainly use taglib or scriptlets?

The more taglib based your templates are, the more simple it will be to migrate them.
………………………………………………………………………………………….
How many virtual sites do you have?

The more virtual sites you have, the more complex your migration will be. You can
migrate your virtual sites separately to dispatch work in time.
………………………………………………………………………………………….
How many pages do you have?

The more content you have, the more time it will require you to validate migration.
………………………………………………………………………………………….
How many languages do you use in your webste?

The more languages you use, the more time the migration will require.
………………………………………………………………………………………….
How many files do you have (number and total size)?

The more files you have, the more time it will require to validate migration.
………………………………………………………………………………………….
How many portlets do you have?

The more portlets you have, the more time the migration will require.
………………………………………………………………………………………….
MIGRATION FROM JAHIA 5.0.X TO JAHIA 5.0.3
This part explains how to upgrade from Jahia 5.0.0 to Jahia 5.0.3. Basically,
after launching some sql scripts if you have a Jahia version under 5.0.2, you
need to setup a separate installation of Jahia 5.0.3, then recover from your
existing Jahia server the data, content and specific setup you may have made
(connection to LDAP server, etc). You will also need to run some other sql
scripts from administration center to update your existing database. The
following procedure should get you up and running.
Start at the paragraph corresponding to your current Jahia version, and then
follow all paragraphs one by one until last one.
Migration from Jahia 5.0.0 to Jahia 5.0.1
© 2007 Jahia Ltd. All rights reserved.
Page 25 of 56
Jahia Book - Chapter 6 - Maintenance
You need to create 2 additional tables in your existing 5.0.0 database. Connect
to your database server with a tool that allow you to run a sql query on it,
and execute the following commands.
For Microsoft SQL Server :
ALTER TABLE CUSTOM_PORTLET_MODE DROP CONSTRAINT CUSTOM_PORTLET_MODE_FK_1;
CREATE TABLE CUSTOM_PORTLET_MODE
(
ID INT NOT NULL,
APPLICATION_ID INT NOT NULL,
CUSTOM_NAME NVARCHAR (150) NOT NULL,
MAPPED_NAME NVARCHAR (150) NULL,
DESCRIPTION NTEXT NULL,
CONSTRAINT CUSTOM_PORTLET_MODE_PK PRIMARY KEY(ID) );
ALTER TABLE CUSTOM_WINDOW_STATE DROP CONSTRAINT CUSTOM_WINDOW_STATE_FK_1;
CREATE TABLE CUSTOM_WINDOW_STATE
(
ID INT NOT NULL,
APPLICATION_ID INT NOT NULL,
CUSTOM_NAME NVARCHAR (150) NOT NULL,
MAPPED_NAME NVARCHAR (150) NULL,
DESCRIPTION NTEXT NULL,
CONSTRAINT CUSTOM_WINDOW_STATE_PK PRIMARY KEY(ID) );
For MySQL :
drop table if exists CUSTOM_PORTLET_MODE;
CREATE TABLE CUSTOM_PORTLET_MODE
(
ID MEDIUMINT NOT NULL,
APPLICATION_ID MEDIUMINT NOT NULL,
CUSTOM_NAME VARCHAR(150) NOT NULL,
MAPPED_NAME VARCHAR(150),
DESCRIPTION MEDIUMTEXT,
PRIMARY KEY(ID),
FOREIGN KEY (APPLICATION_ID) REFERENCES PORTLET_APPLICATION
(APPLICATION_ID) ON DELETE CASCADE );
drop table if exists CUSTOM_WINDOW_STATE;
CREATE TABLE CUSTOM_WINDOW_STATE
(
ID MEDIUMINT NOT NULL,
APPLICATION_ID MEDIUMINT NOT NULL,
CUSTOM_NAME VARCHAR(150) NOT NULL,
MAPPED_NAME VARCHAR(150),
DESCRIPTION MEDIUMTEXT,
PRIMARY KEY(ID),
FOREIGN KEY (APPLICATION_ID) REFERENCES PORTLET_APPLICATION
(APPLICATION_ID) ON DELETE CASCADE );
For PostgreSQL :
DROP TABLE CUSTOM_PORTLET_MODE CASCADE;
CREATE TABLE CUSTOM_PORTLET_MODE
(
© 2007 Jahia Ltd. All rights reserved.
Page 26 of 56
Jahia Book - Chapter 6 - Maintenance
ID INTEGER NOT NULL,
APPLICATION_ID INTEGER NOT NULL,
CUSTOM_NAME VARCHAR(150) NOT NULL,
MAPPED_NAME VARCHAR(150),
DESCRIPTION TEXT,
PRIMARY KEY (ID) );
DROP TABLE CUSTOM_WINDOW_STATE CASCADE;
CREATE TABLE CUSTOM_WINDOW_STATE
(
ID INTEGER NOT NULL,
APPLICATION_ID INTEGER NOT NULL,
CUSTOM_NAME VARCHAR(150) NOT NULL,
MAPPED_NAME VARCHAR(150),
DESCRIPTION TEXT,
PRIMARY KEY (ID) );
For Oracle :
DROP TABLE CUSTOM_PORTLET_MODE CASCADE CONSTRAINTS;
CREATE TABLE CUSTOM_PORTLET_MODE
(
ID NUMBER(10,0) NOT NULL,
APPLICATION_ID NUMBER(10,0) NOT NULL,
CUSTOM_NAME VARCHAR2(150) NOT NULL,
MAPPED_NAME VARCHAR2(150),
DESCRIPTION VARCHAR2(2000) );
ALTER TABLE CUSTOM_PORTLET_MODE
ADD CONSTRAINT CUSTOM_PORTLET_MODE_PK
PRIMARY KEY (ID);
DROP TABLE CUSTOM_WINDOW_STATE CASCADE CONSTRAINTS;
CREATE TABLE CUSTOM_WINDOW_STATE
(
ID NUMBER(10,0) NOT NULL,
APPLICATION_ID NUMBER(10,0) NOT NULL,
CUSTOM_NAME VARCHAR2(150) NOT NULL,
MAPPED_NAME VARCHAR2(150),
DESCRIPTION VARCHAR2(2000) );
ALTER TABLE CUSTOM_WINDOW_STATE
ADD CONSTRAINT CUSTOM_WINDOW_STATE_PK
PRIMARY KEY (ID);
For HyperSonic :
DROP table CUSTOM_PORTLET_MODE if exists;
CREATE TABLE CUSTOM_PORTLET_MODE
(
ID INTEGER,
APPLICATION_ID INTEGER,
CUSTOM_NAME VARCHAR (150),
MAPPED_NAME VARCHAR (150),
DESCRIPTION VARCHAR,
PRIMARY KEY(ID) );
drop table CUSTOM_WINDOW_STATE if exists;
CREATE TABLE CUSTOM_WINDOW_STATE
(
© 2007 Jahia Ltd. All rights reserved.
Page 27 of 56
Jahia Book - Chapter 6 - Maintenance
ID INTEGER,
APPLICATION_ID INTEGER,
CUSTOM_NAME VARCHAR (150),
MAPPED_NAME VARCHAR (150),
DESCRIPTION VARCHAR,
PRIMARY KEY(ID) );
Make sure the tables are correctly created in the database.
You will also need to drop some constraints in your existing 5.0 database.
For Oracle, PostgreSQL and Microsoft SQLServer :
alter
alter
alter
alter
alter
alter
alter
alter
alter
alter
alter
alter
alter
table
table
table
table
table
table
table
table
table
table
table
table
table
jahia_sl2_binding drop constraint fkab79b8e923e1f4c2;
jahia_sl2_binding drop constraint fkab79b8e94605c954;
jahia_sl2_locks drop constraint fk53da340c22ea3034;
jahia_sl2_locks drop constraint fk53da340c33924d02;
jahia_sl2_locks drop constraint fk53da340c69f368a3;
jahia_sl2_locks drop constraint fk53da340cfcf9e20f;
jahia_sl2_parent_binding drop constraint fk21da510c23e1f4c2;
jahia_sl2_parent_binding drop constraint fk21da510c603f6ee2;
jahia_sl2_version_history drop constraint fkb5a4b691454fef2;
jahia_sl2_version_history drop constraint fkb5a4b69123e1f4c2;
jahia_users drop constraint fkc1adc5327a6024d5;
jahia_site_prop drop constraint fkc9188385fcf86241;
jahia_sites_users drop constraint fkea2bf1bf6496a1b8;
For MySQL :
alter
alter
alter
alter
alter
alter
alter
alter
alter
alter
alter
alter
alter
table
table
table
table
table
table
table
table
table
table
table
table
table
jahia_sl2_binding drop foreign key fkab79b8e923e1f4c2;
jahia_sl2_binding drop foreign key fkab79b8e94605c954;
jahia_sl2_locks drop foreign key fk53da340c22ea3034;
jahia_sl2_locks drop foreign key fk53da340c33924d02;
jahia_sl2_locks drop foreign key fk53da340c69f368a3;
jahia_sl2_locks drop foreign key fk53da340cfcf9e20f;
jahia_sl2_parent_binding drop foreign key fk21da510c23e1f4c2;
jahia_sl2_parent_binding drop foreign key fk21da510c603f6ee2;
jahia_sl2_version_history drop foreign key fkb5a4b691454fef2;
jahia_sl2_version_history drop foreign key fkb5a4b69123e1f4c2;
jahia_users drop foreign key fkc1adc5327a6024d5;
jahia_site_prop drop foreign key fkc9188385fcf86241;
jahia_sites_users drop foreign key fkea2bf1bf6496a1b8;
If your MySQL instance is case-senstive, you may need to use uppercase for
the constraints names.
Migration from Jahia 5.0.1 to Jahia 5.0.2
You need to delete some attributes not used anymore in the jahia_link table.
ALTER
ALTER
ALTER
ALTER
ALTER
TABLE
TABLE
TABLE
TABLE
TABLE
jahia_link
jahia_link
jahia_link
jahia_link
jahia_link
© 2007 Jahia Ltd. All rights reserved.
DROP
DROP
DROP
DROP
DROP
COLUMN
COLUMN
COLUMN
COLUMN
COLUMN
status;
creation_date;
creation_user;
lastmodif_date;
lastmodif_user;
Page 28 of 56
Jahia Book - Chapter 6 - Maintenance
You also need to drop some constraints in your database.
Connect to your database server with a tool that allow you to run a sql query
on it, and execute the following commands.
For Oracle, PostgreSQL and Microsoft SQLServer :
alter
alter
alter
alter
alter
alter
alter
alter
alter
alter
alter
alter
alter
table
table
table
table
table
table
table
table
table
table
table
table
table
jahia_sl2_binding drop constraint fkab79b8e923e1f4c2;
jahia_sl2_binding drop constraint fkab79b8e94605c954;
jahia_sl2_locks drop constraint fk53da340c22ea3034;
jahia_sl2_locks drop constraint fk53da340c33924d02;
jahia_sl2_locks drop constraint fk53da340c69f368a3;
jahia_sl2_locks drop constraint fk53da340cfcf9e20f;
jahia_sl2_parent_binding drop constraint fk21da510c23e1f4c2;
jahia_sl2_parent_binding drop constraint fk21da510c603f6ee2;
jahia_sl2_version_history drop constraint fkb5a4b691454fef2;
jahia_sl2_version_history drop constraint fkb5a4b69123e1f4c2;
jahia_users drop constraint fkc1adc5327a6024d5;
jahia_site_prop drop constraint fkc9188385fcf86241;
jahia_sites_users drop constraint fkea2bf1bf6496a1b8;
For MySQL :
alter
alter
alter
alter
alter
alter
alter
alter
alter
alter
alter
alter
alter
table
table
table
table
table
table
table
table
table
table
table
table
table
jahia_sl2_binding drop foreign key fkab79b8e923e1f4c2;
jahia_sl2_binding drop foreign key fkab79b8e94605c954;
jahia_sl2_locks drop foreign key fk53da340c22ea3034;
jahia_sl2_locks drop foreign key fk53da340c33924d02;
jahia_sl2_locks drop foreign key fk53da340c69f368a3;
jahia_sl2_locks drop foreign key fk53da340cfcf9e20f;
jahia_sl2_parent_binding drop foreign key fk21da510c23e1f4c2;
jahia_sl2_parent_binding drop foreign key fk21da510c603f6ee2;
jahia_sl2_version_history drop foreign key fkb5a4b691454fef2;
jahia_sl2_version_history drop foreign key fkb5a4b69123e1f4c2;
jahia_users drop foreign key fkc1adc5327a6024d5;
jahia_site_prop drop foreign key fkc9188385fcf86241;
jahia_sites_users drop foreign key fkea2bf1bf6496a1b8;
If your MySQL instance is case-senstive, you may need to use uppercase for
the constraints names.
Migration from Jahia 5.0.2 to Jahia 5.0.3
New Jahia installation
Shutdown the existing Jahia 5.0.2 instance.
Copy or uncompress Jahia 5.0.3 to a separate directory from the one
where Jahia 5.0.2 is deployed. Before running the configuration
wizard, copy a packaged set of templates containing the same
templates as the ones used in your existing Jahia 5.0.2 install to
tomcat/webapps/jahia/WEB-INF/var/shared_templates/ . This will
allow you to deploy during the configuration wizard the same
templates that you are using on Jahia 5.0.2
Run the configuration wizard. During the database setup, point to a
SEPARATE database than the one used with Jahia 5.0.2 For instance,
if the database used with Jahia 5.0.2 is named "jahia5", create in your
database server a new database named "jahia5_temp". When
presented with the screen to create the initial website, enter the same
© 2007 Jahia Ltd. All rights reserved.
Page 29 of 56
Jahia Book - Chapter 6 - Maintenance
name as your existing Jahia 5.0.2 site and chose the same template set.
Finish the configuration wizard and make sure you can access the
home page.
Shutdown the 5.0.3 Jahia instance.
If you are not using database content storage for the bigtext files and files
uploaded in the file repository of Jahia, copy the directory
tomcat/webapps/jahia/WEB-INF/var/content/ from the Jahia 5.0.2 install
to the 5.0.3 install.
Copy of previous Jahia installation
Copy the template sets used for each existing virtual site from
tomcat/webapps/jahia/jsp/jahia/templates to the same directory of Jahia
5.0.3.
For each templates set that have been deployed in the 5.0.2 install, you
also need to copy or merge if you edited them, the 5.0.3 resource
bundles
located
in
the
tomcat/webapps/jahia/WEBINF/classes/jahiatemplates/ directory. Copy all the ".properties" files
corresponding to your set of templates.
Fix your templates
Changes have been made to the corporate portal templates V1 and V2
(the 2 sets of templates packaged with Jahia). Lots of improvements
have been made on each set, so we encourage you to check the
differences between the sets packaged with Jahia 5.0.0 or Jahia 5.0.1 or
Jahia 5.0.2 and Jahia 5.0.3 and to port them in your set of templates.
You can find the details of the differences:
Corporate portal templates V1: diff from Jahia 5.0.0, Jahia 5.0.1 and
Jahia 5.0.2
Here are the mandatory diff from Jahia 5.0.0 or Jahia 5.0.1.
Corporate portal templates V2: diff from Jahia 5.0.0, Jahia 5.0.1 and
Jahia 5.0.2
Here are the mandatory diff from Jahia 5.0.0 or a Jahia 5.0.1.
Compass library has been updated in WEB-INF/lib/ (compass-core1.0.1.jar). Package org.compassframework has been renamed
org.compass . As a consequence, you may encounter some
compilation errors in your templates until you update your
classes/packages includes.
If you have deployed some web applications in your existing installation,
copy each of them from tomcat/webapps/ to the 5.0.3 directory.
Search indexation should be performed on the new install after the
migration is complete, as changes in the way the indexation is made
have been implemented between Jahia 5.0.2 and Jahia 5.0.3. However
you can recover the content of the tomcat/webapps/jahia/WEBINF/var/fileextraction directory and copy it to the 5.0.3 install. That
© 2007 Jahia Ltd. All rights reserved.
Page 30 of 56
Jahia Book - Chapter 6 - Maintenance
way the search engine won't need to read again the content of all
uploaded files (MSOffice and PDF documents) when re-indexing.
If you have modified some configuration files (LDAP connexion, taglibs
definitions, etc...), you need to port your changes to the equivalent
configuration files of Jahia 5.0.3. Do not overwrite with the old
version as we may have done some structural changes to some of
them.
If you have modified some Jahia engines, you also need to port these
changes to the 5.0.3 engines. Make sure in this case that you modify
the web.xml of Jahia to comment all precompiled JSPs that you have
changed.
Optimize your new Jahia
Finally, connect your 5.0.3 migrated install to the existing database. For
this you need to edit the file jahia.xml located in
/tomcat/conf/Catalina/localhost.
Change the url attribute of both jdbc/jetspeed and jdbc/jetspeedNonTx
tags to point to the database used with Jahia 5.0.2
Launch your new jahia, go to the adminsitration center, server settings
and
click
on
the
patch
management
icon.
Actually this patch management cover the migration from 5.0.2, so
you should put 17724 as the build number
It's important to communicate to your end-user that they will need to
flush their browser cache in order to be sure to have the latest version
of the javascripts used in Jahia when upgrading.
If your are using the Jahia Cache Server (ESI), you should also upgrade it
to the corresponding release of the Jahia Service Pack. It is available in
the download area of the jahia.org website.
If you have a system with large load, you should check the performance
fine tuning guide available with this release.
MIGRATION FROM JAHIA 4.X TO JAHIA 5.X
Before started
The data migration of Jahia4 to Jahia5 will be performing with the
import/export module. This module allows you to create a file with all the
validated content, the Webdav files and all the templates used in your
website.
Only published pages will be exported. So don’t forget to validate everything
necessary as never published pages and not yet validated recent
modifications will not be exported. Don’t worry about validating some
© 2007 Jahia Ltd. All rights reserved.
Page 31 of 56
Jahia Book - Chapter 6 - Maintenance
content that should not be immediately published, after import process, each
page will require validation before being published on the new server.
Those pages will only be exported in actives languages. So don’t forget to
activate no more active languages, for which content you do not want to
loose had been defined. Deactivate languages you want to remove during
migration.
As the XML export/import module migrates only actual in use content, your
database will be cleaned of all invalid or no more used data, so that your new
Jahia server contains only pertinent data. This implies that all versioning
information will be lost. The audit logs will also be lost.
Hard coded PIDs are not handled, as we can’t ensure that a page will have
the same PID before and after migration. We can solve implied problems in
Jahia (See templates migration), but we can do nothing for external links on
your Jahia Server (like trackbacks on blog entries). You may have the same
problem if you have used hardcoded site IDs, container IDs or field IDs.
ACL based on internal Jahia users and groups will be exported natively. On
the contrary, if you're site is based on an external directory (LDAP for
instance) it is mandatory that Jahia is remains connected to that directory
when exporting your data from 4.2 and importing in 5.x. If your Jahia is not
connected to the directory, it will not export the ACL or reimport them.
Globally the migration work in the following way:
Migration of your Jahia 4.x to Jahia 4.2 SP1 with the upgrade patch
available on our website
Export of the site(s) you want to migrate
Modification of your templates to be compliant with Jahia 5
Installation and configuration of Jahia 5
Import of your site(s)
If the migration process is done on a copy of the production server:
Create a "migration environment" with exactly the same components
versions (Operating System, LDAP, JDK version, DB version, etc.) to
avoid compatibility problems.
Once the migration is done, you can:
Reinstall the production server with a fresh Jahia 5.x and import
your data, exported from your migration environment, once
every thing is okay.
© 2007 Jahia Ltd. All rights reserved.
Page 32 of 56
Jahia Book - Chapter 6 - Maintenance
Reinstall a fresh Jahia 5.x, then copy the tomcat/webapps/jahia
directory from your migration environment, create a dump of
your database and restore this dump in production.
The first solution is the most secure, but it takes time to reimport all data via
the Import/export mechanism because Jahia will recreate all sites, pages,
contents, users, groups and ACL on the fly.
The second method is also secure, if you're absolutely confident with your
migrated environment and if the versions are the same (Jahia / Database) in
migration environment and in production environnement. This method will
be much quicker, because all the import work has been done previously and
because importing a database dump is much more efficient than importing.
© 2007 Jahia Ltd. All rights reserved.
Page 33 of 56
Jahia Book - Chapter 6 - Maintenance
Jahia 4.x Data Export
XML Export Operation
Procedure
In the server administration module of Jahia 4.2, you can choose the site(s)
you want to export.
You can export all virtual sites by clicking on the link “ Export all sites” or
you can select the one you want with the check box and click on the link
“Export selected sites”.
Error messages
© 2007 Jahia Ltd. All rights reserved.
Page 34 of 56
Jahia Book - Chapter 6 - Maintenance
During the XML export, you may encounter the following error messages :
ERROR, JahiaAction, org.jahia.bin.JahiaAction: Error
java.lang.OutOfMemoryError: Java heap space
Not enough memory was affected to your Jahia server. Restart your Jahia
server with more memory, and perform again XML export process.
WARN , ImportExportBaseService,
org.jahia.services.importexport.ImportExportBaseService: Invalid pid 12
A textField that contains an hardcoded reference to an invalid pid has been
exported. When such a link is exported, the pid is replaced by the uuid (See
“Structure of the exported archive” section) of the corresponding page, and
when the field is imported, this uuid is replaced by the new pid of the page.
Edit the exported xml file, and search “/pid/12” to identify the field. If you
do not, the field will be imported, still containing this link to this pid, which
may correspond to page of your server this time.
If not pid value is displayed in the error message, the field contained
“/pid/”. You can search this string in your xml file.
Structure of the exported archive
In both case, a zip file will be generated, containing the chosen site(s). We will
find one zip file by exported site.
In each zip file you can find:
A file site.properties which contains general information about the site (
sitekey, server name, languages, ..)
A file export_*.xml by language, which contains all the structured datas.
A bundle of templates named « templates.jar », which contains all the
template of the site, and a file classes.jar which contains all the classes
and resource bundles.
The user list and their proprieties in « users.xml »
The category tree in the file « categories.xml »
Folders « shared », « users » and « groups » which contains webdav tree
structure.
A file « filesacl.xml » which contains all the access rights and properties
on the files.
It is important to notice that that the export file contains the whole data of the
virtual site, in a not protected archive. Confidential files are directly
accessible and so the export file has to be protected as a consequence.
The site.properties file
© 2007 Jahia Ltd. All rights reserved.
Page 35 of 56
Jahia Book - Chapter 6 - Maintenance
It is a properties file which contains the following informations:
siteservername: the server’s name (www.jahia.net)
sitekey: the site’s key used in urls (jahia_net)
sitetitle: the site’s title
the in use languages list, their definition order, their options (mandatory,
active)
languages mapping if defined
the value of the language mixing option if activated
The export.xml file
There is a export.xml file generated for each language active on the site. It
contains the whole live content of the site, staging content is not exported.
The XML file is structured following contents definition in templates, and
based on the structure recognized in the JSR-170.
Pages are represented by <jahia:page> nodes. Those nodes have 2 mandatory
attributes: « jahia:template » which defines the used template and « jahia:title
» which defines the page’s title. The « jahia:pageKey » attribute represents the
url key if defined.
Each page contains node representing either fields (<mySite:image>), or
container lists (<mySite:siteSettingsList>). Those nodes names refer to the
names used in templates in definitions. Nodes representing container lists
have their names suffixed by “List”.
Container lists have a child node for each container in the list, named for the
container list, but without being suffixed by “List” like parent node.
Containers have a child node for each field in the container, using same
semantic as for fields directly contained in page.
Nodes representing fields have an attribute named “jahia:value” containing
the field value.
Finally, nodes representing fields which type is page have a unique child
which type is “<jahia:page>”.
Each node has an identifier “jahia:uuid”, used for references or links. This
attribute has to be unique, but is not mandatory.
Permissions related to an object are exported in a “jahia:acl” attribute.
The users.xml file
© 2007 Jahia Ltd. All rights reserved.
Page 36 of 56
Jahia Book - Chapter 6 - Maintenance
This file contains the list of the users and groups defined on the virtual site.
Each user is represented by a <jahia :user> node, each property of the user is
exported as an attribute of the node.
Nota: only users stored in the Jahia database are exported, LDAP users are
not.
The categories.xml file
We find there the categories tree in XML. Titles, categories properties and
related ACLs are exported as attributes or child nodes of the <jahia:category>
nodes.
The filesacl.xml file
Each webdav files which had specific rights are listed here.
© 2007 Jahia Ltd. All rights reserved.
Page 37 of 56
Jahia Book - Chapter 6 - Maintenance
Installation of Jahia 5 vs Jahia 4
The migration process requires to be performed on a freshly installed Jahia 5.
We recommend using the latest Jahia 5 stable release. The following
paragraphs explain how to keep specific configurations on new server.
LDAP configuration
The configuration files (WEB-INF/etc/ldap/users.ldap.properties & WEBINF/etc/ldap/groups.ldap.properties) are identical in Jahia 4 and Jahia 5,
and so can be directly copied.
The files router-config.xml and group-router-config.xml no more exist, LDAP
providers declaration has to be performed in the file:
/WEB-INF/etc/spring/applicationcontext-services.xml
In this file, uncomment the “JahiaUserManagerLDAPProvider” and
“JahiaGroupManagerLDAPProvider” sections, as well as the corresponding
entries in the “JahiaUserManagerService” and “JahiaGroupManagerService”
sections.
Cluster Configuration
Cluster configuration is done as in Jahia 4, in the jahia.properties file.
However, the org.jahia.cache.jms* sections have been replaced by the cluster*
sections. The cluster.acticated entry has to be set at “true”, and
“cluster.node.serverId” has to be set at a different value on each cluster node.
As cluster nodes now use JGroups instead of JMS to communicate, it is no
more required to specify a JMS server’s address. Instead, four multicast IP
addresses have to be defined. Unless they are already used, you can keep
default values. Those addresses have to be the same on each cluster node.
How to migrate webapps
In Jahia 5, deployed webapps are shared between all virtual sites, so that it is
no more required to deploy several times the same webapp. If you have
deployed, for example the infonews webapp on several virtual sites, tomcat’s
webapps directory contains several times the webapp, suffixed by the name
of the virtual site. In Jahia 5, there will be only one directory. For each
webapp to migrate in a Jahia 5, choose one of those directories, and apply the
required modifications in it.
Jahia 5 let define many entry points in a webapp. To do that, add in the
webapp’s WEB-INF directory a file named Jahia.xml, which describes those
different entry points and which servlet to use. This file has the following
format:
<?xml version="1.0" encoding="ISO-8859-1"?>
<jahia>
<entrypoints>
<entrypoint>
© 2007 Jahia Ltd. All rights reserved.
Page 38 of 56
Jahia Book - Chapter 6 - Maintenance
<name>infonews</name>
<display-name>infonews</display-name>
<description></description>
<target type="servlet-name">Infonews</target>
</entrypoint>
</entrypoints>
</jahia>
Replace <name> node value by the name of your webapp (the name of the
directory) and <target> node value by the servlet or jsp entry point of the
webapp.
Once this file added in the webapp in Jahia 4, you need to recreate a war file
from the directory’s content:
[webapps/infonews-4.0_myjahiasite]% jar cvMf ~/infonews4.0.war *
ajout : WEB-INF/ (entrée = 0) (sortie = 0) (0% stocké)
...
The resulting war file can be deployed in Jahia 5, in the /WEBINF/var/new_webapps directory.
At the end of this section, you should have installed Jahia 5 with your
configuration using a new database.
© 2007 Jahia Ltd. All rights reserved.
Page 39 of 56
Jahia Book - Chapter 6 - Maintenance
Templates Migration
The goal of this section is to let you revise your templates set, developed for
Jahia 4, so that it is Jahia 5 compliant.
We will present there the minimal modifications to do in order to make the
templates Jahia 5 compliant, particularly in order to be able to perform
processes such virtual sites migration by xml import / export.
In the next chapters, we will see the different additional modifications it is
possible to do, for example to beneficiate of Jahia 5 new functionalities, or to
improve performances.
Migration methodology
In order to perform the minimal modifications required to make your
templates set Jahia 5 compliant, we advise you to use the templates set
generated during the xml export of your Jahia 4 site.
In the generated zip archive, you can find a “templates.jar” file, usable
directly in Jahia.
First of all, apply the modifications recommended in the “Changes to be
performed before deployment” chapter, then copy it in the “jahia/WEBINF/var/shared_templates” in a Jahia 5 server, and finally compile all your
templates using the precompileServlet (See. Fine tuning guide). Refer to the
“Changes to be performed after deployment” to get information necessary to
correct your compilation errors. (See “Appendix A: Index of the jsp compiling
errors”)
It is mandatory that your templates compile to perform an import. Even if
your templates compile, it could generate some errors at execution, but those
errors do not prevent import. Nevertheless, we recommend to fix those errors
to have a clean import log, so that it is as readable as possible. To do this, you
can create a page for each template of your set, to test its execution, but we
recommend you to perform a first import test with your now compiling
templates, so that you can test them with your content.
If you have some deprecated templates not yet used by any of your virtual
sites, you may not want to spend time migrating it as you will not use it
again. To identify all the actually in use templates, execute the following
query on your database:
SELECT distinct title_jahia_sites, name_jahia_pages_def,
sourcepath_jahia_pages_def
FROM jahia_pages_data j, jahia_pages_def k, jahia_sites l
WHERE j.pagedefid_jahia_pages_data=k.id_jahia_pages_def and
l.id_jahia_sites=j.jahiaid_jahia_pages_data
ORDER BY title_jahia_sites, sourcepath_jahia_pages_def;
If you use some additional classes or libraries in the WEB-INF/classes/
directory, they will be present in the templates set jar, but you have to
© 2007 Jahia Ltd. All rights reserved.
Page 40 of 56
Jahia Book - Chapter 6 - Maintenance
recompile them in the Jahia 5 environment, as you did for the jsp. This is
required as in Jahia 5 we split Parambean to ProcessingContext/ParamBean
and many signature changed because of this. In other cases, you have to
manually copy them.
Changes to be performed before deployment
This paragraph assumes that the templates to migrate have been created from
the Corporate Portal Templates. If not, go directly to next paragraph.
If the actions.js and eventlistener.jsp files have never been modified, replace
them by those provided with the Corporate Portal Templates V2 in Jahia 5.
If they have been modified, it is necessary to apply the changes manually in
order not to loose the modifications you had done.
actions.js
This file contains javascript functions mandatory for your templates having a
correct functional behavior. This files contains for example javascript function
used to display action menus.
Overwrite the buttonclick() and buttonMouseover() by those provided in the
Corporate Portal Templates V2 in Jahia 5.
Add the content of the action.js file provided in the Corporate Portal
Templates V2 in Jahia 5 from the following section to the end of the file:
// Check the browser for DOM manipulation
function checkBrowser() {
eventlistener.jsp
This file has been totally modified in the Corporate Portal Templates between
Jahia 4 & 5. So it is impossible to define a standard process to update this file
without loosing modifications which could have been applied on it. The
update of this file will require to be handled on a case by case basis.
header.inc
It is required to add in this file (or equivalent) the following include:
<%@ include file="/jsp/jahia/javascript/serverconfig_js.inc"%>
Hardcoded PIDs
© 2007 Jahia Ltd. All rights reserved.
Page 41 of 56
Jahia Book - Chapter 6 - Maintenance
If you use some hardcoded PIDs in your set of templates, those PIDs will not
reference the same pages after migration (or will reference no page at all). If
you prefer to keep those PIDs, you may encounter some 404 errors during
import process. Do not consider it as a problem, but you should add some
appropriate “try / catch” blocks in you templates to have a more readable
import log.
Another solution consists in using urlkeys. Before exporting, add urlkeys to
each page referenced in your set of templates by hardcoded PIDs. Then
replace PIDs by urlkeys in your set of templates.
You can also add urlkeys after having exported your site. To do that, edit the
exported xml file, and add a jahia:pageKey="CHOSEN_URLKEY" property in
<jahia:page> nodes corresponding to each pages you want to reference with
urlkeys.
Then, to modify your templates in order to reference pages by urlkey instead
of PID, the following code examples can be helpful:
final JahiaPage current_page = jData.page();
final PageProperty page_urlkey_property =
current_page.getPageLocalProperty(PageProperty.PAGE_URL_KEY_PROPNAME);
// current page’s urlkey
final String page_urlkey = (page_urlkey_property != null ?
page_urlkey_property.getValue() : "" );
// current page’s PID
final int page_pid = current_page.getID();
// returns the PID of a page designed by its urlkey
public int get_pid_from_urlkey(String urlkey)
{
try
{
List pageProperties = null;
final ServicesRegistry registry = ServicesRegistry.getInstance();
pageProperties =
registry.getJahiaPageService().getPagePropertiesByValue(urlkey);
if (pageProperties.size() == 1) {
final PageProperty pageProperty = (PageProperty)
pageProperties.get(0);
if
(pageProperty.getName().equals(PageProperty.PAGE_URL_KEY_PROPNAME)) {
return pageProperty.getPageID();
}
}
}
catch (Exception e) {
org.apache.log4j.Logger.getLogger(getClass()).warn("Error while
looking for PID from urlkey " + urlkey, e);
}
return -1;
}
declarations.inc (and common_vars.inc )
You can find in Appendix B a list of minimal declarations you should use in a
Jahia 5 templates set. We recommend you to replace yours by those
declarations, and to add the missing ones required by your templates step
one by one until your templates compile. You may also merge it with yours if
© 2007 Jahia Ltd. All rights reserved.
Page 42 of 56
Jahia Book - Chapter 6 - Maintenance
you want to go faster, but this could make you keep some useless
declarations, what can slowdown your performances.
If you had separated your common variables in a specific file, you can still
continue to do so, instead of keeping all in one file as presented in Appendix
B.
Taglibs
In Jahia 4, you used the tag library jahia: . This tag library has been
deprecated in Jahia 5, and has been replaced by two new tag libraries :
content: and jahiaHTML: . The deprecated tag library is still present in
Jahia, so you could decide to keep using it, but as we will remove it in a
further version of Jahia, you would just postpone an inevitable work.
If you have followed the instructions of the previous paragraph, you have
already remove declaration of the old library, and added declarations for the
two new ones. You have now to rename your tags, according to the taglib
documentation available on :
http://www.jahia.net/jahia/Jahia/site/jahia_net/pid/585
you may have to update also some tag attributes.
Absolute fields
If you use some absolute fields (i.e. some fields directly declared at page
level, without being contained in any container / containerList), you may
encounter some import problems. We recommend you to add a container,
and an absolute container list in your templates to avoid it.
As this structure is not the same in your Jahia 4 site, you will have to
manually edit the XML export file to add those two elements.
CHANGES TO BE PERFORMED AFTER DEPLOYMENT
Category.findCategoriesByPropNameAndValue()
© 2007 Jahia Ltd. All rights reserved.
Page 43 of 56
Jahia Book - Chapter 6 - Maintenance
In the Category class, the type returned by the findCategoriesByPropName()
method has been changed:
- public static ArrayList findCategoriesByPropNameAndValue(
String propName,
String propValue)
+ public static java.util.List findCategoriesByPropNameAndValue(
java.lang.String propName,
java.lang.String propValue)
Example :
- ArrayList foundCategories =
Category.findCategoriesByPropNameAndValue("homepage%",
String.valueOf(jData.params().getContentPage().getID()));
+ List foundCategories =
Category.findCategoriesByPropNameAndValue("homepage%",
String.valueOf(jData.params().getContentPage().getID()));
Category.getChildCategories()
In the Category class, the type returned by the getChildCategories() method
has been changed :
- public ArrayList Category.getChildCategories()
+ public List Category.getChildCategories()
Example:
- ArrayList childCategories = currentCategory.getChildCategories();
+ List childCategories = currentCategory.getChildCategories();
CategoryBean
An interface with the same name is defined now, which leads to an
ambiguity. So it is necessary to precise the package when using this class.
- <% if (((CategoryBean)
pageContext.findAttribute("curCategoryBean")).getTitle() != null){ %>
+ <% if (((org.jahia.data.beans.CategoryBean)
pageContext.findAttribute("curCategoryBean")).getTitle() != null){ %>
ContentContainer.getLanguagesStatesWithoutChilds()
In the ContentContainer class, the getLanguagesStatesWithoutChilds()
method has been renamed in getLanguagesStates(). Its parameters are
unchanged.
- public Map getLanguagesStatesWithoutChilds ()
+ public Map getLanguagesStates ()
ContentPage.activeStagingEntries()
In the ContentPage class, the activateStagingEntries() method has been
removed. A new method named activate(), which has exactly the same
parameters has been added to ContentObjet (and so is inherited by
© 2007 Jahia Ltd. All rights reserved.
Page 44 of 56
Jahia Book - Chapter 6 - Maintenance
ContentPage). This method do not replace activateStagingEntries(), and you
now have to use the WorkflowService to validate ContentObject instances.
- public ActivationTestResults activeStagingEntries(
java.util.Set languageCodes,
boolean versioningActive,
JahiaSaveVersion saveVersion,
JahiaUser user,
ProcessingContext jParams,
StateModificationContext stateModifContext )
Example:
final WorkflowService workflowService = WorkflowService.getInstance();
final int contentCtnrWorkflowMode =
workflowService.getWorkflowMode(ctnrToValidate);
// If ContentObject has a linked workflow, we set it to the Std workflow
if (contentCtnrWorkflowMode == WorkflowService.LINKED)
{ workflowService.setWorkflowMode(ctnrToValidate,
WorkflowService.JAHIA_INTERNAL, null, null, jParams); }
final JahiaSaveVersion saveVersion =
ServicesRegistry.getInstance().getJahiaVersionService().getSiteSaveVersion(
jParams.getSiteID());
final StateModificationContext stateModifContext = new
StateModificationContext(
new ContentContainerKey(ctnrToValidate.getID()),localesSet);
workflowService.activate(ctnrToValidate, localesSet, saveVersion, jParams,
stateModifContext);
ContentPage.getContentPagePath()
In the ContentPage class, the getContentPagePath() method has been
renamed in getPagePath(). Its parameters are unchanged.
- getContentPagePath(
EntryLoadRequest loadRequest,
java.lang.String operationMode,
JahiaUser user)
+ getPagePath( EntryLoadRequest loadRequest,
java.lang.String operationMode,
JahiaUser user)
JahiaUser user)
FormDataManager.getInstance()
The getInstance() method is no more defined in the FormDataManager class.
Many functions that required an instance of this class to be called are now
declared as static.
- <option
value='<%=org.jahia.data.FormDataManager.getInstance().formEncode(key)%>'
+ <option value='<%=org.jahia.data.FormDataManager.formEncode(key)%>'
JahiaBaseACL.setGroupEntry()
In the JahiaBaseACL class, the type of a parameter of the setGroupEntry()
function has been changed:
- JahiaBaseACL.setGroupEntry(JahiaGroup, JahiaACLEntry)
+ JahiaBaseACL.setGroupEntry(JahiaGroup, JahiaAclEntry)
© 2007 Jahia Ltd. All rights reserved.
Page 45 of 56
Jahia Book - Chapter 6 - Maintenance
Modify the declaration type of the variable used as second parameter. (This
change may lead to other code modifications if this variable is used
elsewhere.
Import the corresponding class. (in common / declarations.inc if you have
adapted the Corporate Portal Templates)
+ <%@ page import="org.jahia.hibernate.model.JahiaAclEntry"%>
Attention, import only the required class, not the whole package, as it
contains some classes which have the same name that some Jahia classes,
which would lead to some ambiguities preventing your templates from
compiling.
JahiaBaseACL.setUserEntry()
In the JahiaBaseACL class, the type of a parameter of the setUserEntry()
function has been changed:
- JahiaBaseACL.setUserEntry(JahiaUser, JahiaACLEntry)
+ JahiaBaseACL.setUserEntry(JahiaUser, JahiaAclEntry)
Modify the declaration type of the variable used as second parameter. (This
change may lead to other code modifications if this variable is used
elsewhere.
Import the corresponding class. (in common / declarations.inc if you have
adapted the Corporate Portal Templates)
+ <%@ page import="org.jahia.hibernate.model.JahiaAclEntry"%>
Attention, import only the required class, not the whole package, as it
contains some classes which have the same name that some Jahia classes,
which would lead to some ambiguities preventing your templates from
compiling.
JahiaSearchResultHandlerImpl
Replace by PageSearchResultBuilderImpl
Example:
- JahiaSearchResultHandlerImpl.ONE_HIT_BY_PAGE_PARAMETER_NAME
+ PageSearchResultBuilderImpl.ONE_HIT_BY_PAGE_PARAMETER_NAME
JahiaPageBaseService.getPageIDsWithTemplate()
In the JahiaPageBaseService class, the type returned by the
getChildCategories() method has been changed:
- Vector getPageIDsWithTemplate(int templateID)
+ List
getPageIDsWithTemplate(int templateID)
Example:
© 2007 Jahia Ltd. All rights reserved.
Page 46 of 56
Jahia Book - Chapter 6 - Maintenance
- Vector blogPagesId =
JahiaPageBaseService.getInstance().getPageIDsWithTemplate(pageDef.getID());
+ List blogPagesId =
JahiaPageBaseService.getInstance().getPageIDsWithTemplate(pageDef.getID());
PortletSetPersistanceManager.getPortletSet()
In the PortletSetPersistanceManager class, the parameters of the
getPortletSet() method have been changed:
- public PortletBeanSet getPortletSet(
ParamBean jParamBean,
String portletGroupName)
+ public PortletBeanSet getPortletSet(
ProcessingContext jParams,
JahiaData jData,
String portletGroupName)
Example:
- PortletBeanSet portletSet = portletSetManager.getPortletSet(
jData.getParamBean(),
"PortletContentList");
+ PortletBeanSet portletSet = portletSetManager.getPortletSet(
jData.getProcessingContext(),
jData,
"PortletContentList");
PortletSetPersistanceManager.setPortletSet()
In the PortletSetPersistanceManager class, the parameters of the
setPortletSet() method have been changed:
- public void setPortletSet(
String portletGroupName,
ParamBean jParams,
JahiaData jData)
PortletBeanSet portletSet,
+ public void setPortletSet(
PortletBeanSet portletSet,
String portletGroupName,
ProcessingContext jParams,
JahiaData jData)
Example:
- portletSetManager.setPortletSet(portletSpanningGrid, "PortletContentList",
jParams);
+ portletSetManager.setPortletSet(portletSet, "PortletContentList",
jData.getProcessingContext(), jData);
ServicesRegistry. getJahiaApplicationsDispatchingService ()
In the JahiaPageBaseService class, getJahiaApplicationsDispatchingService()
has been removed. If you wanted to get the applications dispatching service,
in order to interact with the portal behavior of Jahia, use the
getApplicationsDispatchingService() method to get an instance of
DispatchingService. This object is not equivalent to the
JahiaApplicationsDispatchingService object you get before as it is now
specific to portal behavior. If you want to manage requests dispatching to
© 2007 Jahia Ltd. All rights reserved.
Page 47 of 56
Jahia Book - Chapter 6 - Maintenance
sub-applications, you now have to use ServletDiaptchingProvider class. This
could be useful if you need to flush caches.
Specific problems
You have some metadata in Jahia 4
If you have defined some fields which contain some metadata like last
modification date, last contributor, creator, … , you may want to use Jahia 5
metadata instead of those fields. You have nothing to do, to benefit of Jahia 5
metadata, but you have to initialize it with the values contained in your fields
in Jahia 4. To do this, you have to edit the XML export file, to add the
required attributes in XML nodes, so that those values will be imported in
Jahia 5.
You can remove your now useless fields in your templates, and the
eventlisteners that updated those fields values.
Changes which can be performed after import
Some templates modifications are mandatory for using your Jahia site, but
can be performed after XML import. For example, the search API has
changed since Jahia 4, and without updating templates, the search
functionality will no more be usable. As it is a mandatory change, you may
prefer do this modification immediately. But you may also prefer delay it in
order to perform a migration as soon as possible.
Search
Replace the searchresult.jsp file in your templates by the one provided in the
Corporate Portal Templates V2 in Jahia 5. Copy also the advsearchresult.jsp
file. If you had modified searchresult.jsp, you will have to reapply those
modifications on the new file. If those modifications are about display, you
will have to do same modifications on advsearchresult.jsp .
Copy each file named search_* from the root directory in the Corporate Portal
Templates V2.
Copy the advsearch/ directory from the Corporate Portal Templates V2.
You may access to the search functionality with a link, and then perform your
search. The searchresult.jsp file in the Corporate Portal Templates V2 is
designed to display the result of a first search. So you may have to replace the
link to search screen by a HTML form like this one:
<script language="javascript" type="text/javascript">
<!-function submitSimpleSearchForm(){
document.searchForm.<%=Search_Engine.SEARCH_REFINE_ATTRIBUTE%>.value='reset';
return;
}
//-->
</script>
© 2007 Jahia Ltd. All rights reserved.
Page 48 of 56
Jahia Book - Chapter 6 - Maintenance
<form name="searchForm" method="post"
action="<%=jData.gui().html().drawSearchLauncher()%>"
onSubmit="checkMaxPageItems(document.searchForm)" >
<input type="text" name="search" size="10"
value='<%=JahiaTools.getStrParameter(request,"search","")%>' />
<input type="hidden" name="maxPageItems" value="10" />
<input type="hidden"
name="<%=PageSearchResultBuilderImpl.ONE_HIT_BY_PAGE_PARAMETER_NAME%>"
value="true" />
<input type="hidden" name="searchView" value="simple" />
<input type="hidden" name="screen" value="execute" />
<input type="hidden" name="freeSearch" value='' />
<input type="hidden" name="<%=Search_Engine.SEARCH_REFINE_ATTRIBUTE%>"
value="" />
<input type="hidden" name="searchHandler" value="search" />
<input type="submit" name="go" value="Search"
onclick="submitSimpleSearchForm();"/>
</form>
Sitemap
Replace your sitemap.jsp file by the one provided in the Corporate Portal
Templates V2, and apply to this file your templates design. If necessary, add
the following declaration:
<ajax:zimbraInclude/>
You may also need to declare the following tag library:
<%@ taglib uri="ajaxLib" prefix="ajax" %>
Blogs
If you use the blog and blogs_listing templates provided in the Corporate
Portal Templates, we recommend you to replace it by those provided in the
Corporate Portal Templates V2 in Jahia 5.
Copy the blogs/ directory from the Corporate Portal Templates V2, and
modify fields and container/containerLists definitions to match with those
used in your templates if necessary.
Reapply your style modifications if you did such modifications.
At the end of this section, your templates should be Jahia 5 compliant, so
that you can from now perform a virtual site import.
© 2007 Jahia Ltd. All rights reserved.
Page 49 of 56
Jahia Book - Chapter 6 - Maintenance
Data Migration
Import process of a Jahia 4.2 xml archive
XML files are Jahia 5 compliant. However, the templates jar file contained in
the export archive have to be replaced by the new Jahia5 compliant templates
jar file previously created.
To perform import, we use the virtual sites managing interface.
You can either use global server export archives or single site export archives.
The file can either be uploaded using the web interface or manually put on
the server, in this instance just indicate the path in the adequate input. It is
recommended to use this second option if possible, especially in case your
export file is big.
Import is processed as a background task, so that you can browse others
virtual site while importing. You can control task processing in the process
viewer.
© 2007 Jahia Ltd. All rights reserved.
Page 50 of 56
Jahia Book - Chapter 6 - Maintenance
Results analysis
Once import is finished, you can verify possible errors in process viewer by
clicking on “informations” icon, then “see logs”.
In this log, objects are referenced by their unique identifiers (for example:
“597363bf-0ebe-4a08-8e76-0ea766f2608a”). Those identifiers are those defined
in the xml export file, which let identify which has encountered a problem
while importing. Language and line number let know in which xml file at
which line is defined the object.
“Definition not found for object <uuid> (<node name>), in <page>
(template <template>) (en, line 7221)” :
Definition has not been found. This is frequent error, which can indicate two
things:
The content is no more used, as some definitions have been removed in
templates, but data was still present in database: in this case, this
content has been normally purged by the import process and you can
pass by this message and associated “not imported” messages.
The content is still in use in the source site, but the required definition
could not be found in the templates during import. It could have been
removed or commented. It is required that all container and/or fields
declarations are present in templates, and that the name is exactly the
same that in log.
“Template not found for object <uuid> : <template name> (en, line 29834)”:
The indicated template could not be found. As a consequence, the whole
page content has not been imported as the page has not been created. This
should not occur if the used templates set contains all exported templates.
“Object <uuid> (<node name>) not imported (en, line 9775)” :
It indicates that a node has not been imported (generally because the
definition could not be found, or because parent node has not been
imported). It is a consequence of the previous errors, and let see which object
have not been imported.
“Page link <uuid> in jahia link on page <id> has not been found in import
- (en, line 1254)”
“Page link <uuid> in bigtext <id> on page <id> has not been found in
import - (en, line 35775)” :
This error indicates that some old external links are remaining, pointing on
pages which have not been imported or have been deleted. It is
recommended to ensure on indicated pages if the link was valid or not on
© 2007 Jahia Ltd. All rights reserved.
Page 51 of 56
Jahia Book - Chapter 6 - Maintenance
source site. If it was valid, the linked page has probably not been imported.
Search in logs for errors related on indicated Id, and verify in XML file if the
page is present.
At the end of this section, you should have migrated your data in Jahia 5.
© 2007 Jahia Ltd. All rights reserved.
Page 52 of 56
Jahia Book - Chapter 6 - Maintenance
Content Validation
We are working on developing a tool which would let verify if no content has
been lost during migration. This tool is not yet available, as automating this
operation is not very easy: we have to compare only a little part of a page
HTML code, but as the rest of the code has changed a lot between Jahia 4 and
5, we have to extract the part we want to compare.
© 2007 Jahia Ltd. All rights reserved.
Page 53 of 56
Jahia Book - Chapter 6 - Maintenance
New Functionalities
Jahia 5 provides new functionalities regarding to Jahia 4. Some of those are
automatically provided by the migration (administration, engines, low level
functionalities, …), but others required some modifications in templates.
Performing those modifications is not mandatory to have Jahia 5 compliant
templates, so that those modifications can be performed after XML import.
Administration bar
A new administration bar has been designed in Jahia 5. This bar provides
access to the new “process display” and “chat” modules, as well as to the
Jahia filemanager.
This paragraph explains how to introduce it with the default look. If you had
modified it in Jahia 4, it will be at your charge to reapply your design
personalization.
Use this to include the administration bar:
<jsp:include page="/jsp/jahia/topbar/topmenu.jsp" flush="true"/>
Operations buttons
We also recommend you to use the embedded operations button bar (tabs to
switch between operation modes), as evaluating if a user is allowed to switch
to edit mode costs a lot in term of performances, and so we regularly update
the code of this bar, in order to improve performances. If you use the
provided bar, you will benefit of those updates when upgrading your version
of Jahia.
<jsp:include page="/jsp/jahia/topbar/operationbuttons.jsp" flush="true"/>
Caches
Jahia 4 provides an included HTML Cache. Jahia 5 also provides a HTML
Cache, but you can also choose to use the new HTML Container Cache, or to
externalize your cache on an other server (which provides for RAM to both
Jahia and cache), using ESI. Using those cache systems requires some
modifications in templates. Please refer the Templates Developer Guide for
more information.
© 2007 Jahia Ltd. All rights reserved.
Page 54 of 56
Jahia Book - Chapter 6 - Maintenance
Modifications in API
There has been many modifications in Jahia API between Jahia 4 and Jahia 5.
Many functionalities have been added, and so API has grown as a
consequence. But there are also some modifications due to the evolution of
the architecture.
The new functionalities should not impact your templates set, but you may
be interested in using it, in order to improve performances of your Jahia sites,
provide additional functionalities to your Jahia sites’ users, etc.
But it will probably be necessary that review your templates, regarding the
modifications of the architecture, as it may impact your templates
functionalities. As it does not prevent data import process, you can perform
this review after import. Indeed, it will be much easier to test functionalities
with real data. But keep in mind this part of the migration, as it could be one
of the most time consumer parts, depending how much complex scriptlet
functionalities you use.
Workflow
In the ContentPage class, the activateStagingEntries() method has been
removed. A new method named activate(), which has exactly the same
parameters has been added to ContentObjet (and so is inherited by
ContentPage). This method do not replace activateStagingEntries(), and you
now have to use the WorkflowService to validate ContentObject instances.
- public ActivationTestResults activeStagingEntries(
java.util.Set languageCodes,
boolean versioningActive,
JahiaSaveVersion saveVersion,
JahiaUser user,
ProcessingContext jParams,
StateModificationContext stateModifContext )
Example:
final WorkflowService workflowService = WorkflowService.getInstance();
final int contentCtnrWorkflowMode =
workflowService.getWorkflowMode(ctnrToValidate);
// If ContentObject has a linked workflow, we set it to the Std workflow
if (contentCtnrWorkflowMode == WorkflowService.LINKED)
{ workflowService.setWorkflowMode(ctnrToValidate,
WorkflowService.JAHIA_INTERNAL, null, null, jParams); }
final JahiaSaveVersion saveVersion =
ServicesRegistry.getInstance().getJahiaVersionService().getSiteSaveVersion(
jParams.getSiteID());
final StateModificationContext stateModifContext = new
StateModificationContext(
new ContentContainerKey(ctnrToValidate.getID()),localesSet);
workflowService.activate(ctnrToValidate, localesSet, saveVersion, jParams,
stateModifContext);
© 2007 Jahia Ltd. All rights reserved.
Page 55 of 56
Jahia Book - Chapter 6 - Maintenance
Huge improvement have been preformed regarding content validation in
Jahia 5, and a new class called WorkflowService has been introduced.
ContentObject language states
ContentObject validation
© 2007 Jahia Ltd. All rights reserved.
Page 56 of 56