Update

In this chapter you get an overview of the most important notes for

Minor-Updating within the imperia 10(i10) versions,
Upgrading from i9 to i10, and
Migrating from i8 to i9.

Note

We support the current versions of the last two Major Releases.
Example:"End-of-Lifetime" of imperia 10 is when imperia 12 is released.

Migrating to a Different Document Storage System#

Important

Before making any changes to the document tree, make sure to back up the current one.

imperia provides an easy way to change the document storage system. To do that proceed as follows:

Go to Menu->System ->Document Storage and select the desired plug-in from the drop down list.
Run the clone_repository.pl script with the desired options.
Run the site_rebuild_db.pl script to complete the migration.
The clone_repository.pl script is used to copy imperia document trees from one repository to another. The script copies the categories' and documents' IDs exactly from the source to the destination repository.
To define the source and the destination use the following options:

-s, --src=REPOSITORY<:conf file> source repository and -d, --dest=REPOSITORY<:conf file> destination repository

For more information on the available options, run the script with the -h/--help option.

Note
If only the source or the destination repository is present, the currently configured storage plug-in is assumed as the missing option.
If you are using a data storage different than File65, but still want the binary data to be stored in File65, set the system configuration variable BINARY_DOCTREE_PLUGIN to File65.

For more information, read the chapter document storage in the admin manual.

Migrating from a 32 Bit System to a 64 Bit System#

There are several steps that have to be followed in order to migrate imperia from a 32 bit system to a 64 bit one.

Firstly, make sure your imperia is upgraded to the last hotfix and the database schema is updated (using the site_doctree_admin.pl -i administration script).
After everything is up-to-date, the next step is to make sure that serialized objects in network byte order are stored with a fixed integer length, so that data may safely be copied between different architectures.
To do that, call the site_clean_byte_order.pl script (located in site/bin) in the command line:
```
site_clean_byte_order.pl -t
```
And then:
```
site_clean_byte_order.pl -b
```
To see all the available options of the script, call it with parameter -h, --help.

Important
This step must be done on the system you are migrating from!
The final step is to copy imperia from the 32 bit system to the 64 bit one.

Note
This procedure is time consuming and may take a long time to complete.
After the migration is done, update site/config/system.conf, providing the new document root and cgi directory, and cgi-bin/imperia.conf, updating the site directory.
Note
In case the database used is File65, delete the site/documents/sqlite.db file and rebuild the database using: `
```
 site_rebuild_db.pl -t -b`
```

General preparations for Updating imperia (all versions)#

Make sure you can confirm to every requirement in the follow list:

Here, migration does not differ from an update:

Backup your system and database.
Stop the Hermes on both the develop and live systems.
Stop the web server.
Unpack the release archive in a temporary directory.
Run the install.pl script in that directory.
- imperia has a regular release cycle. Each release is a complete imperia installation, which means that after downloading an update, you need to run install.pl.
- The installation script does not overwrite data or configuration files. If in doubt, save the existing files with a different extension (.001, .002, .003, ...).
- It will, however, overwrite ALL files with the following extensions:
  
  .pl, .pm, .pod, .txt, .jar, .js, .de, .uk, .gif, .jpg, .jpeg, .tif, .tiff, .psd, .png, .pdf, .rtf, .doc, .xls, .bat, .sh, .exe
- If you have made changes to these files you may back them up, using the installation script. For this purpose run the script with the -k option. Changed files will be renamed, before copying and will be logged in the installation log.
- During the update, existing files are compared to new ones and in this way a precise imperia version is defined on your system. The installation log shows exactly which files have been overwritten. Save and use it if there are questions for the support.
- A "Skipping" entry in the installation log shows that the file has already been updated to the latest version and there is no need for it to be overwritten.
- If installing on UNIX^®, follow the instructions about access permissions to files, described in Installation UNIX.
When the install.pl script has finished, check the Document Tree status with the site/bin/site_doctree_admin.pl script. To install a new release, proceed as follows:
Read the notes below.
Restart the web server

