Restructuring categories and directories

imperia allows you to restructure existing categories and their directories in order to adapt to new requirements circumstances, e.g. new structure of a website or redesigned processes.

Categories may contain webpages, i.e. documents and/or assets like media files, and are arranged in the structure as they appear on the website (see also chapter [Categories).

By 'restructuring categories' you not only change the sequence of the documents, but you can also adapt to the working methods of the editors.

In this chapter you will learn in section Restructuring categories how to rearrange the categories structure and in section Restructuring directories how to resort directories independently from the categories.

This separation between the categories' structure and their directories has the following benefits:

When restructuring categories the directories remain unchanged. By that, there will be no conflict when creating the website.
Vice versa: The restructuring of directories has no effects on the categories. By that, the views on categories and thereby the working methods of the editors remains unchanged.
You can, of course, restructure categories together with their directories, too. By that, you can ensure that the links are set correctly and don't have to be updated subsequently in an additional workflow step.

In addition, the process of restructuring (of categories or directories) is separated from the actual implementation (Todo list):

In a first step, you restructure the categories or the directories; this creates a Todo list as a preparation for the restructuring.
In a second step, the restructuring will be run 'physically' by implementing the Todo list. This ensures that the time-consuming process of the actual implementation can be run at a later time than the restructuring.

General Restrictions

Before restructuring, imperia must be set to maintenance mode to prevent inconsistencies due to document processing.
Inconsistencies may occur, for example, when creating new documents in those categories.
The restructuring of categories and directories never affects existing documents, but only newly created ones.
If the Hermes deamon is running, the restructuring will be published directly to the target systems.
The restructuring can only be done by the “superuser” group.:
- The permission for the restructuring can only be defined in the system, not via the imperia UI.
- If the permission is not set, the options Structure->Restructure Categories and Structure->Restructure Directories will be not displayed in the menu. In addition, in the controller tree a ""s"" is added to both the controllers doc_tree as well as path so that they cannot be edited.

Restructuring categories#

The restructuring of categories implies two basic sub-functions:

You can change the sequence of sibling categories. In this case the directories remain unchanged.
You can move categories beneath other categories to create an hierarchy between categories. This can be done including or excluding their directories.

Change the sequence of categories of the same level#

The menu of a website is often derived directly from the structure of the category tree. If you would now like to change the order of the entries in the menu of your website, you can do this in the category management by rearranging the categories belonging to the same level.

Changing the order has a direct effect. You do not need to create a Todo list that is processed later.

To rearrange the categories, use Reorder in the submenu at the end of a category line:

Reorder categories

Please note

* The ***Reorder*** option only affects sibling categories. This does not change the category hierarchy. 
* Therefore, you cannot use this function to turn a main category into a sub-category, nor to convert a sub-category into a main category; use the function in [Move categories](admin.moving.md#move-categories) for this use case.

Resort categories

There a two ways to resort sibling categories:

a) Use the arrow keys to move the category to its new position.

b) Drag and drop the category to the desired position.

Move the category using arrow keys

Select the category you want to move and click on one of the arrow options to move the category one position up or down.
Confirm the process with SAVE or select CANCEL if you want to return to the category management without saving.

The selected category is now displayed at the new position in the category tree. It appears the same for all users.

Reposition the category via drag&drop **

Click on a category and drag it to the desired position while holding down the mouse button. A dashed line indicates where you can drop the category. You can also skip several positions in this way.
Confirm the process with SAVE or select CANCEL if you want to return to the category management without saving.

The selected category is now displayed at the new position in the category tree. It appears the same for all users.

Move categories#

In contrast to changing the sequence of categories of the same level, with this function you are allowed to move categories of different levels, i.e. main or sub categories equally. That means, you can move a sub category into another main category or a main category into a sub category.

As already mentioned, the restructuring is done separately from its actual implementation. Therefore, in this section you will be shown how to move the categories and thereby prepare the Todo list. In the section run the Todo list you will be shown how to implement the moved categories.

Moving document categories is done separately from moving asset categories since assets do not appear in the website navigation and therefore should not be moved into document categories.

For both categories you can decide to simultaneously move the categories' directories. Or you can move the directories separately from the categories at a later time. This can be useful if a category and its directory have been moved, but while reimporting documents, the old directory has not changed.

