Documentation's navigation


On this page


Who is this guide for?

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.

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.

Tip

You can export a theming file with the configuration of your Linchpin Theme app before you install Linchpin Essentials.

It should not be neccessary to do so (unless you decide to uninstall Linchpin Theme before you install Linchpin Essentials, in this case: please create a backup of your theme first).

To do so, navigate to Confluence administration → Linchpin → Theme → Export. To import this file again, navigate to Confluence administration → Linchpin → Theme → Import.

Info

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.

Buy and 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.

Please note

Please note that you will require a valide license for the Linchpin Essentials app. The Theme/User Profiles license is not carried over.

No additional costs will be inquired. The license for Linchpin Essentials costs the same as a Linchpin Theme or a Linchpin User Profiles license.

Quality assurance

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

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

  • Collapsible Admin Menu
  • Linchpin Communicator
  • Linchpin Essentials
  • Linchpin Suite - API
  • Linchpin Theme
  • Linchpin Theme - Navigation Menus
  • Linchpin Theme - Sidebar
  • Linchpin Theme - Space Directory
  • Linchpin Usage Tracking
  • Linchpin User Profiles
  • Linchpin User Profiles - Content Responsibility

The following apps remain in the system from the previous Linchpin Theme-only or Linchpin User Profiles-only installation and should be uninstalled (or at least deactivated) to prevent side effects:

  • Linchpin Iconfront
    • This app is obsolet.
  • Linchpin Theme (Custom Landing Spaces)
    • This app is no longer part of the Linchpin Theme app; it is now included in the Linchpin Intranet Suite bundle.
  • Linchpin Theme - Confluence Default Theme
    • This app is now implemented as a module of the Linchpin Theme app and no longer a standalone app.
  • Linchpin Theme - Login
    • This app is also now implemented as a module of the Linchpin Theme app and no longer a standalone app.

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: https://seibert.biz/help.


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

Issue

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


Prevention

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

Issue

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


Reason

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 in your system.


Solution

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!

Issue

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


Reason

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.



Solution

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.

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.

Tip

You can export a theming file with the configuration of your Linchpin Theme app before you install Linchpin Essentials.

It should not be neccessary to do so (unless you decide to uninstall Linchpin Theme before you install Linchpin Essentials, in this case please create a backup of your Theme first).

To do so, navigate to Confluence administration → Linchpin → Theme → Export. To import this file again, navigate to Confluence administration → Linchpin → Theme → Import.

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.

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.

Issue

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.



Solution

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

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

Issue

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.


Workaround

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.


Solution

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.







☁️ Looking for a Cloud-based Intranet?

Check out Mantra, your go-to alternative to Linchpin in the Atlassian Cloud!

Mantra is your a comprehensive solution for connecting teams, making collaboration a breeze, and keeping your company's internal communication strong and streamlined - all in the cloud.

Test the intranet for Confluence Cloud now for free: 


Discover Mantra


Link to this page: https://seibert.biz/linchpinessentialsmigration


This page was last edited on 11/13/2024.