Before you upgrade, please make sure you have the pre-requisites covered:
- You are already on ThoughtFarmer version 8.7 and are upgrading to version 9
- If you are between version 8.7.0.XX to 9.1.0.XX, install the latest .NET Core 3.1 on your web server. Please select the "ASP.Net Windows hosting bundle" option.
- Backup your database
- For version 18.104.22.168+, the cards below will break. Your cards are listed in the Admin Panel > Cards. If you have any of these cards, please contact us before your upgrade and we can provide an updated version:
- Calendar Feed
- Locations Directory
- RTE Content Container
- Import ical
- TFStats (Reporting Card)
- Required Reading
Download the upgrade files
Download the latest version files onto the web server. The files are in the 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.
Upgrading 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
- Click on your ThoughtFarmer instance and click "Upgrade selected instance"
- Check off to confirm you've backed up your database and click "Start Upgrade"
- Database Settings: These values should be pre-populated. Verify this information. Click Next.
- Double check the settings on this screen are correct:
- If you're using https, check off "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 your "API Token" field is correct. The API token is in Admin Panel > API Tokens, under "Service API token". Click Next.
- 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.
Upgrading 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
- Click on your ThoughtFarmer Windows service and click "Upgrade selected instance".
- Check off "Employee Directory Connector". If your AD Windows service is on the same server as your ThoughtFarmer site, do not check "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 popup warning saying there's 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 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 Admin Panel > API Tokens. Copy the token under "Service API token".
- Active Directory ID: N/A
- SSO ID: N/A
- Service UID:
- go to Admin Panel > Employee Directory Connector > [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 (ex: your name) and make sure it returns results
- Click around your site (ex: your top level navigation) to check pages are loading in a timely manner.
Test user sync (if integrating with AD or SAML)
- Go to Admin Panel > Employee Directory Connector > [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.
This is only for if you run into 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 were making changes to it, and you decide to rollback, those changes will be lost.
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 one 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".
Take the database backup that you took before the upgrade (mentioned in pre-requisites), and restore it to your current upgraded database.