Purpose

Hipchat Server and Data Center reached end of life in 2020.  To ensure any Hipchat emoticons used on Confluence pages continue to display correctly after your Hipchat server has been shut down, you can migrate these emoticons to Confluence. 

After migrating, you won't be able to add new custom emoticons, but you will be able to continue to view and insert your existing Hipchat emoticons. 

Solution

Follow the procedure below to migrate your Hipchat emoticons to Confluence. Our support team can provide you with the migration plugin. 

Requires Confluence Server or Data Center 7.0 or later. 

Step 1: Disable Hipchat system apps

Disable the Hipchat system apps used to connect Hipchat to Confluence:

1. Go to Administration > Manage apps.
2. Search for the Confluence Emoticons Hipchat plugin system app and select Disable.

Make sure you don't disable the Atlassian Hipchat Integration Plugin Core plugin, as this is required during the migration. 

Step 2: Install the new emoticon app

Download and install the Confluence Custom Emoticon plugin app:

1. Please raise a ticket to Atlassian Support to obtain a copy of confluence-emoticons-plugin-x.x.x.jar file.

   Notes for Atlassian Support

   Please obtain the plugin jar file from CONFSRVDEV-14977 - Getting issue details... STATUS

2. Go to Administration > Manage apps.
3. Select Upload app.
4. Browse for the Confluence Custom Emoticon plugin app and follow the prompts to install it. 

Step 3: Turn on additional logging

To be able to see the progress of the migration, enable additional logging in Confluence:

1. Go to Administration  > General Configuration > Logging and Profiling.
2. Enter com.atlassian.confluence.plugins.hipchat.emoticons.service  in the Class/Package name field.
3. Set the logging level to DEBUG.
4. Select Add entry.

You can remove this entry once the migration has completed successfully. 

Step 4: Run the migration job

To start the migration:

1. Go to Administration  > General Configuration > Scheduled Jobs
2. Locate the Migrate HIpchat Emoticons to Confluence job and select Run.

Check the <home-directory>/logs/atlassian-confluence.log to see the migration progress. Once the migration is complete, you'll see a line confirming the number of emoticons migrated: 

migrateAllEmoticons HipChat Emoticon migration Completed. Migrated 300 emoticon(s)

If you're running Confluence in a cluster, this will be logged on the node that you were accessing when you triggered the scheduled job. 

Step 5: Shut down Hipchat

Once you've confirmed your emoticons are available in the editor, you can disable the following system apps in Confluence:

• Atlassian Hipchat Integration Plugin
• Confluence Hipchat Integration Plugin
• Confluence Hipchat Plugin

Don't disable Atlassian Hipchat Integration Plugin Core, as this is still required. 

You can now shut down Hipchat.  

Troubleshooting 

If the migration does not complete, or for some reason you need to add additional emoticons, you can run the Migrate HIpchat Emoticons to Confluence job again. Confluence will only migrate any emoticons that had not previously been migrated. 

If in future you need to remove an emoticon, you can do this using the REST API:

curl -u <username>:<password> -i -X "DELETE" <base-url>/rest/emoticons/1.0/<emoticonName>

Replace <emoticonName> with the name of the emoticon you want to delete.