Minor Updates in i10x#

In the following you get an overview of important notes when updatin from one i10 to the new i10version.

Update von i10.2.3#

Update von i10.2.2#

Update von i10.2.1#

Update von i10.2.0#

Update von i10.1.x#

Update von i10.0.x#

Upgrade von i9x auf i10x#

Tip

If you are upgrading from i9 to i10 the menu will be migrated automatically!

In the past, the migration of menus from i9 to i10 needed additional, manual adapation, and sometimes it happend that menus got deleted and had to be installed again.

These problems now belong to the past!

Upgrade to the lastest version of imperia 9.2 before migrating to imperia 10. If your current installation is imperia 8.6 please read the installation guide of imperia 9. There you will find all the instruction you will need to upgrade to imperia 9.2. Direct upgrade from imperia 9 or imperia 9.1 to imperia 10 might work, but we do not recommend it.
Install imperia 10 on the develop system.

In the following example, the parameter -s specifies the site directory of the imperia system and the cgi directory is set to “none”. In this case, the script will gather the information about the document directory from the system and omit the cgi directory. You may want to omit the cgi directory, if your systems runs in a mod_perl environemnt.

            ./install.pl -s /srv/www/imperia/dev/imperia.de/site -c none

Update the database schema, see Upgrade Database Schema.
Update references, see Rebuild Database
Install imperia 10 on all your target systems.

This step does not differ from the updating procedure. Just execute the install script on the system you want to upgrade and follow the instructions. More detail in ???.
```
    ./install.pl -l -s /srv/www/imperia/live/imperia.de/site
```
Please exchange the /srv/www/imperia/dev/imperia.de/site path with your path.
Restart the web server.
Start the Hermes on both the develop and the live system.
Enter your imperia 10 licence key
Copy the regkey.bin file, you obtained from the pirobase imperia gmbh, to the directory site/config.
Log on to the system and update your license key. If you use a mod_perl environment, the web server must be restarted again afterwards, since the license information is cached.

Notes for migrating i9 to *i10*

The integration of the LDAP in imperia 10 has been revised completely. After database upgrades as well as in case of any changes in the LDAP group structure or in case of problems, you should replicate the LDAP data in imperia with site_replicate_um.pl --backend=LDAP.
- Also, the replication regularly takes place at 01:00 a.m. You can change the time by adapting the new system variable UM_REPLICATION_EXEC_TIME (Format HH:MM, or “no” in order to turn off the automatic replication) to your needs.
- LDAP:
  The format of the configuration file site/bin/LDAP.conf has been slightly changed. The installer automatically adapts the file to the new format.
  The system variables UMLIGHT_PLUGIN and DATABASE_STORAGE_PLUGIN are not needed anymore. imperia automatically sets the new system variable UM_PROVIDERS to “LDAP”, if the LDAP authentication is activated in your installation.
Important

With --debug you generate a more informative output of the replication script.

By setting the environment variable LDAP_DEBUG to true, you will activate for all areas in imperia a comprehensive Debug output.
Adapt Perl code
The most comprehensive API change in imperia 10 includes the API of the user- and group management. But the class file Roles.pm, Users.pm and Groups.pm will not be configured by the installer as they are still valid for the important read permissions for the user- and group data.
Nevertheless, you should adapt the existing Perl code to the new API. To do so, read the guide “Hitchhiker's Guide To The New User Management in imperia 10.1” which is to be found under site/docs/UM-i10.txt. The API newly adapted to the Perl Code will be, generally speaking, shorter, more readable and more stable.
CkEditor version: outdated 3 Version will also be delivered, but might have problems in newer browsers
Skins of Slot/Flex/Block-Modules have been updated, a Compatibility layer will also be delivered.
Custom components (e.g. Plugins/Perl-CodeIncludes/Controller) need to be adapted eventually.
See the section DISABLE_8BIT_FILENAMES Variable.

Migration from i8 to i10#

