CloudMigrator Quick Start Guide

One in a series of guides for CloudMigrator.

Migrating from GroupWise to GSuite

The following instructions are designed to assist you in migrating mail from GroupWise to GSuite.

Please make sure that the following pre-requisites are complete before continuing onto the CloudMigrator setup.
Pre-requisites
  • Installed a Novell GroupWise client version which is compatible with your server installation
  • Created a GroupWise trusted application to access your GroupWise users' mailboxes.
  • Set up a Google project and a service account for your destination domain.
  • For information about migrating GroupWise Archives please see the knowledgebase article.
1. Pre-requisites
Creating a Groupwise trusted application

To successfully create a trusted application, you need to be logged into the workstation via the Novell client with full Administrative rights over the Post Office, Domain and Cluster.

For CloudMigrator to impersonate users and read their inbox without their password a Novell GroupWise Trusted Application must be created. Trusted Applications are used by third-party programs in order to securely log into Post Office Agents (POAs) in order to access GroupWise mailboxes. Using the Desktop Version of CloudMigrator you can create a Trusted Application, select Tools > GroupWise > Create GroupWise Trusted Application.

To create a Trusted Application enter the Domain Path, and select Create. The Domain Path is the network location containing the Novell GroupWise Domain database, wpdomain.db and wphost.db

You must have read/write access to this location and eDirectory administrator rights in order to create the Trusted Application correctly. Failure to create the Trusted Application correctly will result in authentication issues.

Setting up a service account and Google APIs

In order to access your users' email, files etc. you will need to create a google project and set up a service account. You will also need to enable the relevant APIs.

Firstly, go to your google cloud console, (login as an administrator if you are not already) and click 'Project' at the top and then 'Create Project'.

Enter a name for your project and click 'Create'.

When you have created your project, click on the options menu in the top left of the page, then 'API Manager', then 'Credentials'. Click on 'New credentials' and then 'Service account key'

Next, select 'New service account', name it anything and select 'Project' and then 'Owner' as the role from the dropdown list, finally select P12 as the key type and click 'Create'. Upon clicking 'Create', a P12 file will be downloaded; this is important for later so keep a note of where you downloaded it.

Dismiss the dialog box and on the right hand side of the page, click 'Manage service accounts' and click the three dots beside your service account, then select 'Edit'

You should now be met with the edit service account window, check 'Enable Google Apps Domain-wide Delegation' and click 'Configure consent screen'.

Next, give your product any name you wish and click 'Save' to be taken back to the previous window. Click 'Save' again.

Now make a note of the email address of the service account you just made as you will need this later to configure CloudMigrator. Click 'View Client ID' in the right most column of the service account table and make a note of that too.

Next, click on the options menu again, then 'API Manager', then 'Library'. This will take you to a page where you can search for and enable various google APIs, just use the search box and the enable button at the top of each APIs respective page to enable to following APIs.

  • Admin SDK
  • Drive API
  • Gmail API
  • Calendar API
  • Contacts API
  • Tasks API
  • Groups Migration API

Nearly there! Once all the APIs are enabled, launch the Google Apps Admin Console for your source domain.

Go to 'Security', then to 'Show More', then to 'Advanced Settings' and then finally to 'Manage API client access'. Enter the Client ID you noted earlier into the 'Client Name' field and paste the following into the 'Scopes' field:

https://www.googleapis.com/auth/admin.directory.resource.calendar, https://apps-apis.google.com/a/feeds/emailsettings/2.0/, https://mail.google.com/, https://sites.google.com/feeds/, https://www.google.com/m8/feeds, https://www.googleapis.com/auth/admin.directory.group, https://www.googleapis.com/auth/admin.directory.user, https://www.googleapis.com/auth/apps.groups.migration, https://www.googleapis.com/auth/calendar, https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/drive.appdata, https://www.googleapis.com/auth/email.migration, https://www.googleapis.com/auth/tasks

Finally, click on 'Authorize' on the right on the 'Scopes' field and an entry for your Client ID and its associated now-accessible APIs will appear. Do this for both the source and destination domains.

