How to upgrade Telligent Community

Upgrade path matrix

Telligent periodically makes new releases available to users to enhance the Telligent platform and application functionality. To upgrade an existing installation you will need to upgrade the site's database as well as its Web files. Therefore the instructions have been divided into these areas where action is required. Please note that it is highly recommended to perform the upgrade in a test environment first before upgrading a live site.

If you have a pre-existing Community Server (CS) or Telligent Community installation, you can complete the following processes to upgrade to Telligent Community 6.x.

Upgrade from 6.0 to 6.1 procedure

Notes for upgrading from 6.0 to 6.1

Unblock the zip package by right-clicking it and navigating to Properties. If there is an Unblock button at the bottom of the Properties window, click it to unblock the zip. If there is no Unblock button, the zip is already unblocked.

If you want to upgrade from Telligent Event Calendar 1.7 to Telligent Event Calendar 20 (both of which are compatible with 6.0 and 6.1), you can simply overlay the files from the 2.0 install over your 1.7 site files and then run the 2.0 SQL script.

Updating files for the Telligent Community website

1. Back up your database instance folders.
2. Run the update.sql script against your database to apply hotfix updates.
3. Copy the contents of your current Web folder to a backup directory (such as c:\OldWeb).
4. Manually copy the contents of the package Web folder into your existing site's Web folder (such as c:\inetpub\Web), overwriting any existing files. While doing this you should copy the entire package /bin folder over your existing Web folder's /bin folder (such as c:\inetpub\Web\bin).
5. Pay special attention to all of the *.config files and any files in the \Languages folder (ex. email templates) that might be included in the hotfix package. You may need to copy or merge one or more of the existing files, especially if you made customizations, from the Web folder you backed up to the new Web folder contents to enable connection.
6. Make sure the NETWORK SERVICES (or ASPNET) user has "Read" rights on the site's \Web folder and "Modify" rights on the \Web\Filestorage folder.

Updating files for the the Telligent Evolution Job Scheduler

1. Stop the service.
2. Copy the contents of your current Job Scheduler folder to a backup directory (such as c:\Program Files\Telligent\Old Job Scheduler).
3. Manually copy the files under the Web /bin folder into your Job Scheduler folder. Do not copy the \bin folder, just the files inside of it. Overwrite any files.
4. Manually copy the contents from the following hotfix folders to your existing Job Scheduler folder, overwriting any existing files:
   
   Web/Themes/
   Web/Languages/
   Web/Modules/
   
   If you do not see some of the folders listed above in the package you can skip copying the missing folder(s). If you have already upgraded your website, you can copy the folders above from your website to the Job Scheduler directory since the specified folders on the website already contain the hotfix changes.
5. Again, pay special attention to all of the *.config files and any files in the \Languages folder (ex. email templates) that might be included in the hotfix package. You may need to copy or merge one or more pre-existing files, especially if you made customizations, from the Web folder you backed up to the new Web folder contents to enable connection.
6. Replace the tasks.config file in your Job Scheduler folder with the tasks.config file in the [hotfix package]\Tasks folder. If you have made any customizations to this file you will need to merge your changes. If the tasks.config file does not exist in the \Tasks folder, skip this step.
7. Restart the service.

Instructions for updating Mail Gateway (only if installed and the folder is present in the package)

1. Stop the service.
2. Copy the contents of the Mail Gateway folder to a backup directory (such as c:\Program Files\Old Mail Gateway).
3. Manually copy the contents of the Mail Gateway hotfix folder to your existing Mail Gateway folder, overwriting any existing files.
4. If you made any changes to the Telligent.Mail.Gateway.exe.config file, migrate them over from your backed up config file.
5. Restart the service.

Upgrade from 5.x to Telligent Community 6.x procedure

Notes for upgrading from 5.x to 6.x

Licensing

• If you are planning to upgrade from Telligent Community 5.5 or 5.6 to Telligent Community 6.x, do not proceed until you have secured your licenses from support. Telligent Community 6.x removes licenses that will not work with the new release.
• If you upgrading from 5.0, 5.0 SP1, or 5.5 to 6.x,you need to validate the number of servers. This feature was enacted in release 5.6.

.NET