An upgrade directly from imperia 8.6 can work, but is not supported by imperia.
Also, in a "fresh" imperia 10 system the system.conf variables from i8 are not available.

Migration from i8 to i9#

For all Perl extension we recommend a code structure that is similar to the following:

    use strict;

    use Imperia;

    use vars qw ($new $metainfo);

You get the most important objects via following statement:

    my $system_conf = $imperia->common->
    {system_conf}

    ;
    my $doctree_plugin = $imperia->common->
    {doc_tree}

    ;
    my $user_info = $imperia->common->
    {user}

    ;

The call for Variablen is following:

    my $liveServer = $system_conf->
    {'ABS-DOC-ROOT'}

    ;
    my $doc_root = $system_conf->
    {'DOCUMENT-ROOT'}

    ;

Rest of the code ...

    $new = "Ergebnis";

More methods of Perl extension are to be found under perldoc site/modules/core/Imperia.pm.

Notes for migrating i8 to *i9*

With imperia 9.2 access to the user management has been accelerated, see Upgrade Database Schema
With the introduction of the HTML5 Grid the configuration dialogs of the workflow steps are interpreted in regular HTML. Some of these configuration dialogs therefore, have to be migrated via the script site/bin/site_migrate_fxml_to_html.pl. Every plug-in must be migrated separately!
Also, you need the Perl modules XML::LibXML and XML::LibXSLT in order for the migration to work sucessfully. These modules need to be installed before the migration of your configuration dialogs
For more information on the HML5 Grid read Workflows.
In the MAM, preview images of SVG files are now also generated. You need to set following system.conf variable: MAM_THUMBNAIL_SVG_TO_MIME = 'png'
In case of icons of manually set menu items, you need to create them again, i.e. replace them manually.
OCE: Deinstall the old versions, before installing the new version of the OCE or the bookmarklet.
See the section compatibility layer.

All Notes for Update#

Following notes are relevant for Updating within the imperia 10(i10) versions, for Upgrading from i9 to i10, and, partially, for Migrating from i8 to i9.

iWE Configuration#

You need to adapt custom iWE configuration.
The following line, which was necessary until now, has to be deleted, as the reference is being referenced automatically from imperia 10.2.2:

config.customConfig = '/imperia/js/components/iwe2/default_config.js

Rebuild Database#

Since imperia 10.2.4 it includes new parameters: site_rebuild_db.pl -m -t -b, see also the admin manual for more information.

To rebuild the database is necessary:

when Migrating to a Different Document Storage System
when Migrating from a 32 Bit System to a 64 Bit System
for minor updates:

Use the options -m (minimal mode) -U und -A.
when updating from an older imperia version:
1. Start with the minial mode -m
2. Then, align documents and assets of all target systens subsequently, by using following script:
  
  perl site_rebuild_db.pl -t -b --only-targets DEV
when upgrading from i9 to *i10*:
- Execute the Script site_rebuild_db.pl to match the information stored in the site/meta directory of your system to your database.
  It is recommended to execute the script in two seperated steps. The first will create a ToDo list of necessary actions. The second will process the ToDo list.
  1. The following command will clear the previous ToDo list, create a new one and store it to temp/rebuild.todo
```
./imperia.de/site/bin/site_rebuild_db.pl -c -t
```
  2. The following command will process the ToDo list. It is also possible to stop and restart it.
```
./imperia.de/site/bin/site_rebuild_db.pl -b
```
    Note
    
    Please note that this process may take serveral hours depending on the amount of documents and the processing speed of your hardware
Local User Management:
You can force the reconstruction of the user- and group management by the script call site/bin/site_rebuild_db --todo --batch --um-only.
With imperia 10.2.4 the script perl site_rebuild_db.pl -m -t -b has additional parameters. Read Scripts/site_rebuild_db.pl for more information.

Important

For security reasons, imperia does not report failed logins when the database schema is incompitable, but only shows it in the error log of the web server.

Enhancing access to categories#

Access to categories has been accelerated. By activating the cache through the system.conf-variable: "USER_CAT_CACHE" =1 .

