Lombiq HipChat to Microsoft Teams Migration Utility Readme
Utility to migrate Atlassian HipChat content to Microsoft Teams. You can use this instead of waiting for official support. We're testing this utility at Lombiq Technologies (a web development company working with Microsoft technologies) with a 4GB+ HipChat export package containing more than 200k messages (in rooms; a lot more with private chats). The tool is intended for very technical users and developers.
Currently the app can import rooms and messages from a HipChat export file into Teams channels under a specific team. See the issue tracker on GitHub for missing features and bugs.
Note that this being a utility with just temporary use simplicity of implementation was favored against long-term maintainability. Note that the guide assumes you're using Windows but everything should work equally well under any OS supported by .NET Core. However, released executables are available only for Windows 64b currently.
Running the app
If you're a .NET developer then grab the latest source and run the app from the source (you'll need at least VS 2017 and 2.2 of the .NET Core SDK). Otherwise download the latest release from GitHub and run the exe file in the zip. Be sure to check the full usage guide below.
Keep in mind that you need to be both a HipChat and a Teams admin in your company for this to work.
- As a HipChat admin export your HipChat data from under you HipChat URL (e.g https://lombiq.hipchat.com), Group admin, Data export. Select to export every kind of data and the whole history. Use a password without any special characters or spaces. Save the file under a path without any special characters.
- Download the OpenSSL binaries if your system doesn't have them already. Recommended is the 1.0.2a (not any other version!) x64 zip from here (direct link to file). Unzip it, run openssl.exe and decrypt the export file with the following command:
aes-256-cbc -d -in C:\path\to\export\file.tar.gz.aes -out C:\export.tar.gz -pass pass:password.
- Use your favorite ZIP utility to extract the gz and tar so finally you'll end up with an unencrypted, unzipped export folder (this will contain folders like rooms and users and some further files like rooms.json and users.json). While this decrypt-unzip could be automated it's a yak shaving of epic proportions (but feel free to contribute it if you wish!) but you'll have to do it once any way.
- Go to the Graph Explorer and log in, confirm the required permissions. Then acquire the necessary permissions as following:
- Click on "show more samples", turn "Microsoft Teams" and "Microsoft Teams (beta)" on.
- Try to run e.g. the Microsoft Teams / create channel operation. You'll get an error that you don't have the necessary permissions. Click on "modify your permission".
- Select the following permissions: Group.ReadWrite.All, User.Read.All. You'll need to log in again.
- Once the permissions are OK then run an API request (it can be any of the samples, even just /me. Copy the bearer token (just the token, without the "Bearer" text) used by the request into the AppSettings.json configuration file under the
AuthorizationTokenconfig. You can e.g. use Chrome DevTools (open with F12 in Chrome) to see this token in the Request headers:
- Specify the rest of the configuration as well:
ExportFolderPath: The file system path to the folder where you unzipped the HipChat export package.
TeamNameToImportChannelsInto: Name of the Teams team where you want all the channels to be imported into. Currently all channels are imported into a single team. This wouldn't be an issue if channels could be moved (https://microsoftteams.uservoice.com/forums/555103-public/suggestions/16939708-move-channels-into-other-teams).
NumberOfHipChatMessagesToImportIntoTeamsMessage: You may be able to guess :). If it's greater than 1 then multiple HipChat messages will be imported into a single Teams message. You can use this to overcome Graph API throttling limitations. It seems that the maximum is about 100, with more HipChat messages the request will be too large.
- Run the app and wait for the import to complete. In the console you'll see status and possibly error messages.
Notable features missing and bugs
Some implementation notes
- Here's some information on the HipChat export's schema.
- Some inspiration is taken from https://github.com/microsoftgraph/csharp-teams-sample-graph.
Contribution and Feedback
The module's source is available in two public source repositories, automatically mirrored in both directions with Git-hg Mirror:
- https://bitbucket.org/Lombiq/hipchat-to-microsoft-teams-migration-utility/ (Mercurial repository)
- https://github.com/Lombiq/HipChat-to-Microsoft-Teams-Migration-Utility (Git repository)
Bug reports, feature requests and comments are warmly welcome, please do so via GitHub. Feel free to send pull requests too, no matter which source repository you choose for this purpose.
This project is developed by Lombiq Technologies Ltd. Commercial-grade support is available through Lombiq.