Import a Hipchat data archive into Hipchat Data Center
You can import a Hipchat data archive file to quickly migrate users, messages, and files from one deployment to another. See Export and import data from Hipchat Data Center for a description of what a Hipchat data archive contains.
On this page:
Before you import...
You should only import into a Hipchat Data Center deployment that is fully deployed and operational, but empty. If your deployment will use external user directories, run the import before you connect them.
If you absolutely must import into an existing Hipchat Data Center deployment, be sure the users' email addresses, users' @mention names, and your room names are unique.
Import a Hipchat data archive using the CLI
You can use the CLI to import a Hipchat data archive file into Hipchat Data Center.
Before you begin, make sure that the Hipchat Data Center cluster has been fully deployed, and that the database and file stores are working.
To import a Hipchat archive into a Hipchat Data Center deployment:
- Make sure that the Hipchat archive is in a web server location that is accessible by the Hipchat nodes, or is in the
/file_store/shareddirectory of your NFS share host. This may mean that you have to copy the archive file to a location inside the deployment cluster. Run the following command, replacing the
download_URLwith the URL of the archive file (or the path to the archive file on the node), and providing the password you used when encrypting the file at export time.hipchat import --import --url /file_store/shared/hipchat-[datestamp].tar.gz.aes -p password
For more help with the commands, type hipchat import in the CLI.
Check 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.
Data conflicts when importing
If a room, user, or @mention name already exists at the time of import, Hipchat Data Center 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 Data Center does the following with the user's data:
- If the user owns a room, Hipchat Data Center makes the team 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 the importer cannot create a room during import, Hipchat Data Center doesn't import the room's messages and files.
Once the import process completes, Hipchat Data Center sends an email that reports any data that was not imported.
Troubleshooting imports
You're more likely to encounter issues importing when you import into a Hipchat Data Center deployment that already has Hipchat data. If you absolutely MUST do this, be sure your usernames (users' email addresses), users' mention names, and your room names are unique before you import your data.
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 Data Center 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 Data Center 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 Data Center 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 Data Center was unable to create the room during import, for unknown reasons. |
| Failed to add member {}: {} | Hipchat Data Center 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 Data Center Support. |