Fulltextsearch without Base64#

Fulltextsearch ignores Base64 encoded, internal data. May deactivated by the index.conf-Variable: keepbase64content

Updating SQLite#

Updating SQLite
If possible, update the SQLite to a version >3.8.3. Thereby, you will improve the search results in the Document Browser.

Hermes.conf#

From i10.2 Hermes.conf is mandatory.

Wichtig

This script is not executed automatically when updating or installing initially.

Proceed as follows:

Execute site/bin/site_hermes_plugins_list.pl:
- Windows: C:\Strawberry\perl\bin\perl.exe C:/imp/projects/926/webs/dev/site_hermes_plugins_list.pl -g -q -i Monitor\|Analyzer
- UNIX: perl /imp/projects/926/webs/dev/site/bin/site_hermes_plugins_list.pl -g -q -i Monitor\|Analyzer
Note
- Backslash must be prefixed so that the Shell doesn't interpret | as a Pipe line.
- This script doesn't create multiple Hermes workers but an instance with all plug-ins.
Copy manually the output of the list to site/config/hermes.conf.sample:

perl site/bin/site_hermes_plugins_list.pl > site/config/hermes.conf.sample
Change hermes.conf.sample to hermes.conf.
Note

Following note is relevant for further works with the plug-ins:
- Segmenting Hermes workers can be complex in some cases. For that read the general documentation under: site/config/hermes.conf.sample
- You will find detailed descriptions for applying the Hermes services in the Admin's manual.

Compatibility Layer#

When installing imperia 9 with an existent imperia 8 system, a so-alled compatibility layer will be installed, too.
This compatibility layer is able to interpret some of the former system.conf-variables that are not anymore available in imperia 9.
By that, the project scripts will work further on.
Please note that the compatibility layer provides only restricted functionality in order to facilitate the migration.

Upgrade Database Schema#

As for every major release, an upgrade also includes the migration of the database schema. Other data don't need to be migrated unless you have the newest version of imperia 9.
The user management does not need any migration. But consider that the primary source of all user and group data is the database of the document storage. Thereby, all login attempts will be blocked, if you don't update the database schema.
As in former versions, you update the database scheme by the script call site/bin/site_doctree_admin.pl --upgrade --auto (especially in case of problems with the order of master and copy pages in ther document browser, or with permission difficulties).
Since imperia 10.1 you also have the option --auto that, if needed, automatically rebuilds all tables. This is ecpecially needed if your installation has the file system as the data storage and/or the embedded database SQLite3.

Important
imperia 10 uses foreign keys for the table definition. If you don't use the client-server-RDBMS, but the embedded database SQLite3, consider follong:
In case you want to manually manipulate the database, then, at the beginning of your session, you should activate the foreign keys in SQLite3 by using the statement pragma foreign_keys on in order to avoid a corruption of your data.
Optimizing the database structure (DBMS only)
This step can be omitted, if you are using File65 as your document storage. If you are using a DBMS – like MySQL, Oracle or PostgreSQL – you should vacuum your database to optimize its structure.
```
./site/bin/site_doctree_admin.pl -V
```
When migrating from i9 to i10 :
Before executing site_rebuild_db.pl, following scripts need to be executed first:
- site_doctree_admin.pl -r index_posting -r users -r groups -r users_groups
- site_doctree_admin.pl -r role_acl
- site_doctree_admin.pl -U

Extendend Access Control#

Especially for Target Systems, the access control can be adapted via rule sets as in Apache 2.4. Therefore, copy the file /site/config/access.conf.sample and adapt it to your needs.

Dashboards#

Dashboard customized in imperia 9 won't be available in version 10. The reason for that is the adaption of the dashboards in order to extend the configuration options of widgets.
See also "Upgrade User-Management" under Migration to Version 10x.

Variable `DISABLE_8BIT_FILENAMES`#

By setting 1 this variable forces 8-bit file and directory names upload in a “safe” character set.

Refer to the Admin documentation.