Upgrade ThoughtFarmer (self-hosted)
Pre-requisites
Before you upgrade, follow these pre-requisites:
- You are already on ThoughtFarmer version 9.0 or higher.
- If upgrading to version 10 from version 9.x, install NET Framework 4.8 runtime (requires a server reboot).
- Install the latest .NET Core 6.0 on your web server. Select the ASP.Net Windows hosting bundle option.
- Backup your database
- Backup your web server, if possible.
e.g. Take a snapshot if the web server is running on a VM
Download the upgrade files
Download the latest version files onto the web server. The files are in the version folder at the bottom of this ThoughtFarmer Community page. You'll need the TFManager executable file. If you're integrating with on-premise Active Directory, download the EDCManager executable too.
Upgrade your site
On the web server, run the TFManager executable and follow these steps:
- Run the TFManager executable as an Administrator on the web server. Values in the TFManager installer will be pre-populated from the below registry keys under:
Computer\HKEY_LOCAL_MACHINE\SOFTWARE\ThoughtFarmer\
- Click on your ThoughtFarmer instance and click Upgrade selected instance.
- Check the box to confirm you have backed up your database and click Start Upgrade.
- Database Settings: These values should be pre-populated. Verify this information. Click Next.
- Web server settings: Check that the settings on this screen are correct:
- If you're using https, check the box Enable HTTPS Redirect and ensure https is in the API URL field.
- For the API URL, use your actual site URL instead of localhost if possible. Make sure your site URL is accessible from the web server. Include http:// or https://
- Check that the API Token field is correct. The API token is in the ThoughtFarmer Admin panel > Integrations section > API Tokens page, under Service API token. Click Next.
*The API Token field is concealed in more recent versions of ThoughtFarmer. If so, it must be retrieved directly from the database via these steps:- Open SQL Server Management Studio (SSMS) on the database server hosting your ThoughtFarmer database
- Run the following query against the ThoughtFarmer database to view the API Token. Note this down.
SELECT Ticket FROM Token WHERE Feature = 1;
- Skip the Update Search+ screen by clicking Next.
- Click Next again to start the upgrade. Wait for it complete successfully.
- If you are not integrating with on-premise Active Directory, skip to the Post upgrade checks section below.
Download the ElasticSearch requirements
Follow the instructions for upgrading ElasticSearch on this ThoughtFarmer Community page.
Upgrade your AD sync Windows service (if integrating with AD)
The ThoughtFarmer EDC Service (Look for this under Services.msc) is used for the AD sync and is located on your web server. Follow these steps to upgrade it:
- Run the EDCManager executable as an Administrator on the web server. Values in the EDCManager installer will be pre-populated from the below registry key:
Computer\HKEY_LOCAL_MACHINE\SOFTWARE\ThoughtFarmerAuth
- Click on your ThoughtFarmer Windows service and click Upgrade selected instance.
- Check the box Employee Directory Connector. If your AD Windows service is on the same server as your ThoughtFarmer site, do not check the box Single-Sign On Site. This option is for users who have their ThoughtFarmer site and Windows service on separate servers. Click Next.
- The next screen shows your IIS site settings, which only applies if you checked the single-sign on site option above. No changes needed here. Click Next. You'll get a pop-up warning saying there is a conflict and a folder already exists in that location. This is fine, click OK.
- The next screen shows the folder path of your ThoughtFarmer EDC Service. The correct values should be pre-populated. Click Next.
- Web server settings: This provides the information that the EDC service uses to connect to the main application. The correct values should be pre-populated. You can verify using values from your intranet site. See below on where to find them.
- Main site URL: Your ThoughtFarmer URL (don't use localhost unless your site URL is not accessible from the web server). Include http:// or https://
- API Token: Found in the ThoughtFarmer Admin panel > Integrations section > API Tokens page. Copy the token under Service API token.
- Active Directory ID: N/A
- SSO ID: N/A
- Service UID:
- Go to the ThoughtFarmer Admin panel > Users & security section > Employee Directory Connector page > [name of your external user store].
- The Service UID is the Id in the Basic Information tab.
- After verifying the above values, click Next and wait for the upgrade to complete successfully.
Post-upgrade checks
Do these quick tests after the upgrade to make sure the main components of your site are working.
Test search is working
- Click on the Search button near the top right, next to your profile image.
- Search for something that you know exists (e.g. your name) and make sure it returns results.

Test performance
- Click around your site (e.g. the top level navigation) to check that pages are loading in a timely manner.
Test user sync (if integrating with AD or SAML)
- Go to the ThoughtFarmer Admin panel > Users & security section > Employee Directory Connector page > [name of your external user store].
- Click the Synchronization Settings tab.
- Click Validate credentials and refresh the page until you see it validate successfully.
- Check off some sync tasks included in your daily schedule sync and click Synchronize now.
- Click the Synchronization Logs tab, and check if the sync completed successfully (you may need to flip back and forth between tabs to see the sync status change). The duration of the previous syncs are indicators of approximately how long the sync should run for.
Rollback plan
This is only for if there is a critical issue after the upgrade and you need to rollback to your previous version. The rollback would need to be done on the web application and database. If your site is up and running after the upgrade, and people make changes to it, and you decide to rollback, those changes will be lost.
Web Application
If you took a snapshot of your web server before the upgrade, then you can revert back to the snapshot. If not, then please follow these steps:
- Open up IIS.
- Click on your site.
- On the right, click Basic Settings.
- Change the version number under Physical path to the previous version you had before the upgrade. If you don't know what that number is, go to the physical path location. Go up 2 folders and the second most recent version folder is the one you had before the upgrade. Make note of that number and go back to the physical path in IIS. Replace the current number with that number.
- Click the arrow next to your site in IIS to expand it. For each of the sub-applications, formsapi and usermanagementapi, click Basic Settings on the right.
- Repeat step 4 for formsapi and usermanagementapi.
Database
Take the database backup that you took before the upgrade (mentioned in pre-requisites), and restore it to your current upgraded database.
Comments
0 comments
Please sign in to leave a comment.