• .NET framework version 4.0 is required for Telligent Community 6.x.
• If you are running Windows Server 2008 without SP2, you should install KB958854 to resolve some issues with .NET 4.0.  Windows Server 2008 SP2 and Windows Server 2008 R2 are unaffected by this issue.

Customized pages

• When you upgrade, only the default version of a page is updated. If you have customized a page on your site, this page must be reverted or updated manually to reproduce the added or changed widget and layout functionalities.

Theme customizations

• Additional steps should be taken to ensure that theme changes made in Telligent Community are applied correctly when upgrading from Telligent Community 5.0/5.5. Changes were made in Telligent Community 6.x to store factory defaults and configured defaults together to enable easier upgrades; however, the existing configured defaults will not be automatically adjusted as they have been in previous upgrades. To accomplish this, you must open a special upgrade page.

• To ensure that an upgraded site looks and behaves as desired, a review should be performed after the upgrade. The review required depends on whether or not the site's theme has been heavily customized.

When upgrading from release 5.0 or later, default pages are not deleted or reverted to factory defaults. This requires either (a) reverting all theme pages via the Revert button in the Site Administration Control Panel or (b) manual editing of every page to ensure it looks satisfactory.

• Upgrading a heavily customized site - A heavily customized site should be considered as one where extensive changes have been made to the layout of individual pages. For such sites, a review of each page in the theme may be necessary to ensure that changes made to the factory default styles and layouts are rendered as desired.

• Upgrading a lightly customized site - A lightly customized site should be considered one that included only minor changes to the factory default page layouts. For such sites, it may be beneficial to revert all pages back to the current factory defaults when upgrading Telligent Community 6.x. After you do this, the site will be completely reverted to the original factory defaults.
  
  
• Consult this information on migrating widgets when upgrading from 5.6 to 6.x.

Attachment files

• Two new centralized file stores, Telligent.Evolution.Components.Attachments and Telligent.Evolution.Attachments.Temporary, were created to replace an existing store, CommunityServer.Components.PostAttachments.You will need to utilize a special page in Control Panel to move post attachments from their 5.x location to their 6.x location.

Search

• Search is required for 6.x. If you do not have it, install search.
• Solr 1.4 is required for 6.x. If you do not have it, upgrade to 1.4.
• In versions of Telligent Community before 5.6, the tasks could be run in the Web process or as a separate service. However, most tasks are now executed in their own service.
• Telligent Community 6.x requires that you update your solrconfig.xml and schema.xml files. Make sure you copy these files from the upgrade package into your Solr\Conf folder to overwrite the old versions.

Job Scheduler

• If you are upgrading from 5.6 to 6.x, you will need to remove the earlier version and install Telligent Job Scheduler for 6.x.

• If you change your domain name during an upgrade, you will need to update Default Site URL in Control Panel > Site Administration > Site Configuration > Setup > General Site Settings to allow Job Scheduler to build the URLs required to perform jobs.

Network service user

• If you're using Windows XP for development purposes, your network service user is ASP.NET. If you're using Windows Server 2003, your network service user is NETWORK SERVICE. If you're using Windows Server 2008, your user is IIS APPPOOL\<application pool you create>.

Member Points System (MPS)

• The Rater Factor in the MPS factor values tab has changed regarding how points are awarded for assigning star values to other posts. As a result, some people who accumulated a high rating on the basis of how they rated other posters may receive lowered ratings after the upgrade. You can either leave the value points as they stand, or you can recalculate them. (Although we don’t recommend recalculating for large databases, because it will take a long time to run.)

Telligent Analytics Web Analytics (Extended Analytics)

• If you are running Telligent Analytics, you will need to stop the task service or the analytics runner. (To disable the task service, navigate to Control Panel > Administrative Tools > Services > and locate the task service and disable it. If you are using the analytics runner, stop the application manually [as you might a Windows program] or, if you have it set up as a scheduled service, disable it.)
• If you are also installing a mobile site as a child site of this community, you need to add a remove statement to the mobile site's web.config file for Web Analytics since it is already being inherited from the community site.

Validate the servers

Validate the number of servers configured to access your existing Telligent Community database. To do this:

1. Navigate to Control Panel Dashboard > System Administration > Site Administration > Manage Licenses.
2. View the information in the Number of Servers area.
   
   
   

   If there is a discrepancy between the number of licensed servers versus those currently in use, you will receive licensing error messages and will have some trouble upgrading Telligent Community. In the event of a difference, you can check to see whether you have old servers registered in the Manage Licenses page. Then you can contact Support to resolve the issue.

Get the package and unzip it

1. Obtain the installation package from Customer Care.

2. If you are opening the package using Internet Explorer, you may need to unblock the package:

   1. Open the folder to which you downloaded the package.

   2. Right-click the package and select Properties.

   3. At the very bottom of the screen that window, you may see an Unblock button. If you see this, click Unblock.

   4. Click OK.

3. Extract the contents of the package to a temporary location on your hard drive.

4. If you have customizations to your site's files, read the next section (Update theme customizations). Otherwise, progress to upgrading website files.

Upgrade website files

Ensure you back up the entire site to another folder beforehand. If you are upgrading the same website's files and not creating a new site, perform most of these instructions on the original site's Web folder.

1. Back up your website's files (e.g., c:\<local directory, such as inetpub>\<webfolder>copied to c:\>inetpub\OriginalWeb).

2. Copy the upgrade Web folder into a new folder.

3. Copy over the new web/filestorage/ folder over the old one.
4. Merge the old communityserver_override.config file, if it exists, into the communityserver_override.config on the new site or simply copy it over to the new site's directory.

5. Install an application pool if you have not already done so.

6. Change your ASP.NET version from below version 2 to 4 if you have not already done so.

7. Grant your service userread permission on c:\<local directory, such as inetpub>\<web folder>.

8. Grant the service user modify permission on C:\<local directory, such as inetpub>\<web folder>\filestorage .

9. Update the connectionStrings.config file in the <web folder> to point to the database the site is using (if you are not upgrading the same database). Reference the connectionStrings.config file from the site's backup if necessary.

10. Upgrading your Telligent Analytics "Extended Analytics" module: If you currently have the Extended Analytics module, please follow all of the steps below to ensure there is no disruption in the collection of Web traffic data:
    1. Delete the CommunityServer.ExtendedAnalytics.dll file from your Telligent Community site \bin directory.
    2. In your Telligent Community site's web.config file, locate the <modules> section in <system.webServer>. Uncomment the JavascriptAnalyticsHttpModule line.
    3. Locate the <handlers> section, and uncomment the analytics and analyticsUrls handlers.
    4. Optional: If your Telligent Community site is running on a Web farm, ensure that steps b and c happen on all Web servers.

11. Update the folder path for the site's entry in IIS so that it points to the new folder (if you are not upgrading the same folder), for example C:\<local directory, such as inetpub>\<web folder>. If you are using IIS6 instead of IIS7, refer to the Microsoft IIS 6 documentation for your specific platform.

Don't test the website URL until after you upgrade the database. You may run into Windows Authentication issues if you do so prematurely, and some sprocs may be missing until that point.

Upgrade database

1. Back up your database.

2. Inside the extracted contents of the upgrade package, open the SqlScripts folder.

3. There are several SQL files in the SqlScripts folder. Use SQL Server Management Studio to open the cs_UpdateSchemaAndProcedures.sql script file.

4. Execute the file against the database that your site is referencing. Ensure that the query returns a successful result. Don't run any of the other queries unless instructed to do so by Support.

Update for Windows Authentication

If you areusing Windows Authentication with Telligent Community, update the communityserver_override.config file.

Update the connection string and test it

Test the upgraded site by visiting the site's URL in a browser. If the site doesn't work, double-check the service user ID, its assigned rights, and the connectionstrings.config file.

Upgrading theme files from 5.x to 6.x

When you upgrade from 5.x to 6.x, run the following page as an administrator. (Do this after the database and Web files have been updated.)

/controlpanel/utility/upgradethemefilesto6.aspx

This will physically move theme configuration-associated files from their 5.x location to their 6.x location to ensure that additional CSS, JavaScript, and supplementary files are available to customized themes.

If files (css, images, etc.) are uploaded to a site, group, or blog theme via theme configuration in the Control Panel, those theme files were previously stored in a specific directory in CFS.  In 6.x, that location is slightly different (as theme names changed to GUIDs in 6.x), so this script moves those files from where they would have been to the new location. This tool does not create new themes or migrate existing themes from 5.x to 6.x. 