Note

It is not possible to move the root directoy!
When selecting Move document categories, only document categories will be displayed in the selection dialog. If Move asset categories is selected, only asset categories will be displayed.
No files will be moved, only “transferred”.
Incorrectly moved categories can only be undone by deleting/not executing the Todo list. You then have to move the catogories from the start.

The following instructions apply to both moving document and asset categories. The only difference for asset categories is that asset variants are not displayed in the dialog since unlike in use case copy pages they cannot be moved individually.

Choose menu Structure -> Restructure categories.
Select either MOVE DOCUMENT CATEGORIES or MOVE ASSET CATEGORIES.
In the dialog that opens, two tree views (Source and Destination) of the categories and their associated documents/assets are displayed.
Select the desired category in the Source tree on the left as well as the target category in the Destination tree on the right.
For multiple selection activate the Enable multiple items moving checkbox.
Click PROCEED to continue.

Options:
- I do not want to do any path manipulation now: If this option is selected no path (directories) updates will be done during the restructuring.
- Overwrite existing files: If other files, different than the files directly affected by the restructuring, are affected by the newly computed paths, the process is stopped and the conflict has to be resolved manually. If overwrite existing files is activated, all files will be overwritten. Copy pages of directly affected by the restructuring documents are always overwritten.
- Directory of source category: Lists the source category's directory.
- Directory of target category: Lists the target category's directory.
- *New directory of moved category: Lists newly calculated directory from the source and target categories.
- Patch directories of categories, that match the source category directory: The category tree is searched and if a directory corresponding to the source directory is found, it will be adjusted according to the proposals.
- Only patch directories of subcategories: This limits the previous one to subcategories of the category being moved.
- Only change paths of documents that belong to the moved category: Only paths of documents that are within the category to be moved are updated. If this option is not selected paths to all documents in the source category will be updated.
After selecting the appropriate options, click PROCEED to prepare the Todo list.

The Todo list has been created. You can run the Todo list later or now.

Click PROCESS TODO LIST to run the Todo list immediately. For more information on this see Run the ToDo list.

If the checkbox I do not want to do any path manipulation now and thus not moved the directories, you can do it afterwards. To proceed see the next section.

Restructuring directories and files#

There are two ways to move directories:

Restructure the directories/files
Rename the directories.

Note

Moving or renaming files and directories has no impact on the categories structure.

Restructure directories#

As described above, the restructuring of directories can be done separately from categories. Again, the restructuring is carried out first before the Todo list can be started.

Note