2. Select your configuration

If you have not already done so, create a new configuration item by clicking the plus button and then "create a new configuration to get started".

Select the GroupWise configuration item.

You should also supply a license key here before you continue. If you do not supply a key you will be able to setup and configure CloudMigrator but will not be able to perform a migration.

To enter this key, hover over the orange gear in the actions column and navigate to "View license" (one icon to the left) and you will be prompted to apply a license. Alternatively, you can click the name of the unlicensed configuration.

When entering a license, you must first specify the platforms that you will be migrating to and from (see steps 3 and 4). You do not need to set up the platforms yet, just let us know which you will be using so that we can check your license validity.
3. Source Platform - GroupWise

Choose GroupWise as the migration source and enter your GroupWise settings into CloudMigrator and then click next.

  • Server Address - The hostname or IP address of the GroupWise server.
  • Admin Username - The username of an admin user with an active email account on the GroupWise system.
  • Trusted Application Name - The name of the trusted application you created in the pre-requisite stage.
  • Trusted Application Key - The key provided by the trusted application creator after creating one in the pre-requisite stage.

CloudMigrator will now perform a small connection test to verify that the details you have entered are correct. If this fails you may have entered something incorrectly. If you are failing to resolve the issue please contact CloudMigrator Assist via the chat icon.

4. Destination Platform - GSuite

Select GSuite as your destination platform.

Select where you would like your data to be migrated. If you have purchased GSuite for Business or Google Vault you may want to migrate data directly into Google Vault.

To enable Google Vault for your domain, please see the following article: http://support.google.com/vault/bin/answer.py?hl=en&answer=2584132

Enter information for your GSuite admin account.

CloudMigrator will perform a connection test against your GSuite domain to verify that everything has been entered correctly.

If your GSuite system is brand new or for any reason the users being migrated have not been created in GSuite, CloudMigrator can create your users for you. Simply go to advanced settings, to the user settings section and enable Create Users.

5. Select which users to migrate

It's now time to add which users you'd like to migrate.

When migrating from GroupWise you may be able to Get Users from the actions menu. To use this feature, you must have installed a version of GroupWise Client which is compatible with the server installation on a workstation within the network in which the GroupWise server is running. If this option is unavailable, you can manually import users via a CSV file or simply add them individually via the plus icon

At this point you can choose what to migrate for each user, when migrating from GroupWise you can migrate mail , contacts , calendars and tasks .

Enter your user's full email address within the Export Name field. If you have already created your GSuite users then you will just need to enter their username. If you would like CloudMigrator to automatically create your GSuite users make sure you also enter your user's given and family names as well as a strong password.

To migrate appointments from calendar resources only the ‘Resource Name’ is needed, ‘Resource Description’ is optional, and ‘Password’ is not required.

When a resource is migrated using CloudMigrator then the ‘Import Name’ becomes the resource ID within GSuite. If resources have been pre-created in GSuite then the resource ID should be extracted from GSuite and specified for the ‘Import Name’. Resource IDs can be found in the GSuite control panel by clicking on a resource name. The ID required is specified in the control panel as ‘Resource identifier’.

6. Select how much mail to migrate

CloudMigrator lets you decide how much mail you'd like to migrate to your shiny new GSuite system.

If you are changing your email address as part of the migration you can verify that the domain names are correct here. You can also specify specific address replacements in the respective section of the advanced settings.

For more information on domain and address replacements, see this page.

7. Start your migration

Before you start your migration, you must supply a license key. If you have not supplied this key in step 2, you can do it now by clicking the bold link in the red bar at the top of the page. If you do not see the red bar then you are already licensed and don't need to worry!

We know that you may want to start your migration in the middle of the night, or over the weekend, but we don't expect you to stay up in order to do so. With CloudMigrator you can decide to schedule exactly when you'd like the migration to occur.

Start the migration.

8. Review your migration results

During the migration process CloudMigrator will report back in real time exactly who is being migrated and the items being processed. All you now need to do is sit back, relax and wait for your migration to complete.

Check the progress of your migration.

Once complete you can download a full report for your migration.

For more information about this page, please visit the summary page.

GroupWise Advanced Settings

While the default options are recommended for the majority of users, CloudMigrator gives users the ability to customise their migration experience. The following are the advanced options available to those migrating from GroupWise.

Account/Archive Settings

  • Archive Label/Folder Method - Choose to use just one label/folder (as specified by ‘Archive Label’) to migrated archived messages (Single Label), or choose ‘Folder Structure’ to apply the label or folder structure as specified by the archived messages folder structure in the same way that labels/folders are applied to non-archived messages. Choose ‘Label and Folder Structure’ to have both label/folder types applied.
  • Archive Label/Folder - The name of the label/folder created for archived GroupWise messages if ‘Archive Label/Folder Method’ is set to ‘Single Label’.
  • Incoming Shared Folders - Within a user’s mailbox structure, there may be shared folders of other users. Google Apps and Office 365 do not support this concept of shared folders and thus any shared folder from another user will not be updated once in the destination system. It may also require the transfer of lots of data from a single user’s mailbox to many other users. It is recommended therefore that this setting is left at false. Note than any folders that a user has shared with others will be transferred as normal as they are normal folders for the owning user.
  • Message Export Method - choose the way in which messages will be exported from GroupWise folders. Generally this should be left at ‘Quick Messages’, with ‘Filtered’ being an option if ‘Quick Messages’ fails. Use ‘Original’ only if incorrect numbers of messages are exported using other options, and no folder contains more than 4000 messages.

Appointment Settings

  • Migrate Notes - Migrate GroupWise notes as all day appointments.
  • Migrate Appointments from Mail Attachments - Migrate GroupWise appointments that are attached to Mail messages.
  • Incoming Shared Calendars - Migrate incoming shared calendars from GroupWise. This will result in duplication of items between accounts and is not recommended.

Message Settings

  • Category Labels - Apply category labels or categories to migrated messages in both accounts and archives (GroupWise 8 or higher only).
  • Plain Text Only - Use only the plain text body when migrating internal GroupWise emails. Note that emails recieved from outside of the GroupWise system are migrated as normal.
  • Use Expanded Recipients - Use expanded recipients when resolving email recipients. Only turn off when directed by support.

Contact Settings

  • Address Book Processing - Select the address books for migration. Note that if system address books are migrated then contacts in the system address book become personal contacts in the destination system.
  • Incoming Shared Address Books - For GroupWise 8 only, choose to migrate incoming shared address books. For versions of GroupWise below 8 this option is ignored and all address books are migrated.
  • Contact Extraction Language - Select the language in which your contact data is stored (English, German or Swedish only at present).
  • Excluded Frequent Contact Addresses - Enter a list (one per line, lower-case) of email addresses or wildcards of contacts that should be skipped when migrating ‘Frequent Contacts’. To specify wildcard addresses, use the format ‘*@domain.com’, where all addresses that end in ‘@domain.com’ will be skipped.
  • Excluded Sync Addresses - Enter a list (one per line, lower-case) of email address of contacts that will not be included if performing GroupWise System Address Book synchronization.
  • Migrate All Group Members - Turn this on to always attempt to migrate all members of Distribution Lists/Groups, even if the contact would not normally be migrated due to the address book settings. This means you can choose not to migrate the system address book, but user’s personal contact lists that contain addresses from the system address book would still be complete.System Address Book Sync Type – (Google Apps Only) choose whether to sync the system address book with Google Domain Profiles, Shared Contacts or both. The default is to sync with both. See the section on syncing the GroupWise System Address Book.
  • System Address Book Sync Type - (Google Apps Only) Choose whether to sync the system address book with Google Domain Profiles, Shared Contacts or both. The default is to sync with both. See the section on syncing the GroupWise System Address Book.

Other Settings

Note that these settings are ignored when migrating to Office 365.

  • Migrate Signature - Migrate the users GroupWise signature (if set and enabled). Plain text or HTML signatures can be migrated that are encoded as base64 or quoted printable.
  • Migrate Rules/Filters - Migrate the users GroupWise rules to Google filters. Note that only rules that can be mapped to Google filters will be migrated. It is important to migrate filters one time only, or duplicates will be created in Google Apps.
  • Migrate Account Delegation - Migrate account delegation to Google Apps account delegation. Please see the section on ‘Migrating GroupWise Delegates’ for further information.