Upgrade filestores for attachments

1. Navigate to http://yoursite/ControlPanel/Utility/UpgradeAttachments.aspx.
2. Click Start Migration.
3. After running the attachment upgrade, recycle the app pool and restart the application.

Install your license

Install your Telligent Community 6.x license at this point and test it by updating your connectionstrings.config file and trying to navigate to the site. If you do not install your license, you could get a yellow screen.

Update search

Perform the following steps on the server that is running Solr:

The following instructions assume the Solr home ([solr home]) directory is in the default installation location, e.g., c:\Program Files\Apache Software Foundation\Tomcat 6.0\solr. If you have changed the home directory for Solr, adjust the instructions accordingly.

If you've made any customizations to the schema.xml file or solrconfig.xml file, you should use a merge tool such as WinMerge and merge the custom changes to the updated files.

1. Navigate to the [solr home] directory and create a folder called conf_backup.
2. Copy schema.xml and solrconfig.xml from [solrhome]/conf to the conf_backup folder.
3. Copy schema.xml and solrconfig.xml from the Search/solr/conf directory in the Telligent Community package to the [solr home] directory.
4. Restart the Tomcat service.
5. Perform a full reindex.

Update (or install) Mail Gateway

If using Mail Gateway with Telligent Community 5.x, you need to take some additional steps during the 6.x upgrade to also upgrade Mail Gateway (if you're using it; if you're not, skip this section).

Upgrade Mail Gateway

1. Back up the mailgateway.config and Telligent.MailGateway.exe.config files in the current installation of Mail Gateway. By default, these files are located in c:\Program Files (x86)\Telligent\Mail Gateway\. If you installed Mail Gateway in another directory, the files will be located at that path.
2. Uninstall the previous Mail Gateway service.
3. Install the Mail Gateway.
4. Update the <Sites> node in mailgateway.config with the <Sites> node from the file backed up in Step 1.
5. Apply any customizations made in the backed up Telligent.MailGateway.exe.config to the newly installed file.

Install Mail Gateway for the first time

1. Install the Mail Gateway.
2. Follow the steps to configure Mail Gateway.

Job Scheduler

In Telligent Community 6.x, most tasks should be executed in their own service.

All Telligent Community 6.x sites need to install the Telligent Job Scheduler. To learn more about working with custom tasks in the Job Scheduler, see the article in the Developer documentation.

Install the Job Scheduler for Telligent Evolution 6.x/Telligent Community 6.x

Note that if you have Job Scheduler for Community 5.x, it needs to be uninstalled, and then you need to install the Job Scheduler Telligent Evolution 6.x/Telligent Community 6.x version.

In Telligent Evolution release 6.x/Telligent Community 6.x, the Job Scheduler is installed with a .bat file rather than an msi. The instructions for upgrade are located in a README.txt file, and are reproduced here.

1. Copy (back up) your previous Job Scheduler folder installation to another location. (The default location is C:\Program Files (x86)\Telligent\Job Scheduler.)
2. Obtain the package from Customer Care and right-click it to expose the Properties window.
3. If an Unblock button is displayed, click the button. If you do not do so, Job Scheduler will not run properly.
4. Uninstall Telligent Job Scheduler from the Control Panel.
5. Delete all files in the existing Job Scheduler folder.
6. Copy all files from the installation folder into the Job Scheduler folder.
7. Run install.bat as administrator (that is, right-click the file and select Run as administrator) to install the Job Scheduler service.
8. Compare your backed up files with newly created Job Scheduler using a comparison tool such as WinMerge, and merge any files as necessary. These files might include language resource files or config files.
9. Determine what changes you made to previous email templates and apply them to the new templates. They are different enough that they can't be merged. (The names of many templates have changed, as detailed here.)
10. Update your connectionstrings.config (or copy it from your backup location) and update your communityserver_override.config files (or copy it from your backup location).
11. If you are using Windows Server 2008, you need to add the NETWORK SERVICE user to the web and filestorage folders with the same permissions and create a user for it in the server and database. (It may already exist in the server.)
12. Open services (services.msc at the command prompt) and start the Telligent Job Scheduler service. (The service should start automatically after the initial run.)

If you still have any problems after following the troubleshooting suggestions provided in the documentation, please contact Support.