* In *imperia*, directories containing five or more digits are 'counter directories' and will be moved with documents. If counter directories are defined differently in your system, please change the variable `DIRECTORY_COUNTER_REGEX` in the system configuration.
    * For more information on the variable, read the [Configuration Glossary](admin.conf.md#directory_counter_regex-variable).
    * For more information on counter directories, read the [programeers' manual](https://portal.pirobase-imperia.com/pb/imperia-cms-dokumentation-private/programmer-en-11/programming.metafiles/#counter-in-the-directory-name).
* As for categories, moving to the root directoy is not possible, unless the directory is renamed to “/”.

Choose menu Structure -> Restructure directories.
Click MOVE DIRECTORIES/FILES.
In the dialog that opens, two tree views (Source and Destination) of the directories and their associated documents are displayed.
Select the desired directory in the Source tree on the left as well as the target directory in the Destination tree on the right.
For multiple selection activate the Enable multiple items moving checkbox.
Click PROCEED to continue.

Options:
- Source directory: The directory that will be moved.
- Target directory: The target directory.
- New directory:The new path of the moved directory.
- Patch directories of categories, that match the source directory: If paths that match paths of the directory to be moved are found in the category's settings, the latter are adjusted.
- Overwrite existing files: If this option is not checked (default), the process will stop just before it would overwrite a file. This issue has to be fixed manually before proceeding. If this option is activated, all files will be overwritten.
- Click MOVE SELECTED OBJECT to prepare the ToDo list. A status report of the Todo list will be displayed.

The Todo list has been created. You can run the Todo list later or now.

Click PROCESS TODO LIST to run the Todo list immediately. For more information on this see Run the ToDo list.

Rename the directories#

In this section it is possible to either change the name of a particular subdirectory or change the whole path. To do so, select the Rename directories option from the initial dialog.

Choose menu Structure -> Restructure directories.
Click RENAME DIRECTORIES.
Click on the name of the desired directory or choose The Edit-Symbol at the end of the line.
Enter the new name in the New path input field and save the changes with SAVE.
Choose PROCEED. Continue as described in Restructure directories.

Run the Todo list#

As mentioned above, restructuring is carried out in two steps. In the first step, a Todo list is created which is processed in a second step.

Note

Restructuring tasks are performed based on a Todo list. The Todo list is called /site/logs/moving.todo. This file is stored, even after successful processing, until the next task is started.
The interface is regularly updated via AJAX during a processing. The progress is held in the /site/logs/moving_ajax.log moving_process_ajax.output moving_create_ajax.output file, which is deleted automatically at the end of a restructuring.

The restructuring protocol is written in the /site/logs/moving.log file, for example:

[Do Sep 09 17:24:59 2010] [info] Start creating todo list.
[Do Sep 09 17:24:59 2010] [info] Scheduled document '/47/50/54/100' for moving.
[Do Sep 09 17:24:59 2010] [info] Scheduled document '/47/49/51/96' for moving.
[Do Sep 09 17:24:59 2010] [info] Scheduled document '/47/49/53/99' for moving.
[Do Sep 09 17:24:59 2010] [info] Scheduled document '/47/49/52/97' for moving.
[Do Sep 09 17:24:59 2010] [info] Scheduled grafiker file '/2/product_y' 
contained in document '/47/50/54/100' for moving.
[Do Sep 09 17:24:59 2010] [info] Scheduled grafiker file '/2/ii/product_a' 
contained in document '/47/49/51/96' for moving.
[Do Sep 09 17:24:59 2010] [info] Scheduled grafiker file '/2/ii/product_c' 
contained in document '/47/49/53/99' for moving.
[Do Sep 09 17:24:59 2010] [info] Scheduled grafiker file '/2/ii/product_g' 
contained in document '/47/49/52/97' for moving.
[Do Sep 09 17:24:59 2010] [info] Finished creating todo list.

The assignment of the currently started restructuring to the Todo file is done via a ticket.
- The ID of the ticket is specified in the user interface from one step to the next. In this way, their own processes can be seen clearly.
- The additional information needed is stored in the /site/logs/moving.ticket file. This file is automatically deleted at the end of the restructuring.
Only one restructuring process can run at a time. If there is a running process, a warning is displayed. Only when a restructuring is completed, a new process can be started.
Please make sure that the you are in the maintenance mode.

1. Start the Todo list

Click PROCESS TODO LIST directly after moving or renaming categories and directories.

If you want to start the Todo list at a later time, process as follows

Choose menu Structure -> Restructure directories or menu Structure -> Restructure categories.

The STATUS page of the Todo list opens automatically as you have always to run the ToDo list before creating a new one.

Click PROCEED to start the ToDo list.

The Todo list starts running.

The following processes are carried out when the Todo list is prepared :

The system scans the entire category tree to see if any paths must be updated.
The system calculates the new category's NodeID (only in restructuring categories).
For each affected document
- a new NodeID is calculated (only in restructuring categories).
- all references (links to this document) are collected.
- all graphic objects are collected.
If the list is compiled, a summary about how many objects will be changed is displayed. This allows for an approximate time estimation.

The following processes are carried out during the Todo list running:

The system transfers the categories in the data management (assigning the newly created NodeIDs).
Loading all documents, adjusting meta information, storing for:
- version of SiteMeta,
- last version from the archive or the version in a workflow,
- affected Copy Pages.
Reparsing all relevant documents
Loading all references, adjusting meta information, storing for:
- version of SiteMeta,
- last version from the archive or the version in a workflow,
- affected Copy Pages.
Reparsing all relevant references
Explicitly deleting all graphic objects in their old position.
Presenting proposals for manual path adjustments
- in template,
- in flex modules,
- in slot modules,
- in includes,
- in the dynamic.conf, system.conf, smart-meta.conf, FTS.conf, index.conf.

2. Finish Todo list

After the Todo list has been processed, another status page opens where you get an overview report of the moved categories or directories.

With CLOSE you will leave the page.

The restructuring process of categories and directories is now completed.