Using the Application¶
The application can be accessed from your IBM Connections site using the extension:
The application initially loads on its "Home" page, ready to use with default configuration. On first use in any single browser session, you should switch to the "API Settings" page to check the default configuration, and update this configuration if required for your environment.
In particular, you may need to change the "Destination Domain" if you run the app in your source Connections environment and need to migrate to a separate environment.
Once configured as required, return to the "Home" page and click "Analyze Communities" to initiate the process.
Depending on the size of your environment, the analysis may take some time.
Once complete, the list of Communities will be displayed. This includes filtering that defaults to show only Communities valid for migration from CCM to Files.
Current details for quota and current size of Files within each Community is shown.
Test mode is provided to give an analysis of the Library prior to the actual migration. Note that a licence key is required to disable test mode and perform a real migration, and the licence key (if provided to you) must be installed as described in the "Configuring the Application" section of this document.
To migrate one or more Communities CCM to Files, select the checkbox next to each Community name and click "Migrate Communities". (Test mode should be disabled for the actual migration.)
The status log will provide details while processing, showing all Library files and Files folders during the migration set-up (if test mode is selected this is where the process ends).
Details are provided for each file processed as files and folders are migrated to Files.
Once a Migration run has completed an entry will be logged showing a summary of each Community processed and the files and folders found within CCM along with those created in Files. This log file is saved under the "Temporary Files Storage" location. The detailed log is cleared when starting each new analysis, if required, for this log should be manually copied from the page prior to refreshing or closing.
The process of analysis can be re-started by refreshing the page, however, as noted above, this will clear the detailed log.
Regarding file name conflicts¶
When migrating files, the application makes some attempt to work around file name conflicts. This is particularly worth noting when either:
- One CCM library has files of the same name in different folders; or
- One community has two or more CCM libraries with files of the same name.
IBM Connections Files permits files of the same name in different folders, but doesn't permit a top-level file (not in any folders) to have the same name as a file in a folder.
By default, if the CCM Migrator tries to migrate a file and finds that there is already a file of that name in Community Files, it will rename the new migrated file by appending an underscore (_) followed by a number. It will use the number 2 for the first renamed file, increasing the number if the first rename also produces a conflict, and will try up to 20 renames on each conflicting file before giving up. For example, if the file name "My Document.doc" conflicts with an existing Community File, it will be renamed to "My Document_2.doc".
Additionally, for each community, the application checks whether a migration was previously attempted for that community, and avoids repeatedly migrating files which were previously migrated. This means that if a migration of one community was partially successful, but some error prevented completion, the error can be fixed and the migration repeated without having to clear out previously migrated files or producing duplicates. Important: Migrations performed before this functionality was added to CCM Migrator (on 11 Feb 2019) will not be detected, due to the reliance on a new style of system logging.
The application's user-interface provides some options to change the above behaviour, as follows:
- Migrate each community from scratch – The default (disabled) state detects whether files were migrated for each community in a previous run, to prevent repeatedly migrating the same files. Enabling this options prevents such detection. This will probably never be necessary.
- Rename files to avoid name conflicts – The default (Yes) option causes conflicting files to be renamed as described above. Select "No" to prevent renaming files, and therefore prevent migrating files with conflicting names.
- Maximum number of renames per file – The number of times to try renaming each conflicting file. Defaults to 20, but any number from 1 to 100 is valid. Ignored if the previous option is "No".
- Prefix text before number for renamed files – The text separating a file's original name from the number, for any files renamed due to conflicts. Defaults to underscore (_), but can be longer than one character if desired.