GSuite Advanced Settings

While the default options are recommended for the majority of users, CloudMigrator gives users the ability to customise their migration experience. The following are the advanced options available to those migrating to GSuite.

Transfer Settings

  • Migration Base URL 1.0 - The base URL for email migration using v1 of the email migration API. This should only be changed for specialized migration scenarios and for normal migrations should not be altered.
  • Migration Base URL 2.0 - The base URL for email migration using v2 of the email migration API. This should only be changed for specialized migration scenarios and for normal migrations should not be altered.
  • Timeout - The time in milliseconds that the tool has to complete sending a transaction to Google before an error occurs. This should be set high enough so that large amounts of data can be sent (further description is available in ‘Migration Strategies’). If a transaction fails using the provided timeout, it will be re-attempted using a larger timeout. While errors occur this will continue with increasing lengths of timeout, up to the retry count. It is better to set this to a very high value to ensure requests get through.
  • Maximum Batch Size - This is the maximum size, in bytes, of a single transaction with the Google servers. Note: The absolute maximum size of any transaction that Google Apps allows is 32MB. Because of the way that messages are created and encoded (XML OR JSON, which is then Base 64 encoded) it is not usually possible to know the exact size of a message until it is created. Messages can be sent in batches, which also make it more difficult to establish the exact size of each transaction. Large batches also increase memory usage significantly and it is recommended that the maximum value of 5MB is used. This setting also has an impact on how long a single message will take to transmit to Google Apps and can therefore affect the requirements for the Timeout setting.
  • Maximum Batch Count - The number of items that will be sent in a batch when transferring contacts and calendar items.
  • Retry Count - The number of times a transaction with the Google servers will be retried if it fails. Note: A transaction could fail for one of a few reasons. If the transport layer fails, that is a transaction could not get through to the Google servers or the transaction times out, then the transaction will be attempted again until the retry count is met – with an increasing timeout value each time. Another possible reason for failure is that the client is sending too many requests per second. In this case, an exponential backoff system is employed where the tool waits for a period before retying any failed transactions (or parts of transactions).
  • Modify Request - Leave at the default unless instructed by support.
  • Custom Parameters - Adds custom headers to Google API requests, for debugging only.

Calendar Options

  • Force Appointment Acceptance - Set this to true to force all appointment recipients' attendance as confirmed.
  • Appointment Privacy - Set the visibility of all appointments. Original will use the privacy setting from the source system, while the other settings will override the original setting and set the specified visibility.
  • Maximum Attendees - Set the maximum number of attendees for any migrated appointments.
  • Default Calendar Timezone - Set the default calendar timezone to use for recurring appointments which have no timezone set in the source system and where the target Google calendar is in UTC.
  • Send Individual Events - Send appointment events as individual items rather than as a batch. Performance is slower than in batches, but may help with some rare issues with rate limiting.
  • Color Categorized Appointments - If the appointment had a category in the source system, apply a colour to all appointments of that category.

Document Options (File and Attachements)

  • Convert Text - Where possible, convert text and word documents to the Google Documents format.
  • Convert Spreadsheets - Where possible, convert spreadsheets to the Google Documents format.
  • Convert Presentations - Where possible, convert presentations to the Google Documents format.
  • Convert Drawings - Where possible, convert drawings (*.wmf) to the Google Documents format.
  • Convert OCR - Where possible, convert images using OCR.

