32.1 Overview of Folder Structure Archive

Folder Structure Archive can be used to archive the folder structure and optionally its associated content for Contribution Folders (supported by the Folders_g component). The structure of the folders is archived through database table replication. You can configure which folders (along with all subfolders) should be archived. The folder archives can be accessed by the Archiver utility for further processing (for example, replication or transfer to a different Content Server instance).

Note:

Folder Structure Archive does not support Folders. The Archiver utility can be used to move Folders structure and content. For details, see Chapter 33.

The FolderStructureArchive component is installed, but disabled, by default with the Content Server instance. To use the component you must enable it with the Component Manager.

Folder Structure Archive has several uses, including:

As a backup tool: Back up the folder structure (including its content, if desired) and store it in a safe place to be restored in a server malfunction or other calamity.

As a duplication tool: Copy the folder structure (including its content, if desired) and create an exact copy on a different computer to simplify multi-server setups.

As a synchronization tool: Keep the folders environment between two systems synchronized (for example, a development system and a production system, or two identical, redundant systems). Folder archives created using this component can be transferred or replicated to another system.

Important:

Before using Folder Structure Archive, please ensure that you read the Section 32.2.

32.2 Important Implementation Considerations

Please note the following important implementation considerations:

Folder Structure Archive cannot be used to replicate Site Studio websites. The folder tree on the Folder Archive Configuration page will include all Site Studio website folders, and you can archive and replicate them to another system. However, the replicated website may not work correctly on the target system. If you want to replicate a Site Studio website, use Site Studio's built-in replication features.

If you are using Folder Structure Archive as a duplication or synchronization tool between two systems, it is recommended that you select different initial collection IDs (InitialColID setting) for the source and target system when installing the Folders_g component. If the initial collection IDs are the same and users are allowed to manipulate folders on the target system, there may be collection ID collision errors during the duplication or synchronization process.

You can select a folder in the tree on the Folder Archive Configuration page without selecting its parent folder. This does not affect the folder's virtual folder path; in other words, the virtual path will remain [Parent_Folder]/[Folder], even if [Parent_Folder] is not selected. If you transfer or replicate the archive to another Content Server instance and the parent folder does not exist on that server, it is automatically created, but without the metadata of the corresponding folder on the source server.

If you want to transfer or replicate a folder structure archive between two Content Server instances, it is recommended that you do not manually create the folder structure on the target system. Folders that do not exist on the target system are created automatically during the transfer or replication process. If you do create folders manually, this may lead to out-of-sync errors during the process since the folder names may match, but their underlying unique identifiers (xCollectionID) do not. To help reduce mismatching folder issues, you can use the CollectionIsConsumptionOnly configuration variable to lock the folders environment on the target system.

If you set up replication between two systems using Folders Archive Structure, folders that are created or moved on the source system are automatically created or moved on the target system as soon as content is added to the source folder. Also, if you change the metadata of a folder on the source system, these changes are automatically reflected on the target system as well (as soon as content is added to the target folder). Any folders that are deleted on the source system are automatically deleted on the target system. When a folder is deleted, all its information is gone. However, any folders that are deleted on the source system are not automatically deleted on the target system, which means the two systems are out of sync. This is because the Folders_g component does not keep track of deleted folders. When a folder is deleted, all its information is gone. When the Archiver utility starts the replication process, it does not know what folder(s) to delete from the target system.

Similarly, if a folder move causes the folder to no longer reside in an archived folder, this folder will not be archived and replicated. Consider a system with folders /FolderA, /FolderA/SubfolderA, /FolderB, and /FolderB/SubfolderB. If /FolderA is set up to be archived and /FolderB is not, moving SubfolderA to /FolderB means it will not be replicated. However, if both /FolderA and /FolderB are archived, the move of SubfolderA would be replicated.

If you set up archiving or replication of folders and content items using Folders Archive Structure, the shortcuts of the folders and content items are not archived or replicated.

