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:

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.

  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.

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

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

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.

 

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport