Exporting and Importing your HipChat Data
Group administrators can export and import HipChat Server data. This lets you do the following:
- Migrate from HipChat Cloud to HipChat Server
- Migrate from one HipChat Server to another HipChat Server
- Back up your HipChat Server data
This page
| If you want to | Do this |
|---|---|
| Migrate from HipChat Cloud to HipChat Server | Contact HipChat Server Support to help you export your data from HipChat Cloud. (For more details, see the Exporting from Hipchat Cloud KB article.) Once you've got your data exported, import it into a HipChat Server deployment. |
| Migrate from one HipChat Server deployment to another HipChat Server deployment | Export your data from HipChat Server deployment and import it into another HipChat Server deployment. |
Back up your HipChat Server data | Export your data from HipChat Server. |
Security
When you export, HipChat creates an encrypted archive file using 256 AES (standard encryption). The archive file is hosted at a unique URL. (If you're exporting from HipChat Server that URL is on HipChat Server.) The download of the file is not secured, but the file is encrypted with a password.
HipChat data that is and (isn't) exported from HipChat Server
Following are high-level details on the data that is and isn't exported:
- When you export, the export includes users, rooms, and room history, by default.
- You can choose to export files and 1-to-1 chat history, also.
- The export excludes integrations, passwords, API tokens, and server settings.
The following sections give more details on which data is and isn't exported from HipChat Server.
For information on data you can export from HipChat Cloud, see the Exporting from Hipchat Cloud KB article.
Users
The following user data is exported:
- Usernames
Note: The users' email addresses are their user names. - Users' @mention names
Note: These are the names used to mention users in chat. The users can set these on their profile pages. - Users' profile pages
The following user data is not exported:
- Users' passwords
- Users' notification settings
- Rooms the users have joined
Rooms
The following table shows which room data is exported:
- The owner of the room
- The type of room (either private or open)
- The room's list of members (if the room is a private room)
- The guest access setting for the room (either enabled or disabled)
Note: If the room has guest access enabled, a new guest access URL is generated on import.
Room History
Messages are exported.
Note: When you have the history retention set to Store at 75 messages (option available in HipChat Cloud) the messages are not exported. (History retention is set on the Group admin > Group info page.)
Files and 1-to-1 chat history
By default, files and 1-to-1 chat history are not exported. When you're exporting from HipChat Server, you can choose to export one or both of these.
Note: When you have the history retention set to Store at 75 messages (option available in HipChat Cloud) the messages are not exported. (History retention is set on the Group admin > Group info page.)
Integrations
Integrations and their API tokens are not exported. After you import your HipChat data into a HipChat Server deployment, install and configure your integrations on that deployment.
Data conflicts when importing
Always import into a clean HipChat Server deployment.
To avoid data conflicts, always import into a clean HipChat Server deployment that you've configured through the HipChat Server Setup wizard and installed a valid license on. If you do import into an existing HipChat Server deployment, be sure usernames (users' email addresses), @mention names, and room names are unique.
If a room, user, or @mention name is not unique during import, HipChat Server assumes the existing room or user is correct and does not recreate it. The messages in the room are added to the existing room and the users' messages are associated with the existing user.
If a user isn't created during the import, HipChat Server does the following with the user's data:
- If the user owns a room, HipChat Server makes the group admin the room’s owner.
- The user’s messages and files are not imported. This means, they’ll be missing from room history.
- The user’s one-to-one chats are not imported.
If a room isn't created during import, HipChat Server doesn't import the room's messages and files.
Data that isn’t imported is reported in an email you receive when the import finishes.
Exporting your HipChat data
You can export your HipChat data from HipChat Server. When you export, HipChat creates an AES-256 bit encrypted archive file.
For information on exporting data from HipChat Cloud, see the Exporting from Hipchat Cloud KB article.
- Browse to the fully qualified domain name you've configured for your HipChat Server, for example https://hipchat.yourcompany.com.
- Log into the web user interface (UI) using your administrator email and password.
- Click Server admin > Export.
- To include files and one-to-one chat history in the export, select the check boxes.
- In the Password and Confirm Password fields, create a password to protect your archive file. You're required to provide this password when you import your data into HipChat Server. We don't store this password, so be sure to remember it.
- Click Export. Depending on how much data you have, it may take a few hours to export the data. When it's finished, you'll receive an email with a link to download the file.
- When you receive the email, click the link in the email to download the archive file.
To learn how to check the status of your export, see Checking the status of your export job.
To automate exports, refer to the shell script hosted here. You'll need to download and customize that script for your specific needs.
Importing your HipChat data archive file
To avoid data conflicts, always import into a clean HipChat Server deployment that you've configured through the HipChat Server Setup wizard and installed a valid license on. If you do import into an existing HipChat Server deployment, be sure your usernames (their email addresses), users' @mention names, and your room names are unique.
- Move the archive file you downloaded from the export email to a URL (either http:// or https://) that your HipChat Server can access.
Note: If your HipChat Server is behind a firewall, you must put the archive file in a web server that your HipChat Server can access. - Browse to the fully qualified domain name you've configured for your HipChat Server, for example https://hipchat.yourcompany.com/.
- Log into the HipChat Server web user interface (UI) using your administrator email and password.
- Click Server admin > Import.
- In the Archive file url field, enter the URL to the file. Use the following format:
http://SERVER_URL/... or https://SERVER_URL/.. - In the Password and Confirm Password fields, enter the password you created when you exported the archive file.
- Click Import . Depending on how much data is in the archive file, it may take a few hours to import the data. When it's finished, you'll receive an email. The email tells you whether the import succeeded, succeeded with warnings, or failed. It lists any warnings and errors the import encountered.
To learn how to check the status of your import, see Checking the status of your import job.
Troubleshooting the import
You're more likely to encounter issues importing when you import into a HipChat Server deployment that already has HipChat data. If that's your situation, be sure your usernames (users' email addresses), users' mention names, and your room names are unique before you try importing your data, again.
The following table lists the error and warning messages you may encounter when importing HipChat data.
| Message | More details |
|---|---|
| Couldn’t decrypt the archive file. Make sure you’re entering the correct password. | You probably provided the wrong password on the Import page. Re-enter your password. Note: Unfortunately, HipChat Server doesn't store your password when you create it on the Export page. If you've forgotten your password, you'll have to export your data again. |
A user you’re importing already exists. The user {} is now mapped to {}. | The user had a username and/or @mention name that already exists on the HipChat Server deployment. The user's data (messages and more) was mapped to the existing user's data. |
| A room you’re importing already exists. The room {} is now mapped to {}. | A room with the same name already exists on the HipChat Server deployment. The room's data (messages and more) was mapped to the existing room's data. |
| The room {}’s owner, {}, is missing. The new owner is {}. | The owner of the room was not imported, so the group admin is now the owner. |
| Failed to create room {}: {} | HipChat Server was unable to create the room during import, for unknown reasons. |
| Failed to add member {}: {} | HipChat Server was unable to add this user as a member of the private room during import, for unknown reasons. |
| Issues found when populating the room | This occurs when setting the permissions on a private room and a room member is a deleted user. A deleted user cannot be added to the allowed user list of a private room. Any messages previously sent by the user are still imported. Note: This means that at some point the user was deleted from HipChat. HipChat keeps the deleted user, so the messages in chat history still show who the sender was. |
| Couldn't delete user | This is an expected error related to guest access. Messages still import correctly. |
| The user, {}, is missing from the list of room members because the user wasn't imported. | The user is a member of a private room, but the user wasn't imported, so it is now missing from the room's list of members. |
| Failed to upload file: {} | The file couldn't upload. |
Couldn’t upload the photo for username. | The user's photo couldn't upload. There could be a number of reasons the photo didn't upload. It's possible a service is malfunctioning or an appliance is out of space. |
| Something went wrong. Try again in a few minutes. | This could appear for a number of reasons. If it keeps happening, check with HipChat Server Support. |
Exporting using the CLI
You can export your HipChat data from HipChat Server using the CLI. Run the following command to export the data:
hipchat export --export
-p your_password
The export and password arguments are required for your export.
| Argument | Valid alternative | Notes |
|---|---|---|
--export | -e | This is the argument that actually kicks off the export packaging process. |
--passphrase | -p | To protect your archive file, you're required to provide this password when you import your data into HipChat Server. We don't store this password, so be sure to remember it. |
where your_password is a password you create to protect your archive file.
The following table tells about additional optional arguments for your export.
| Argument | Valid alternative | Notes |
|---|---|---|
--help | -h | Display help content for exports. Use this as a standalone argument and not paired with the actual export argument. |
--check | -c | Check the status of your export, which can take a few hours, depending on how much data you have. Use this as a standalone argument and not paired with the actual export argument. |
--include_oto | -o | Include 1-to-1 chat history in the export. |
--include_attachments | -a | Include files (attachments) in the export. |
--notify | Space-separated list of email addresses, in addition to the HipChat Server admin, to get an email when the export job is finished. Example: hipchat export -e -p your_password --notify her@example.com him@example.com |
Here's a sample command using for an export that includes 1-to-1 chats and files, while notifying additional people when the export finishes:
hipchat export --export --include_oto --include_attachments --passphrase your_password --notify jim@example.com pam@example.com
For more help with the commands, type hipchat export in the CLI.
Checking the status of your export job
Depending on how much data you have, the export can take a few hours.
To check the status of your HipChat Server export job, run the following command:
hipchat export --check
A message appears giving the status of the export.
Canceling an export job
If you need to cancel an export job that's in progress, you can run the following command:
hipchat export --cancel
Decrypting the exported files
If you want to view your exported files without importing them into HipChat Server, run the following command to decrypt the archive file:
openssl aes-256-cbc -d -in path_to_encrypted_file -out path_to_decrypted_file -pass pass:your_password
The following table explains those arguments more.
| Argument | Notes |
|---|---|
aes-256-cbc | This is the cipher to use to decrypt the file. |
-d | This argument is the command to decrypt the file. |
-in | Use this to specify the path to the archive file you're about to decrypt. |
-out | Use this to specify the path where you want to output the decrypted file. |
-pass pass: | Enter the password you created when you exported the archive file. |
Purging exported files
You can also purge exported files by their age in days. To delete export files that are older than 7 days old, run the following command:
hipchat export --purge-older-than 7
Importing using the CLI
You can use the CLI to import the archive file into HipChat Server. Run the following command to import the file:
hipchat import --import -u download_URL -p password
where
download_URLis the URL to the archive file. For example, http://SERVER_URL/ ... or https://SERVER_URL/..-
passwordis the password you created when you exported the archive file.
For more help with the commands, type hipchat import in the CLI.
Checking the status of your import job
Depending on how much data you have, the import can take a few hours.
To check the status of your import job, run the following command:
hipchat import --check
A message appears giving the status of the import.