It is recommended that you use Folder Structure Archive with the DocFolderArchiving component. This component is installed along with the Folders add-on if, during the Folders installation, you chose to preserve the folder structure of content during archiving. When you import a content item that belongs to a folder, this component will create the folder structure on the target system if it does not yet exist on that system. If the identical folder structure (with the same or a different xCollectionID) exists on the target system, then it makes sure that the xCollectionID of the content item being imported into the target system matches with the existing folder on the target system.

Consider a content item on the source system in a folder. The xCollectionID of the content item is 8, and the folder is called FolderA. Now assume that you are using Doc Folder Archiving component to archive that content item to a target system. If FolderA does not exist in the target system at the same level, then Doc Folder Archiving will create FolderA in the target system and then import the content item into that folder. More than likely the xCollectionID of the FolderA will be different than FolderA on the source system. If FolderA already exists on the target system at the same level but has different xCollectionID (for example, 7), then Doc Folder Archiving will not delete that folder. It will keep the folder, but it will change the xCollectionID of the content item that you are transferring from 8 to 7, so that the content item still belongs to the correct folder.

32.3 Differences With Built-in Folders Archiving Features

Folders Structure Archive has its own built-in archiving features, which are accessed on the Contribution Folder Administration Configuration page.

Functionality Differences

Folder Structure Archive can be used alongside built-in archiving features, but its functionality differs in several important ways:

The application can export selected portions of the folder structure, whereas the built-in Contribution Folders archiving features can only export the entire folder structure.

The application can create incremental archives-that is, archives that contain only changed folders compared to an earlier version- whereas the built-in Contribution Folders archiving features can only create archives that contain all items, even unchanged ones.

The application can include both the folder structure and folder content in the archives (depending on the value of a Folder Structure Archive variable), whereas the built-in Contribution Folders archiving features can only export the folder structure and none of the content in the folders.

Unlike the built-in Contribution Folders archiving features, the application allows the creation of multiple source folder archives, which can all be imported, transferred, or replicated to the same target Content Server instance using the Archiver utility.

Processing Differences

If you export the complete folder structure using the built-in Contribution Folders archiving features and you import it into another Content Server instance (using the Contribution Folders user interface), then that server's existing folder structure is deleted entirely and replaced with the imported structure.

If you create an archive using Folder Structure Archive and you import, transfer, or replicate it to another Content Server instance (using the Archiver utility), then the existing folder structure is not deleted, and the archived structure is merged into the existing structure.

32.4.1 Creating a Folder Structure Archive

In the Collection Name list on the Folder Archive Configuration page, select the archive collection that the new folder structure archive should be part of.

In the Archive Name field, specify the name of the new folder structure archive.

Important:

Ensure that you provide an archive name before selecting folders to be included in the archive. If you select folders first and then specify an archive name, nothing happens when you click Add. (The folder tree collapses completely and your folder selection is lost).

In the shaded area, select all folders to include in the folder structure archive. If you click the check box of a parent folder, all its child folders are selected automatically as well. You can also select and deselect any of the child folders individually. A parent folder will only be selected if all of its subfolders are selected as well. If you deselect any of the child folders, its parent folder is automatically deselected, too. This does not affect the virtual folder path properties of the child folder.

Click Add. A message is displayed saying that the folder archive was added successfully. The archive is now included in the Archive Name list, and also in the list of current archives for the Content Server instance; see Section 32.4.3.

32.4.2 Updating a Folder Structure Archive

You can use the definition of an existing folder structure archive, modify it, and create an updated archive. To update a folder structure archive:

Log in to the Content Server instance as an administrator.

Choose Administration, then Folder Archive Configuration.

If required, on the Folder Archive Configuration page assign the archive to a different collection in the Collection Name list.

In the Archive Name list, select the name of the folder structure archive to update. The folder archive tree in the shaded area is updated to reflect the current selections for the archive.

Note:

You cannot save the selected archive under a different name. If you change the name in the Archive Name field and click Add, the archive is considered a new archive and you must select the folders again before clicking Add.

When defining the folder structure archive on the Folder Archive Configuration page, you can select a folder without selecting its parent folder.

If you click the check box of a parent folder, all its child folders are selected automatically as well. You can also select and deselect any of the child folders individually. A parent folder will only be selected if all of its subfolders are selected as well. If you deselect any of the child folders, its parent folder is automatically deselected, too. This does not affect the virtual folder path properties of the child folder.

Note:

By default, if a parent folder is not selected, its source collection ID is not passed on to its child folders. If you want the source collection ID of a folder to be retained even if its parent folder is not selected, set the AllowMigrationOfParentFoldersMeta variable to true (this is not the default). For details, see Section 32.4.4.

Click Update. A message is displayed saying that the folder archive was updated successfully. To process this archive further, see Section 32.4.3.

32.4.3 Using a Folder Structure Archive

After you create a new folder structure archive, its files are located in the Intradoc_Dir/archives/Archive_Name directory, and it is included in the list of current archives for the Content Server instance in the Archiver utility:

The Name column contains the name that was given to the archive when it was created. See Section 32.4.1. The Description column will always say "Archive with folder structures" to indicate the archive's purpose.

The folder structure archive can now be processed further. All normal Archiver functions can be used. For example, the archive can be transferred or replicated to a different Content Server instance.

Note:

For several important considerations that should be taken into account when implementing the Folder Structure Archive component, see Section 32.2.

32.4.4 Configuration Variables

There are several configuration variables that you can use to modify the behavior of folder structure archiving. This section provides information about the types of such variables.

32.4.4.1 Folder Structure Archive Variables

The variables for Folder Structure Archive are set in the following file: IdcHomeDir/components/FolderStructureArchive/folderstructurearchive_environment.cfg. This is a read-only file, so if you want to modify a setting, use the Admin Server: General Configuration page.

The following configuration parameters are supported:

ArchiveFolderStructureOnly=true|false: If this variable is set to true, the archive will only include the folder structure and none of the content items contained in the structure. This variable enables you to create a copy of the folder structure for backup purposes or identical multi-server setup. The default is false, which means that content items are included in the folder archive.

AllowArchiveNoneFolderItem=true|false: If this variable is set to true, the archive will include content items, even if they are not in the folder structure. The content that does not belong to any folder is included in the folder structure archive. If it is set to false, only content items that are in the folder structure are exported. You can use this configuration variable to set up replication for folders and content at the same time; otherwise additional replication for folders and normal content would be required. The default is true, which means that content items outside of the folder structure are also included in the folder archive.

AllowMigrationOfParentFoldersMeta=true|false: If this variable is set to true, the source collection ID of a folder is retained (migrated from the parent folder), even if the parent folder is not selected on the Folder Archive Configuration page. The default is false, which means that metadata of parent folders is not passed on unless the parent folder is specifically selected.

Important:

After modifying a configuration parameter value, ensure that you restart the Content Server instance.

32.4.4.2 Folders_g Component Variables

The variables for the Folders_g component are set in the following file: IdcHomeDir/components/Folders_g/folders_environment.cfg. This is a read-only file, so if you want to modify a setting, use the Admin Server: General Configuration page.

The following Folders_g configuration variable is useful with Folder Structure Archive:

CollectionIsConsumptionOnly=true|false: If this variable is set to true, the folders environment on the Content Server instance is locked, which means the server is set to receive folder data only (hence consumption). Users with RWD permissions are not allowed to create, move, modify, or delete folders. Users with Admin permissions are not allowed to create folders, but they can move, modify, and delete folders.

This setting should typically be set on a Content Server instance that is the target of an archive transfer or replication. It prevents out-of-sync errors between the source server and target server, which could arise if folders were manipulated manually on the target server.

The default setting is false, which means the folders environment on the Content Server instance is not locked.

In a replication setup, any deleted folders on the source system are not automatically deleted on the target system. Even with the target system in consumption-only mode, system administrators can manually delete the affected folder on the target system. (Please note that they cannot create folders.)

Caution:

If users are allowed to manipulate folders on the target server, ensure that you select a different initial collection ID (InitialColID setting) for the target server than for the source server during the Folders_g component installation. Otherwise there may be collection ID collision errors.

Important:

After modifying a configuration parameter value, ensure that you restart the Content Server instance.

Scripting on this page enhances content navigation, but does not change the content in any way.