Email Options

  • Google Email Migration API Version - Specify the version of the Google Email migration API to use, or whether to use IMAP.
  • Archive Inbox EMail - Do not place migrated email from the inbox into the inbox within Google Apps. Instead the email will have a label of 'Migrated Email' applied.
  • Apply Inbox Label to Sub-Folders - When a message from the source system was in a folder in the inbox, create the message with both 'Inbox' and 'Folder Name' labels. Set to False to just create the folder label.
  • Modify Sent Address - For sent messages, if the sender does not match the email address of the destination account, modify it to match. This is to allow for sent items to display correctly in the Google Apps interface. Default is true.
  • Email Transfer Delay - Specify the number of milliseconds to wait between sending messages.
  • Maximum Batch Count - Specify the maximum number of messages in a single batch. Specify 0 to let the tool automatically allocate batches. Only applicable for immediate migrations.

Document Options

  • Collection Naming Scheme - When attachments or files are migrated to Google Drive, choose the collection label scheme that will be applied to the migrated documents.
    • Folder Name and Collection Label - migrate documents into a collection based on the folder name the attachment or document originated from, and also apply the collection label specified in 'Collection Name'.
    • Folder Name - Migrate documents into a collection based on the folder name the attachment or document originated from.
    • Collection Label - Migrate documents into a collection specified by 'Collection Name'.
    • None - Do not apply a collection label.
  • Collection Label - Specify the name of the collection label that will be used when 'Collection Label Scheme' specifies that a collection label should be applied to migrated documents.
  • Preserve Modified Date - Attempt to preserve the modified date during a migration.
  • Maximum Results Per Request - The limit on the number of results returned when listing files using the Google Drive API.

Team Drive Options

  • Team Drive Default Organizers - Optionally, specify a list of existing user email addresses that will be assigned as organizers to Team Drives being migrated to. These organizer accounts will then be used to improve the performance of the migration. In the default case the G Suite admin user account will be used to perform the migration to Team Drives, but specifying multiple users here improves throughput by utlizing multiple organizer accounts simultaneously.
  • Team Drive File Permissions - When adding permissions to files within Team Drives choose where these permissions will be applied. Choose from 'File' (the default), 'Root' (where all permissions will be applied on the Team Drive itself and thus inherited down the whole tree) or 'None' (no permissions will be applied)
  • Team Drive Folder Permissions - Team Drive folders cannot directly have permissions. Choose whether to apply permissions that apply to folders from the source at the root of the Team Drive, or not at all.
  • Team Drive Same Domain Migration Operation - When migrating from a Google Drive folder into a Team Drive choose whether to copy the files, or to move them. Note in the case of a move, the skeleton folder structure of the source folder will remain.

User Options

  • Check Users/Resources/Groups Exist - Set this to false if you do not want to check if users, groups or resources exist in Google Apps (useful for testing exporting without creating accounts in Google Apps).
  • Create Users/Resources/Groups - If users, groups or resources (supported source systems only) are not present within the Google domain, create them. If users have not been pre-created within the Google system then this can be set to true to have the migration tool create the users. If the users have not been pre-created and this is set to false then the migration process will fail. Note: Setting this to true requires that the Admin SDK is enabled for the Google domain and also that all details are provided for each user, including name, given name, family name and password. Failing to provide any of these details will cause the creation process to fail for that user. It is generally recommended that users are pre-created in the Google domain before processing with the tool. For resources and groups, only the Resource/Group Name (and Import/Export Names) are required.
  • Change Password On Login - Force users to change their password on next login.

Contacts Options

  • Migrate to 'My Contacts' - Migrate personal contacts to the 'My Contacts' group rather than only to 'All Contacts'.
  • Send Individual Contacts - This should generally be left to true, while slower than batch importing its much more reliable.

Label Options

  • Explode Message Labels - By default, if an email message is contained within a folder structure the label applied to that message will be the same as the folder structure (e.g. 'Personal Folders/My Folder/My Other Folder'). Setting this option to true will create a label for each of the folders (e.g. for the case described, labels of 'Personal Folders', 'My Folder' and 'My Other Folder' will be applied).
  • Create Sub Labels - Create all sub-labels for labels within a message. For example, if a message has the label 'toplevel/midlevel', create both 'toplevel' and 'toplevel/midlevel' labels. This is specifically designed for use with nested labels.

Performance Options

  • Multi-Server Drive Migration - Use distributed locking to allow for Drive migrations to be performed from multiple servers. This can be disabled if using only one server for migration.