Page tree
Skip to end of metadata
Go to start of metadata

You can upgrade and migrate your Linchpin Theme app and/or your Linchpin User Profiles app to Linchpin Essentials. You will find all important information regarding such an upgrade here.

Who is this guide for?

The information on this page are valid for both Linchpin Theme-only customers and Linchpin User Profiles-only customers. It does not matter what app you are migrating from, the procedure stays the same. All existing data and configuration is carried over.

Migrate to Linchpin Essentials in four steps

Backup your data

To back up your data, please make a copy of the database first. This is usually done by your Confluence system administrator.

We recommend to perform the migration on a test instance first, regardless of whether you have performed a backup or not.

Also, before you begin, please read this knowledge base article and find out if your Confluence version is prone to this bug making certain parts of Linchpin unavailable.

Install Linchpin Essentials

Now, install the latest version of the Linchpin Essentials app.

To do this, either upload the installation file onto your server or install the app via Atlassian Marketplace.

It is not necessary to update any individual Linchpin apps before you upgrade to Linchpin Essentials.

Quality assurance

1) First of all, please make sure that all Essentials apps are listed in the Confluence App ManagerThese apps should also be listed as active.

List of apps that are installed with Linchpin Essentials and have to be active:

  • Collapsible Admin Menu
  • Linchpin Communicator
  • Linchpin Essentials
  • Linchpin Iconfront
  • Linchpin Suite - API
  • Linchpin Theme
  • Linchpin Theme - Confluence Default Theme
  • Linchpin Theme - Login
  • Linchpin Theme - Navigation Menus
  • Linchpin Theme - Sidebar
  • Linchpin Theme - Space Directory
  • Linchpin User Profiles
  • Linchpin User Profiles - Content Responsibility

2) Then, re-index all your pages. You can do that in Confluence administration → Administration → Content indexing → Search Indexes.

More optional steps:

3) Make sure that your Linchpin Theme is activated.

Navigate to Confluence administration → Look and Feel → Themes to do that. Also, please make sure that the navigation menu is activated. This can be done in Confluence administration → Linchpin → Theme → Configuration → Navigation → Display navigation.

4) It might be needed to clear all Confluence caches.

To do this, navigate to Confluence administration → Administration → Cache Management and click on the Flush all button.

Then, perform a quality assurance review on the apps and data as needed.

If you encounter any problems, please contact your account manager or reach out to our support team:

Optional: Deactivate not needed apps

Linchpin Essentials is a bundle featuring Linchpin Theme, Linchpin User Profiles and the Collapsible Admin Menu.

All Linchpin apps can be fully disabled if you don't wish to use them.

To disable an app, navigate to Confluence administration → Manage apps.

Find the app you wish to disable, open its tab and click on the Disable button.

FAQ & self-help

Help! My installation hangs/froze!


If you already have the Linchpin User Profiles app installed, the installation of Linchpin Essentials may hang in very rare cases.


To make sure that your installation can't begin to hang, uninstall the Linchpin User Profiles app before you install the Essentials app. Linchpin User Profiles will be re-installed with rest of Essentials.

Solution for the freeze

If you couldn't prevent the freeze from happening, there is a solution.

Further information on how to solve this issue can be found here:  Installation or update of Linchpin Intranet Suite hangs.

((warning) This article was written for the Linchpin Intranet Suite but it's applicable to the installation of Linchpin Essentials, too.)

I see a license warning for some Linchpin apps. What do I do now?


At some point after the initial installation of the Linchpin Essentials bundle, Confluence might display a license warning for some individual Linchpin apps.


If you've updated your custom set of Linchpin apps regularly in the past, the Linchpin Essentials app might not install the entire set of Linchpin apps in their bundled form. The Linchpin Essentials installer performs a version check in the background. The Essential bundle installs only bundled Linchpin apps that have a newer version than the one already installed on your system.


Don't worry - as long as a valid license for Linchpin Essentials exists, the individual apps will continue to work just fine.

Please do not uninstall or update any individual Linchpin apps. Instead, wait for the next release of Linchpin Essentials!

My Linchpin apps don't work after a migration to Linchpin Essentials.


You migrated you individual Linchpin apps to the Linchpin Essentials bundle and now some apps don't work anymore.


This might be the case if your individual Linchpin apps had a newer app version than the apps which were delivered with the Essentials bundle.

In this case, some things within the app structure and functionality might have changed and the older app version (which is included in the Essentials bundle) can't properly read the information anymore.


Please wait for a new release of the Linchpin Essentials app. A new version of Essentials will include newer app version and fix the problem by installing the newer app and restoring functionality.

Will I lose my data due to the migration?

No. Your data should not be lost during a migration.

If your apps don't work anymore (for example: macros failing to display content properly), it means that something in the app's structure changed and the older version of the app simply can't read the newer information stored in your system. If this happened to you, read the "My Linchpin apps don't work after a migration to Linchpin Essentials." FAQ entry.

Should I ever downgrade an app?

We can't recommend a downgrade of an app. Some downgrades may cause problems due to incompatibility with the newer data or incompatibility with other apps.

If you wish to try and downgrade the apps instead of waiting for a new Linchpin Essentials release, please use a test instance first. And remember that you do this at your own risk.

Do I need to do a test run first?

At least we strongly recommend to perform the migration on a test instance first. It's just a safer bet - regardless of whether you have performed a backup or not.

My apps are missing valid licenses and display warnings after the update.


You upgraded from Linchpin user Profiles/Linchpin Theme to Linchpin Essentials and increased the amount of user licenses.

Now some apps are marked with a red label and display a warning that an upgrade is required.


1) Uninstall all apps which show the "Upgrade Required" warning.

2) Re-Install the same version of Linchpin Essentials once again.

I use Confluence 7.3.x or older and experience troubles.


In some cases, a Linchpin app or a third party app update makes some Confluence areas not accessible and Linchpin macros/functions are not working as expected. This is particularly relevant for (really) old Linchpin User Profiles apps.

This issue is related to a Confluence bug reported to Atlassian in CONFSERVER-22390.


Our knowledge base offers a workaround for this issue. Please click the following link to learn more: Knowledge Base - Parts of Linchpin or Confluence not accessible after update.


Update Confluence to one of the versions listed as fix versions in CONFSERVER-22390.

After the migration

Once you migrated your individual app(s) to Linchpin Essentials, you might want to check out our documentation on First Steps with Linchpin Essentials.

This page was last edited on 05/07/2021.