MigratingZimbra Calendars and ContactsToOffice 365withZ2O365.exe |
|
| Last Version:
Product Version: |
February 2019
0.8 |
Copyright
Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Sumatra Development LLC.
2019 Sumatra Development LLC. All rights reserved.
Microsoft, Active Directory, Outlook, Windows, and Windows Server are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
The names of actual companies and products mentioned herein may be the trademarks of their respective owners.
Table of Contents
Overview – Train Hard, Fight Easy! 3
Email Migration into Exchange Office 365 5
Microsoft’s Built-in Migration 5
Z2O365 Works for Office 365 — ONLY 12
What does NOT migrate into Exchange 22
Other aspects of the complete migration process 23
Contact Sumatra Development 25
Zimbra Calendar Migrations
This guide explains how to take legacy calendar, and contacts data from Zimbra and insert it into Office 365.
What Zimbra Calendar Migration Involves
This is a fast, simple, inexpensive method for moving calendar and contacts from Zimbra to Office 365.
Since 2001 Sumatra Development has been doing full-state migrations of legacy calendar systems, where meetings are functional meetings and guest lists are functional in meetings.
This is our answer to demands for a less expensive, simpler, faster migration path for smaller sites and enterprises that do not need full-state meetings.
If you can successfully migrate your email (which should be low to no charge) you can successfully migrate your calendar and contacts. Your total software budget for this will be under US $1000.
This is the solution before you.
Overview – Train Hard, Fight Easy!
Regardless of the method, number of users, servers, or additional engineering requirements you have, we recommend three things.
- ALWAYS run a test BEFORE going into production.
- ALWAYS run a test BEFORE going into production.
- ALWAYS run a test BEFORE going into production.
We cannot state enough the importance of testing prior to deployment. The most successful migrations we have seen have been the ones with the most preliminary testing. Our motto comes from Marshall Zhukov via the Navy SEALS: Train hard, fight easy.
Flat calendar migrations via Z2O365.exe are specifically designed to be done with less testing and quicker deployments.
For any full-state migrations (where meetings migrate as meetings with responses, conference rooms, and attendees) the earlier you start, the better and easier the process is.
Your sequence
Your email migration is going to take at least one order of magnitude elapsed time longer than your calendar migration. It’s just a matter of simple math. The volume of email overwhelms the volume of calendar and contact data in any real-world production system.
With that in mind, the is the procedure we recommend:
- Provision your users and do a first-pass email sync
- Migrate calendars, contacts, and (when the Graph API allows) tasks
- Run final email sync
- Cut users over to production system
- Cut over MX records, Outlook profiles, etc.
Email Migration into Exchange Office 365
You have two good inexpensive (basically free) options for moving your email into Office 365. We are going to assume you have done your email migration with one of these methods and are familiar with Office 365 permissions and accounts.
We are also assuming you have your email migration under control and will be using the permissions you have already assigned going forward to move calendars.
If you want to read Sumatra’s guides on email migration our collected experience is on our blog at: https://calendarservermigration.blogspot.com/
imapsync
We have found imapsync to be an excellent product for email migrations. It is inexpensive, efficient, and effective. We at Sumatra do not profit from your use of imapsync. The developer gets all of the funding you supply him. And for a minimum of 50 Euros and a maximum of 100, there is no reason a seasoned Exchange administrator could not migrate all of their email with imapsync.
Please see our blog postings MDaemon Mail to Exchange via imapsync and imapsync vs PST: Tonnage and Speed as well as any other recent email migration postings on our blog.
Microsoft’s Built-in Migration
Sure. It’s there and it’s free. And it’s a black box with very few options. Your call. If you have problems See the Microsoft Troubleshooting Guide https://support.microsoft.com/en-us/help/10062/troubleshooting-issues-with-imap-mailbox-migration
O365 Migadmin* Permissions for Migrating
* We use “migadmin” from here on to mean migration administrator.
For an email migration Microsoft has you set very generous permissions.
We have set calendar migration to use the same permissions.
For reference see:
https://docs.microsoft.com/en-us/Exchange/mailbox-migration/assign-permissions-for-migration
| Add-MailboxPermission
-Identity “Jimi Hendrix” -User migadmin -AccessRights FullAccess -InheritanceType all |
These would of course all be on one-line but we break them here for convenience and readability.
O365 Graph Permissions for Migrating
This application uses Microsoft Graph, and follows its permissions reference so that this application can obtain access without a user
There are THREE STEPS you must follow
- Find your Office 365 Tenant ID
- Create a new App Registration for the Z2O365 application
- Update the appsettings.json file
This is the walk-through:
- Find your Office 365 Tenant ID in the Azure AD Portal:
- Login to your Microsoft 365 Admin Center or Microsoft Azure as an administrator.
- We found the “PREVIEW” version to be a better experience (as of 1/30/2019)
NOTE: if you select preview, you can skip this step — you will be able to see the tenant id in the second step
-
- In the Microsoft Azure portal, click Azure Active Directory.
- Under Manage, click Properties. The tenant ID is shown in the Directory ID box
- Create a new App Registration for the Z2O365 application
- Login to your Microsoft 365 Admin Center or Microsoft Azure as an administrator. (you just did this above)
- In the Microsoft Azure portal, click Azure Active Directory.
- Under Manage, click App registrations (preview)
- Create a new Registration
- Enter a name (your choice)
- Select accounts in this organizational directory
- Click Register
- Under View API Permissions, Add permissions calendar read/write, contacts read/write
- Grant Admin Consent
- Under Certificates & Secrets, create a Secret
- Update the Z2O365 appsettings.json file
- Under the AppSettings, add the information from the prior steps:
- The APP Name
- AppTenantID
- AppID
- AppClientSecret
Z2O365.exe
Requirements
Make sure that your environment meets the following software requirements.
Office 365
.NET Framework 4.6.2 or better
A License Key from Sumatra
Trial Version
The trial version works EXACTLY as described here except the Trial Version:
- Does NOT need a license key
- Inserts 10 calendar events from the last 7 days for any users you migrate (recurring events in this period will be recurring events through their entire duration)
- Inserts 10 contacts
Z2O365 Works for Office 365 — ONLY
- We assume you are migrating into Office 365 aka https://outlook.office.com.
- We use Microsoft Graph in this application. Graph has some limitations:
- Graph Does NOT work for on premises versions of Microsoft Exchange
- See the section below for a list of “What does not migrate”
Z2O365.exe
.
Sumatra delivers Z2O365 in a “zip” file. Z2O365 is a Microsoft Windows Application requiring .NET Framework 4.6.2 or better. Unzip the file into any directory you choose.
Before you can execute the application, you must configure it.
You execute the application by double clicking on Z2O365:
This will bring up an Office 365 dialogue box asking you to sign in with your system administrator credentials. Do so and the application will then start to execute:
Running it will look like this:
Logfiles are automatically created at each run-time with the canonical name: z2o365_output.log If you have trouble and are contacting us for support we are likely to ask you for this log file.
Configuring Z2O365.exe
.
To make your migration simple to execute we place all configuration parameters for your legacy Zimbra system and your migration preferences in a file appsettings.json.
Edit this with your choice of text editor.
First you will need your Zimbra domain, ports, and admin user ID and passwords.
Your license key from Sumatra goes in the “licensekey” field:
This key is specific to your target domain and bounded by time (usually 30 days).
Account List
The account list file is the list of accounts you want to migrate from/to. Each row contains two values, the Zimbra SMTP address and the Office 365 SMTP address, separated by a comma. This allows you to “remap” Zimbra accounts to Office 365 accounts.
For example, if you want to take three users (Janis, liberace, room 222) for testing purposes, edit this file to contain only that list of users.
| janis@sumatra.io,janis.joplin@sumatra.onmicrosoft.com
liberace@sumatra.io,walter.liberace@sumatra.onmicrosoft.com room222@sumatra.io, room_222@sumatra.onmicrosoft.com … |
If you are using a Microsoft CSV file – then take the user IDs from the first column.
If you are using imapsync the list you use from an iteration file will work (unless you are getting really intricate).
To get a list of all accounts in Zimbra and save it in a file called accounts.txt:
| Zmprov -l gaa >accounts.txt |
This is an excellent start for your user list – though you will need to modify it. First, we suggest you remove administrator, anti-virus, and other non-migrated accounts. You will also need to add the Office 365 SMTP address to the file. Here is an example of Zmprov’s output:
The list is specified here in appsettings.json. JSON requires you “double quote” the backslash:
UNDO
One of the great benefits of our technology is UNDO!
If something goes wrong with your migration (like inserting data into the wrong user, not that that has ever happened in the real world or anything….) you can remove the data Sumatra’s application inserted, leaving all other data in place. We urge you to test this feature. It’s a very powerful feature that will keep you from having to revert to backups in the event of catastrophe. It’s really cool – you should insert some items to a test calendar. Open that calendar, then run an Undo – and watch calendar events disappear!
If you have to UNDO – set “run” to “true” in appsettings.json. Before you can UNDO you will also have to enter a confirmation key. It’s a simple failsafe that prevents heartache later. You can change this key to any word/phrase you prefer.
Invoking Z2O365 will read the userlist and remove all Sumatra-inserted data from the list of users therein (currently calendar events and contacts).
You WILL need to type the ConfirmUndoKey before it executes.
These are the results:
Post-Migration Convenience
Sumatra uses Outlook’s built-in category capability to make your life easier post-migration. Searching for the category ZimbraMeetingsYouOrganize akkows you to find and re-establish your meetings by proposing them to other users (keep in mind – in our full-state migration this is unnecessary).
Similarly, recurrence patterns unsupported by Microsoft Graph are also readily found.
You can find ALL of these either via calendar List View:
Or define category colors to match the category in which case they are readily found by inspecting your calendars.
Which is readily found in a calendar:
What does NOT migrate into Exchange
The following table outlines explicitly what is not migrated from Microsoft Exchange 2013 to Exchange
Data we do not migrate:
- Zimbra tags become Outlook/Office 365 Categories. Colors are a user preference and may differ between Zimbra and Outlook/OWA until set by user.
- Attachments to calendar events. Zimbra APIs do not allow access to attachments.
- Tasks are not supported by Microsoft Graph in production-quality API releases.
- Some monthly and yearly recurrence patterns are not supported in the Microsoft Graph API. That is: First WEEKDAY or N’th Weekend day of the month. We insert these into Office 365 with our best guess and note them in the notes field of the event. Users can find them easily in Outlook by searching for the keyword “ZimbraRecurrencePatternNotMigrated.” This can be configured in your appsettings.json file.
- User defaults (including work hours) – though this you can handle yourself.
- “Exceptions” to recurring items are created as stand-alone items and disassociated from the series. Zimbra creates exceptions for any number of reasons, such as change of date/time/subject/agenda/location, as well as when an attendee changes their response to a meeting request.
- This version creates your meetings as appointments. It does not create meetings, add attendees, re-propose meetings, nor re-create responses. We do, however, put the guests you’ve invited and their responses in the body of the appointment. If this is something your organization must have –Sumatra has the solutions! Our technology does what we refer to as a “full state” migration. If that is your organization’s business requirement, please inquire.
- Contact pictures (another form of attachment) do not migrate.
Other aspects of the complete migration process
Delegate Migration
Since Zimbra consciously decided to emulate as much Microsoft functionality as explicitly and exactly as it could, you have a high chance of migrating your Delegate access successfully. But please consider if you wish to be propagating a culture of “maximum access.”
BEWARE:
Migrating Zimbra permissions to Office 365 does not automatically set up menus for user access via Outlook or OWA! In order to do this you need to set -SendNotificationToUser and the user must respond.
To extract Zimbra delegate permissions:
Zmmailbox will give permissions for any mailbox or calendar you want as follows
./zmmailbox -z -m janis@sumatra.io gfg /Inbox
./zmmailbox -z -m janis@sumatra.io gfg /Calendar
For reference: https://wiki.zimbra.com/wiki/Zmmailbox
Shows us that Jimi has Read permissions on Janis’s calendar with the “p” meaning he is allowed to see Private appointments.
This also works for tasks and contacts.
To save to a text file append ‘> permissions.txt’
See: https://wiki.zimbra.com/wiki/Ajcody-User-Management-Topics
Permissions exist as per the following table:
r = read
w = write
i = insert
d = delete
x = accept/decline invitations
a = administer
P = allow to see Private appointments
Using PowerShell to SET permissions in Exchange is straight-forward.
To insert Zimbra permissions into Exchange:
Use:
Add-MailboxPermission in PowerShell
Add-MailboxFolderPermission -Identity jimi@sumatra.io -User janis@sumatra.io -AccessRights Editor
This will give Janis editor delegate access to Jimi’s mailbox.
And of course, you will need to manipulate or edit the text file you originally extracted from Zimbra. But this is not beyond high school programming or scripting.
You can also delegate other folders like jimi@sumatra.local:\Calendar and so forth with Add-MailboxFolderPermission
| # this adds Janis as calendar delegate to Jimi’s calendar, but without access to private items.
Add-MailboxFolderPermission -Identity jimi@sumatra.io:\Calendar -User janis@sumatra.io -AccessRights Editor -SharingPermissionFlags Delegate -SendNotificationToUser |
| # this adds Janis as calendar delegate to Jimi’s calendar, WITH access to private items.
Add-MailboxFolderPermission -Identity jimi@sumatra.io:\Calendar -User janis@sumatra.io -AccessRights Editor -SharingPermissionFlags Delegate,CanViewPrivateItems -SendNotificationToUser |
See also: How to use Powershell to set delegate for user mailbox in Exchange 2010 and Office 365
Again, just because you can migrate permissions does not mean you should. You will likely perpetuate security issues for users who have changed roles and should no longer have access to some accounts! Your migration is the best time to review all of these!
Seriously talk this over in your organization.
Contact Sumatra Development
We never learned anything listening to ourselves talk.
We only learn it when you folks tell us what you want.
If it involves calendaring technology, feel free to contact us!
The Managing Partners of Sumatra can be reached at:
Check us out at www.sumatra.com as well as
Our blog:
http://calendarservermigration.blogspot.com/
And Twitter: