Updated: 10/4/2016 - Added download link for MigrationTools.zip
Disclaimer: Using this tool is completely a use at your own risk tool and is in no way supported by either the GroupWise team or the Vibe team.

This document covers the tools and process for moving entries from GroupWise Document Management to Novell Vibe.

Information and expertise provided by Rob Luhrs, Bill Ramsey, Bob Hannan

System Requirements

GroupWise 8.x or GroupWise 2012.x
Vibe 3.3

Prerequisites

Vibe 3.3 Installation.

• • Vibe must access the same LDAP user store that GroupWise uses. An LDAP sync must be run. Choose the option to Register LDAP User Profiles automatically. This ensures that the users are the same in Vibe as in GroupWise.

• • You must enable SSL on SOAP for all POAs involved if you intend to use SSL. Note: HTTP is an option just for the export.

• • Clean up all documents by using Mass Document Operations. In the process of running these procedures, you might find a number of orphaned documents and you might also find that some users have been deleted and re-created or lost access to some of their documents. These documents and situations should be cleaned up as much as possible before the migration begins. Handling these situations is easier in GroupWise and then you will avoid having to fix these problems after the migration.

• • To ensure that the groupsWiseDistributionLists are moved over to Vibe (because some permissions are based on that), you need to add the following value to the group filter section of the LDAP configuration: objectClass=groupWiseDistributionList. Then re-run the LDAP synchronization.

• • Any orphaned documents still in the system are moved to the Admin user in Vibe.

General Overview

Novell has developed a set of scripts to assist in the migration of GroupWise Document Management to Novell Vibe. The feature set between the two products are quite different. GW DMS allows users to create, edit and share documents individually as well as through the folder hiearchy. A user has full control of the access rights for each document. Novell Vibe allows users to share documents through global, team, and personal folders. In order to migrate GW DMS documents, each user's personal documents are copied to a Vibe folder within the Vibe user's workspace. Users who originally had access to those documents (essentially a link) now have an entry in their personal workspace that links to the owner's documents. Access controls are maintained via the provided set of scripts.

GroupWise DMS

A GroupWise user creates DMS entries by uploading documents into GroupWise. The user then shares a folder or file to relevant users while granting access controls. When the GroupWise user updates a document, those changes are either immediately available to users on the same post office or replicated automatically to all necessary post offices throughout the GroupWise system.

Novell Vibe

A user or admin creates a personal/team/group area, depending on the use case. The creator decides access controls at that time, and then begins uploading entries and documents. The folder structure is usually built to mimic organization structure and teams. Search and structure are essential, allowing users to find their desired document areas.

Vibe migration is not intended to duplicate the features of GW DMS, but to move documents en masse, maintaining access controls and folder structure. Moving forward, a successful migration will likely include the rearrangement of the documents into a more coherent structure with team/group/user access. This can be manually accomplished with the copy/move functionality within Vibe.

Migrated Documents

Each migrated document is owned by the original creator. If the original creator shared the document with other users, that link is preserved and access control is maintained.

Export Process

Overview

The migration process begins with an export of files. You run an export that communicates to the GroupWise system via web services. You can define a specific user or request all users. Once the export is complete, each user will have an individual XML file that includes all documents and their properties. Files are stored in the file system in a directory structure based on the post office.

After the users and their documents are exported, you will need to execute the import utility. This script reads the exported XML files/documents and uploads the documents into Vibe via web services. After all the users are imported, the import script process then creates links in each document area to the documents you previously had access to.

Export

The export tool exports user's documents and document information from GroupWise. The tool for this is gwdmsexport.exe. The script can be run from anywhere that can connect to the GroupWise POA. Be aware that since large amounts of information and documents are downloaded, using a machine that has close proximity to the GroupWise machine greatly increases performance.

To export all users at once, you need to create a Trusted Application and Key. The GroupWise instructions are here.

1. 1. Leave the Requires SSL and TCP/IP Address fields blank.

1. 1. Remember the application name and note the directory and file name you want.

1. 1. Location for the Key File: Browse to and select the directory where you want to create the trusted application key file.

1. 1. Name of the Key File: Specify the name of the trusted application key file to create. The third-party program must be designed to successfully access the trusted application key file where you create it.

1. 1. Find the file you just created, and edit it in a text editor.

1. 1. Put the application name on the first line, and move the key to the second line. Make sure there is no third line.

The trustfile.txt file might look like this:

DMSTrust
3657C60118B10230444998877B346CDFD5B3657C60218B10000B35331FC4A7GB91B

Place this file in the GwMigrateDMSToVibe directory.

The options for gwdmsexport.exe are as follows:

/host | h
/port
/user | u
/out | o (output directory)
/export (include documents)
/alias (transforms one user's docs to another; not recommended for this project)
/dumpusers (dumps a list of users including uid and email.  Used for debugging)
/proto (by default it is HTTPS. , If you want HTTP, use /proto=http)
/all
/trust (this points to the trusted key file)

Here is a sample command line to export a single user:

gwdmsexport.exe /user=jsmith /host=192.168.1.1 /port=7194 /export /trust=trustfile.txt

The system creates an export.log and a jsmith.xml file. If export was chosen, a directory with the post office name containing the exported files is also created.

For exporting all users, it is still required to put in an existing user. We recommend trying a single user first to test the trust file. When you are satisfied that works, run a command like the following:

gwdmsexport.exe /user=jsmith /host=192.168.1.1 /port=7194 /export /trust=trustfile.txt /all

Import Process

The import process can be run on any machine, but the recommendation is to run it on the Vibe server.

The script to migrate is called: migrate.bat (or migrate.sh on Linux). Most configuration settings are done in the migrate.properties file. The common configuration items are:

dataRoot=C:/install/data
hiddenRoot=C:/install/data/zone1/entry_data

Configure the properties before running migrate.bat. Any changes to the directories below require removing the configuration and then reinstalling it.

The dataRoot contains all the exported information XML files. The dataRoot directory contains default directories:

• • Binders (Copy all the username.xml files to here)

• • entry_data (copy the SDCS.DistLibPo.DLIB19 etc directories containing the files from the export to here)

• • Users_Groups (leave empty)

• • The hiddenRoot directory points to where the documents were exported. This directory contains directories such as SDCS.DistLibPo.Lib42

To run this tool, you must first change permissions on the migrate.sh file in Unix. Then run migrate.bat in Windows or migrate.sh in Unix. Please check with your System Administrator, but the most commonly used command is chmod 744 migrate.sh.

The command line looks like this:

########
Welcome To DMS to Vibe Migration

Select one of the following:
0. Quit
1. Vibe Configuration (Must be done before Migration)

Enter Your selection:
########

The first choice is to run option 1. This installs the required Web services to the Vibe installation. The application walks you through stopping Tomcat and then restarting after installation of the migration-specific tools.

The next step is to run the migration.

########
Welcome To DMS to Vibe Migration

Select one of the following:
0. Quit
1. Migrate DMS
2. Delete Migrated Data
3. Undo Vibe Configuration (Do this after Migration is complete)

Enter Your selection:########

Choose Option #1.

When you have completed the migration, you have the choice to remove the custom migration code from your Vibe installation.

########
Welcome To DMS to Vibe Migration

Select one of the following:
0. Quit
1. Migrate DMS
2. Delete Migrated Data
3. Undo Vibe Configuration (Do this after Migration is complete)

Enter Your selection:
########

Deleting migrated data might not get all artifacts.

Finally, copy the Install/teaming-library/definitions/dms directory to the /opt/novell/teaming/apache-tomcat/webapps/ssf/jsp/custom_jsp directory.

Usage Notes

1. 1. Duplicates. During this process, we have found that users might have many duplicate files in their document directories. Because of the way DMS handled documents, these are actually links to a single document.
      
      For example, in my home directory I might have the following files:
      
      John's Documents
      
      Documents
      
      Document1.doc
      
      Schedule
      
      Subfolder
      
      Document1.doc
      
      The migration process deletes a duplicate reference if it is in the same folder.
      
      If the duplicates are in a different folder, you need to create a link to the first entry:

1. 1. Links. In the documents, you will see a number of places where a user has shared a document with another user:
      
      User1 Documents
      
      Documents
      
      User1sDocument.doc
      
      User2 Documents
      
      Documents
      
      User1sDocument.doc
      
      The migration process, creates the document under User1's documents, and creates a link to the document from User2's documents. When User2 clicks his version of the document, it loads the original (if he has permissions). All permissions should be migrated.
      
      When you have a link to an entry in another user’s directory, you see the title link as follows:
      
      Link->User1sDocument.doc
      
      Clicking that entry redirects you to the actual document if you have permissions.

1. 1. Any orphaned documents still left in the system after your cleanup that are referenced by other users are placed in the Admin Home directory under the admin personal workspaces. All the files are hidden, but any user who had access to them before can see them through their links.

1. 1. Vibe does not support linked documents natively. Moving forward, the best thing to do is to create a new structure to stored documents based on business needs and access controls. Documents should be moved to where they belong in this new structure. Links can then be deleted by the user by going to the folder containing the links and clicking the check box to the left of the link, then clicking the Delete button above the folder. Duplicates should be handled in the same way, by moving them to the appropriate area and removing the duplicate links.

This information was provided by our Engineering and Services organization as they developed these tools/utilities and executed them for a Government customer in the US. Please let us know if you use this information and if you find anything that would be useful to share. The article and best practices will be updated accordingly. We would love to hear your successful or unsuccessful implementations and migrations.