How to upgrade Telligent Community

Current Revision posted to Telligent Community 6 by Jenny Jarrard on 9/7/2012 9:15:53 AM

Upgrade path matrix

If you have	And want to upgrade to	The upgrade path is
CS2007	6.0	CS2007->CS2008; CS2008 -> 6.0
CS2007	6.1	CS2007->CS2008; CS2008->6.1
CS2008	6.0	CS2008->6.0
CS2008	6.1	CS2008->6.1
5.x	6.0	5.x ->6.0
5.x	6.1	5.x->6.1
6.0	6.1	6.0->6.1

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

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

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.

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>\<web folder>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 user read 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 are using 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 .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.)

Upgrade from Community Server procedure

This article describes how to upgrade from previous versions of Community Server to  Telligent Community 6.x.

• Key changes affecting the upgrade
• Upgrade the database
• Upgrade to new site with new IIS application
• Upgrade to new site with existing IIS application

Upgrade notes for Community Server

The key changes that will most affect your community when upgrading are:

• Upgrade only from Community Server 2008 or later
  If you're running your community on anything prior to the version from 2008, you must first upgrade your site to Community Server. If you have Community Server, you can upgrade directly to Telligent Community 6.x.

  We have made significant changes and improvements in moving from your Community Server site to Telligent Community, including the introduction of group hierarchies, multiple blogs, forum, galleries, and wikis per group, complete redesign of permissions and a completely widgetized user interface.

• All installations require a valid license file
  You must obtain a valid license to run Telligent Community anywhere other than locally with limitations on number of users, groups, and applications.

• Only the Fiji theme is supported
  With completely widgetized themes, we currently only support the Fiji theme for Telligent Community installations. Dynamic theming means that all areas of a page are widgets or discrete components that can be removed, moved (via drag and drop), renamed, and/or configured specifically for your community. You can add any number of widgets to each page to customize the experience for your community members.

• Categories translated to joinless groups
  Telligent Community uses an unlimited group/subgroup hierarchy with any number of applications (forums, blogs, wikis, file galleries) within each group and new joinless groups that do not require membership but provide structure for a community. All categories in your CS2008 community - whether for groups, blogs, forums, media galleries, or wikis - are translated into joinless groups when you upgrade to Telligent Community. All groups or applications within these categories are now part of these new joinless groups. Be sure to review our full list of features to become more familiar with all of Telligent Community's capabilities.

Prepare to upgrade CS

You have two ways you can upgrade to Telligent Community, both of which work well. Remember that if you encounter errors during the upgrade process and need to attempt the process again, do so against a new backup of the database and a new set of the Telligent Community installation package.

•  Start with new. Create a new IIS application that includes the new Telligent Community components and copy over only the filestorage folder from your CS site.
• Start with old. Overwrite the existing CS IIS application's Web directory files and remove components that are no longer necessary for Telligent Community .

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 opens (just above the OK, Cancel and Apply buttons) you may see an Unblock button. If you see this it, click Unblock.

   4. Click OK.

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

4. If you have customizations to your site's files, refer to Updated customized site files.

Upgrade database

You should use the following steps to upgrade your database whether you are creating a clean database or upgrading an existing one.

1. Obtain a copy of the needed upgrade from Support.

2. Create a backup of your database. We've done our best to ensure a smooth upgrade process, but there are times when unforeseen issues (especially data issues) can cause problems. The safest path to a smooth upgrade is to have a backup of your database ready in case you need to roll back changes.

3. Connect to your database server.

4. Upgrade instructions for Community Server:
   
   
   1. Open the SqlScripts\Reset_SearchIndexes.sql file and execute it on your CS database.
   2. Run the following script on your CS database to keep subscriptions intact and ensure group members will continue getting email notifications:
      
      

      delete from cs_TrackedSections
        where UserID in
          (select gm.UserID from cs_Sections S left join cs_GroupMembers gm
      on gm.GroupID = s.GroupID where s.SectionID =
      cs_TrackedSections.SectionID)
      
      insert into cs_TrackedSections (UserID, SubscriptionType, DateCreated, SettingsID, SectionID)
        select gm.UserID, 3 as SubscriptionType, getdate() as DateCreated, s.SettingsID, S.SectionID
          from cs_GroupMembers gm
          left join cs_Sections s on s.GroupID = gm.GroupID and s.ApplicationType = 0

   Open the standard upgrade script file, SqlScripts\cs_UpdatesSchemaAndProcedures.sql, and execute it on your CS database.

Upgrade website files

Upgrade site with a new IIS application

To upgrade your CS site to Telligent Community with a new IIS application:

1. Unzip the Telligent Community package into a temporary location on your Web server. Notice that it contains these folders: Web, SqlScripts, and Solr (for search).

2. To configure the Web server:

   1. In IIS:

      1. Create a new application named telligent_community and indicate its physical path as the Web folder you unpackaged.

      2. Grant the NETWORK SERVICE user Read & execute privileges.

   2. In the file system:

      1. Copy all files from your Telligent Community Web\filestorage folder into the new Web\filestorage folder for the telligent_community application.

      2. Copy the connectionstrings.config file from your old installation, or edit the freshly installed one with your website's database information.

      3. Grant the NETWORK SERVICE user Read permission on the Web folder.

      4. Grant the NETWORK SERVICE user Modify permission on the Web\filestorage folder.

3. Verify that your community works as expected by navigating to http://localhost/telligent_community(or whatever name you used in step 2.a.A above). If the site doesn't work, double-check the network user ID, the rights it's assigned to the folders, and the connectionstrings.config folder.

4. Apply your license to use Telligent Community for more than just local verification.

5. Install any additional components that are important for your community:

   1. Telligent Community Mail Gateway (optional for integration with email).

Upgrade site with an existing IIS application

To upgrade your CS site to Telligent Community using your existing IIS application:

1. Create a backup of all files in your CS \Web directory to ensure your ability to roll back changes appropriately.

2. Unzip the Telligent Community package into a temporary location. Notice that it contains these folders: Web, SqlScripts, and Solr (for search).

3. To configure the Web server:

   1. Save the connectionstring.config file from your existing CS Web folder.

   2. In IIS, make sure the NETWORK SERVICE user has Read & execute privileges.

   3. In the file system:

      1. Copy all contents of the Web folder from the temporary location and paste them into the Web folder of the CS site to overwrite all files.
      2. Copy the saved \filestorage folder back to your Web directory.
      3. Move the saved connectionstring.config file back into your Web folder so that the connection to your database is preserved.
      4. Remove all folders (such as the Hawaii theme) from Web\Themes EXCEPT for Blogs, Fiji, Generic, Groups. This is required since Telligent Community only supports the Fiji theme.
      5. Remove all folders (such as the Hawaii theme) from Web\Themes\blogs EXCEPT for anything named fiji or generic.
      6. Remove any logging.config, communityserver_override.config or siteurls_override.config files you may have in the Web folder.
      7. Make sure the NETWORK SERVICE user Read permission on the Web folder.
      8. Make sure the NETWORK SERVICE user Modify permission on the Web\filestorage folder.

4. Verify that your community works as expected by navigating to http://localhost/cs (using the name of your IIS application from step 3.a.A for your new Telligent Community site). If the site doesn't work, double-check the network user ID, the rights it has assigned to the folders, and the connectionstrings.config folder.

5. Apply your license to use Telligent Community for more than just local verification.

6. Install any additional components that are important for your community:

   1. Telligent Community Mail Gateway (optional for integration with email).

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