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 toDo this
Migrate from one Hipchat Server deployment to another Hipchat Server deploymentExport 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:

  • (tick) When you export, the export includes users, rooms, and room history.
  • (info) You can choose to export files and 1-to-1 chat history. 
  • (error) The export excludes integrations, passwords, API tokens, users auto-join information, and server settings.

The following table gives more detail 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.

WhatIncluded in export?Notes
Usernames(tick)

These are the users' email addresses.

(info) All users are included in the export, including inactive (or "deleted") users.

User @mention names(tick)Users set these on their profile pages, and they're used to mention users in chat.
User profile pages(tick)
User passwords(error)User passwords are never exported. If necessary, an administrator can reset user passwords after an import.
User notification settings(error)
Rooms each user has joined(error)
Room name(tick)
Room owner(tick)
Room type(tick)This is the room's privacy setting: public or private.
Room member list(tick)This is only included for private rooms.
Room's guest access setting(tick)If the room has guest access enabled, a new guest access URL is generated on import. 
Room message history(tick)/(info)

History retention settings can change how this works.

(info) If you are exporting from Hipchat Cloud, and have a retention period of 75 days or fewer, message history is not exported.

Archived rooms(tick)Archived rooms are included in the export, along with their "User archived the room" or "User unarchived the room" messages.
Deleted rooms(error)
Files(info)

Not exported by default. If you export images, the original file is included in the export, but thumbnails are not.

History retention settings can change how this works. (History retention is set on the Group admin > Group info page.)

1-to-1 chat history(info)

Not exported by default.

History retention settings can change how this works. (History retention is set on the Group admin > Group info page.)

Integrations(error)Integrations and their API tokens are not exported. You must reinstall and configure integrations after importing a Hipchat data export to a new deployment.
Integration API tokens(error)

Data conflicts when importing

Always import into an empty 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.

  1. Browse to the fully qualified domain name you've configured for your Hipchat Server, for example https://hipchat.yourcompany.com/.
  2. Log into the web user interface (UI) using your administrator email and password. 
  3. Click Server admin > Export.
  4. To include files and one-to-one chat history in the export, select the check boxes.
  5. 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.
  6. 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.
  7. 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.

Be sure to check the /file_store/ partition free space usage using the 'df -h' command before executing the export. As a rule of thumb, it is advised to have around 2.5x the amount of available space in relation to the amount of used space on this partition. This is to ensure that the exporter will have plenty of space to export, move and encrypt the data being exported. See Increasing disk capacity


Importing your Hipchat data archive file

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 your usernames (their email addresses), users' @mention names, and your room names are unique. 

  1. 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. 
  2. Browse to the fully qualified domain name you've configured for your Hipchat Server, for example https://hipchat.yourcompany.com/.
  3. Log into the Hipchat Server web user interface (UI) using your administrator email and password. 
  4. Click Server admin > Import.
  5. In the Archive file url field, enter the URL to the file. Use the following format: 
    http://SERVER_URL/... or https://SERVER_URL/..
    (tick) You can also use a path to the archive file on the host instead of a URL.
  6. In the  Password  and  Confirm Password  fields, enter the password you created when you exported the archive file.
  7. 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.

MessageMore 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 userThis 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.

ArgumentValid alternativeNotes
--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.

ArgumentValid alternativeNotes
--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.

ArgumentNotes
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.

The export archives are encrypted with OpenSSL version 1.0.1.

If you use OpenSSL version 1.1 to decrypt the archive, add the parameter "-md md5", when you specify the password.

openssl aes-256-cbc -d -in path_to_encrypted_file -out path_to_decrypted_file -md md5 -pass pass:your_password


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

Always import into a clean Hipchat Server deployment. 

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_URL is the URL to the archive file. For example, http://SERVER_URL/ ... or https://SERVER_URL/..
  • password is 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.


Last modified on Apr 12, 2019

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.