TMCore07 Installation Guide

Introduction

This document describes how to install and configure TMCore, including the Topic Map Editor, Topic Map Web Service and NPCL Web Service web applications. Before beginning installation ensure that the prerequisites mentioned are installed and working.

Note

If you are upgrading from a previous version of TMCore, please refer to the section called “Upgrading From A Previous Release” before performing the installation tasks detailed in this document.

Warning

IMPORTANT NOTICE FOR UPGRADERS!

If you are upgrading from a release prior to TMCore07 SP2, please note that starting from the SP2 release of TMCore07, the pre-requisite version of the .NET Framework has been advanced to .NET version 2.0. This has two important effects.

ASP.NET 2.0 is now used for all TMCore web applications. Please ensure that you install this version of the framework and register it with IIS (using the aspnet_regiis.exe command if necessary).
All applications originally compiled targetting .NET 1.1 MUST be recompiled against the new TMCore07 SP3 assemblies and must target the .NET 2.0 platform. .NET 1.1 applications are no longer supported.
Applications that were compiled to target .NET 2.0 and use the old TMCore assemblies will continue to run without any modification. The installer will add policy files to the GAC to ensure that references to old versions of the TMCore assemblies are automatically redirected to the new assemblies.

Prerequisites

Before installing the TMCore there are some third party components that need to be present. The following sections describe each of these in turn.

Windows Server 2003 or later, Windows XP Professional or later

For installation of Windows operating systems please see the relevant documentation from Microsoft. Developing client applications that access the database remotely or via the topic map web service can be accomplished on potentially many different operating system configurations. Below we describe the requirements to install the core engine, the SQL database and set up the web application and web service. The web application and web service require Microsoft IIS and ASP.NET to be installed.

Note

On Windows XP Professional, support for ASP.NET is installed by installing the .NET Framework as described below. On Windows Server 2003 or later and Vista or later ASP.NET support is installed through the Add/Remove Windows Components option in the control panel.

SQL Server

TMCore depends upon SQL Server for its back-end persistence. SQL Server 2000, SQL Server 2005, SQL Server 2008 and SQL Server 2012 are supported.

IIS

In order to access the TMCore engine via a web service or the navigator application IIS is required. IIS 5.0, IIS 6.0 and IIS 7.0 are all supported. For installation of IIS please see the relevant documentation from Microsoft.

.NET Framework 2.0

Installation on Systems running IIS 5 or IIS 6

TMCore makes use of the Microsoft .NET Framework version 2.0. Prior to installation, you MUST download and install the .NET Framework version 2.0 from http://www.microsoft.com/downloads/browse.aspx?displaylang=en&productID=DE7BB609-3FD0-4B0F-865D-5ED2463AD5D0

If IIS is installed after the .NET Framework, a script needs to be run to integrate the .NET Framework with IIS. The utility is called aspnet_regiis.exe and can be found in %WindowsDir%\Microsoft.NET\Framework\v2.0.50727\. Typically it is called with the '-i' parameter.

Note

On x64 platforms please ensure that you register the 64-bit version of the .NET Framework with IIS. This can be found in %WindowsDir%\Microsoft.NET\Framework64\v2.0.60727\

After registering ASP.NET with IIS 6, you may need to also enable the use of ASP.NET v2.0 as a web service extension with IIS. To do this open the IIS Management console (Control Panel / Administrative Tools / Internet Information Services), expand the node for the machine running IIS and click on Web Services Extensions. Ensure that the extension ASP.NET v2.0.50727 is present - if it is not you may need to restart IIS and/or re-run the aspnet_regiis.exe command. If the Status for this extension is set to "Prohibited", select it and click the "Allow" button to enable ASP.NET processing. You should not need to restart IIS after this.

Installation on Systems Running IIS 7

On systems running IIS 7, ASP.NET 2.0 support should be installed through the Add/Remove Windows Components interface. After ensuring the ASP.NET 2.0 support is installed you should only need to ensure that the application pool used for TMCore Web Services is running using ASP.NET version 2.0.50727.

Installing and Configuring TMCore

There are just a few steps in configuring TMCore for use.

Running the TMCore Installer

The TMCore software and documentation is installed by running the installer program. The installer will guide you through the process of selecting the components to be installed. The installer provides the following installation options:

Client and Client Applications - installs the Topic Map Web Services client library and command line applications.
Database Scripts - installs the SQL scripts required to initialise a database for TMCore.
Web Services - contains separate components for each of the web applications that are shipped with TMCore.
- Topic Map Web Service - installs the ASP.NET components for the Topic Map Web Service.
- NPCL Web Service - installs the ASP.NET components for the NPCL Web Service.
- Topic Map Editor - installs the ASP.NET components for the Topic Map Editor web application.

Creating the TMCore Database

This step needs to be performed only if you are installing the database server to be used by TMCore.

Create a new database in SQL Server called 'topicmap'

Using SQL Server Query Analyzer, SQL Server Management Studio or another SQL tool and, ensuring that the context is the new 'topicmap' database, run the T-SQL script tmcore.sql located in install_folder\scripts. This script will create all the tables, indexes and views required.

Note

It is possible to choose a database name other than 'topicmap' for the database that will store the TMCore data, however if you do choose a different name, some additional configuration will be required for the web applications and web services.

The database creation script will also create two new database roles named "tm_reader" and "tm_writer" which are granted sufficient privileges to read from and modify the topic map system respectively. We recommend that you use these roles when granting access to individual accounts to the TMCore database.

If the applications you are running do not need to be able to poll the TMCore system for changes (see the Chapter "TMCore System Utilities" in the Developers' Guide for details), you may also wish to run the T-SQL script install_folder\scripts\disable-changelog.sql to remove the triggers that populate the change log tables for the TMCore system - this may improve throughput on topic map modifications.

Installing the License File

TMCore is protected by a runtime license manager. Before running any of the TMCore applications including the web applications, please ensure that you have placed the license file supplied to you by Networked Planet (tmcore.lic) in the location appropriate to the operating system of your machine:

Windows XP Professional: Documents And Settings\All Users\Application Data\NetworkedPlanet\licenses
Windows 2000: Documents And Settings\All Users.WINNT\Application Data\NetworkedPlanet\licenses
Windows 2003 Server: Documents And Settings\All Users\Application Data\NetworkedPlanet\licenses
Windows Vista or later; Windows Server 2008 or later: ProgramData\NetworkedPlanet\licenses

Note

The Application Data or ProgramData directory may be a hidden directory on your machine. If you cannot see the directory in Windows Explorer, you must enable viewing of hidden files by choosing the menu option Tools > Folder Options, click on the "View" tab and ensure that the option "Hidden files and folders" is set to "Show hidden files and folders". On Vista, this option can be set from the "Organize" drop-down menu by choosing the "Folder and Search Options" menu item.

Registering the Web Applications with IIS

The three web applications that are provided with TMCore are the Topic Map Web Service (found in the directory install_folder/TMService), the NPCL Schema Web Service (in the directory install_folder/NPCLService, and the Topic Map Editor (in the directory install_folder/TMEditor). To use any of these web applications you must register them as web applications on a website under IIS. There are two options for installing these web applications in IIS:

Create virtual directories under the IIS website that point to the web application directories under the TMCore installation location.
Copy the web application directories to a location under the website's root folder.
Copy the web application directories to some other location and use a virtual folder to include the applications within the website hierarchy.

Except for stand-alone development installations we generally recommend one of the latter two arrangements. By making a copy of the web application directory you are assured that future upgrades will not interfere with the running of these applications, however this also means that you will be required to manually manage the upgrading of these web applications.

All three applications are ASP.NET 2.0 web applications and you should follow the normal procedure for installing such applications according to the version of IIS that you are running. This means that you must ensure that each of the web application top-level folders or the virtual directories you created are registered with IIS as an application. The method for doing this varies depending on the version of IIS you are running - please check the IIS documentation for more information.

The following sections provide some additional information regarding the configuration of the web applications.

Configuring the Topic Map Web Service

This configuration step is required only if the Topic Map Web Service application was installed either by selecting the Server setup or by selecting the Custom setup and enabling installation of the Topic Map Web Service feature.

Note

The Topic Map Web Service requires that the database has been configured and a valid license has been installed as described in the sections above.

If the TMCore database is installed on another machine; or if the database is not named 'topicmap', then it is necessary to change the connection parameters to the TMCore engine. The configuration is located in the file named web.config in the root folder of the Topic Map Web Service web application (install_directory/TMService), and is contained in the appSettings section of the configuration as shown below:

<appSettings>
  <add key="networkedplanet.tmcore.dbconnect" 
	  value="Data Source=localhost;Integrated Security=SSPI;Initial Catalog=topicmap" />
	  ...
</appSettings>

Change the value of the 'value' attribute to the correct connection string for accessing the TMCore database you wish to access. The value is a normal ADO.NET connection string. The database server name is specified by the Data Source option and the database name is specified by the Initial Catalog option. It is also possible to alter the authentication method used to connect to the database and the user name and password for the connection. However it is recommended that you make use of Windows security and do not use a configured user name and password in the connection string.

Note

When using Windows security to access the database, you must ensure that the application pool that the tmws application is assigned to is granted read access to the TMCore database.

The Topic Map Web Service is configured to write basic logging information to the directory that contains the application. If you wish this logging to take place, you must grant the ASPNET user write privileges on the directory containing the Topic Map Web Service files.

To test the Topic Map Web Service is running simply enter the service endpoint URL into a browser. The service can be accessed through the tmservice.asmx page that is installed in the root of the Topic Map Web Service directory. If you browse to this page, a web page listing all the available methods will be returned if everything is correctly configured. From this list, click on the method named GetTopicMaps. On the page that is displayed, click the 'Invoke' button. This will call the web service and the results of the call will be displayed in a separate window. If everything is configured correctly and the TMCore database is currently unpopulated the result of the call should be an XML document containing only the element topicmapsystem. If the TMCore database already has some topic maps loaded, then the results should list the names of all the loaded topic maps.

Note

After configuring the connection to the database you may also choose to configure a set of named queries and a query ontology for the Topic Map Web Service. Details on configuring these features can be found in the Web Services Guide document.

Configuring Query Timeouts

You can configure TMWS's timeout when executing SQL queries (via the ExecuteQuery or ExecuteQueries web service methods) by setting networkedplanet.tmcore.tmws.commandtimeout application setting as follows:

<appSettings>
  <!-- Configure a 60 second timeout, overriding the default of 15 seconds -->
  <add key="networkedplanet.tmcore.tmws.commandtimeout" value="60" />
  ...
</appSettings>

This configures a 60 second timeout over the default 15 second timeout for SQL queries to return from TMCore.

Configuring Deadlock Retries

You can configure the number of times that TMCore will retry a ProcessTransaction web service method call that fails due to a deadlock by setting the networkedplanet.tmcore.tmws.deadlockretrycount application setting as follows:

<appSettings>
  <!-- Configure 3 deadlock retries , overriding the default of 0 -->
  <add key="networkedplanet.tmcore.tmws.deadlockretrycount" value="3" />
  ...
</appSettings>

This configures TMWS to retry a deadlock-failed transaction 3 times, overriding the default of no retries.

Configuring the NPCL Web Service

This configuration step is required only if the NPCL Map Web Service application was installed either by selecting the Server setup or by selecting the Custom setup and enabling installation of the NPCL Web Service feature.

Note

The NPCL Web Service requires that the database has been configured and a valid license has been installed as described in the sections above.

If the TMCore database is installed on another machine; or if the database is not named 'topicmap', then it is necessary to change the connection parameters to the TMCore engine. The configuration is located in the file named web.config in the root folder of the Topic Map Web Service web application (install_directory/NPCLService), and is contained in the appSettingssection of the configuration as shown below:

<appSettings>
  <add key="networkedplanet.tmcore.dbconnect" 
       value="Data Source=localhost;Integrated Security=SSPI;Initial Catalog=topicmap" />
  ...
</appSettings>

Note

When using Windows security to access the database, you must ensure that the application pool that the NPCL Web Service application is assigned to is granted read access to the TMCore database.

The NPCL Web Service is configured to write basic logging information to the directory that contains the application. If you wish this logging to take place, you must grant the ASPNET user write privileges on the directory containing the NPCL Web Service files.

To test the NPCL Web Service is running simply enter the service endpoint URL into a browser. The service is accessible through the npclschemaservice.asmx page that is contained in the root directory of the NPCL Web Service. A web page listing all the available methods will be returned if everything is correctly configured. The operations provided by this service require at least one sample topic map to be imported first.

The NPCL Web Service also has some additional configuration options which are described in detail in the Web Services Guide document.

Configuring the Topic Map Editor Web Application

This configuration step is required only if the Topic Map Editor Web Application was installed either by selecting the Server setup or by selecting the Custom setup and enabling installation of the Topic Map Editor feature.

Note

The Topic Map Editor Web Application requires that the database has been configured and a valid license has been installed as described in the sections above.

If the TMCore database is installed on another machine; or if the database is not named 'topicmap', then it is necessary to change the connection parameters to the TMCore engine. The configuration is located in the file named web.config in the root folder of the Topic Map Editor Web Application (install_directory/Topic Map Editor), and is contained in the appSettings section of the configuration as shown below:

<appSettings>
  <add key="networkedplanet.tmcore.dbconnect" 
       value="Data Source=localhost;Integrated Security=SSPI;Initial Catalog=topicmap" />
  ...
</appSettings>

Change the value of the 'value' attribute to the correct connection string for accessing the TMCore database you wish to access. The value is a normal ADO.NET connection string. The database server name is specified by the Data Source option and the database name is specified by the Initial Catalog option. It is also possible to alter the authentication method used to connect to the database and the user name and password for the connection. However it is STRONGLY RECOMMENDED that you make use of Windows security and do not use a configured user name and password in the connection string.

Note

When using Windows security to access the database, you must ensure that the user named ASPNET on the machine running the IIS web server is granted read access to the TMCore database.

The Topic Map Editor Web Application is configured to write basic logging information to the directory that contains the application. If you wish this logging to take place, you must grant the ASPNET user write privileges on the directory containing the Topic Map Editor Web Application files.

To test the Topic Map Editor Web Application is running simply enter the URL of the Topic Map Editor application into a browser. A web page listing all the topic maps available in the TMCore database will be displayed if everything is correctly configured.

Upgrading From A Previous Release

Note

The upgrade script tmcore-1.3-to-2.0-upgrade.sql is known to generate some warning messages to do with a renaming of certain stored procedures. The warnings are shown below and can be safely ignored as these are all internal stored procedures and should not have been used in any custom code.

Caution: Changing any part of an object name could break scripts and stored procedures.
The object was renamed to '_TM_NEXTID_SP'.
Caution: Changing any part of an object name could break scripts and stored procedures.
The object was renamed to '_TM_GETRELATEDTOPICS_SINGLE_SP'.
Caution: Changing any part of an object name could break scripts and stored procedures.
The object was renamed to '_TM_GETTRANSITIVECLOSURE_SP'.

Note

We STRONGLY RECOMMEND that you perform a full database backup before attempting an upgrade. Our scripts have been written and tested to be non-destructive in their effects, but a full backup provides you with complete data security should anything go wrong in the upgrade process. We also recommend that you make a backup copy of any configuration files (such as Web.config files) that are contained inside the TMCore installation directory before running the installer - again the installers are designed to not modify these files and to automatically create a backup web.config file for the web applications, but making a separate copy provides you with an additional level of backup should the installation process go wrong for any reason.

If you do encounter any trouble with the upgrade process, please let us know be reporting the error to us at support@networkedplanet.com.

Upgrading from TMCore07 Service Pack 5

There are no additional actions required when upgrading from TMCore07 SP5.

Upgrading From TMCore07 Service Pack 4

There are no additional actions required when upgrading from TMCore07 SP4.

Upgrading From TMCore07 Service Pack 3

Several stored procedures and user-defined functions have been updated in this release. The changes will not modify any of your data.

The script for this upgrade is install_directory/scripts/tmcore-2.3-to-2.4-upgrade.sql. Run this SQL script against your TMCore database using SQL Server Query Analyzer, SQL Server Management Studio or the command-line ISQL tool.

Upgrading From TMCore07 Service Pack 2

Database Upgrade

Note

The changes made to the database by this upgrade are not backwards-compatible with previous versions of the TMCore client libraries. After installing this upgrade you must upgrade all clients and web applications that connect to the database.

Several stored procedures and user-defined functions have been updated in this release. The changes will not modify any of your data.

Apply the following update scripts to the database in the order specified below.

install_directory/scripts/tmcore-2.0-to-2.2-upgrade.sql.
install_directory/scripts/tmcore-2.2-to-2.3-upgrade.sql
install_directory/scripts/tmcore-2.3-to-2.4-upgrade.sql

Web.Config modifications

The Web.config files provided with TMCore07 SP2 contained version-specific assembly references which need to be modified. It is possible to change these references to remove the version number, thus ensuring that any future updates will not require another modification.

Topic Map Web Service Web.config

In the Web.config file for the Topic Map Web Service, one change need to be made in the configSections element. This should be found near the top of the Web.config file.

Procedure 1. To Update the Topic Map Web Service Web.config File

Open the Topic Map Web Service Web.config file (install_directory/TMService/Web.config) in Notepad or another text editor.

Locate the line that reads:

<section name="ontology" type="NetworkedPlanet.TMCore.Utils.OntologySectionHandler, tmcore, Version=2.0.0.0, Culture=neutral, PublicKeyToken=da294bc4e1ae447d"/>

Change this line to remove the assembly version information. The updated line should look like this:

<section name="ontology" type="NetworkedPlanet.TMCore.Utils.OntologySectionHandler, tmcore, Culture=neutral, PublicKeyToken=da294bc4e1ae447d"/>

Topic Map Editor Web.Config

The default web.config file for the TMEditor application provided with TMCore07 SP2 contains a version-specific reference to TMCore. This reference is not normally required and can safely be removed.

Procedure 2. To Update the Topic Map Editor Web.config File

Open the TMEditor web.config file (install_directory/TMService/Web.config in Notepad or another text editor.

Locate the section of the file that reads:

<compilation defaultLanguage="c#" debug="false">
  <assemblies>
    <add assembly="tmcore,Version=2.2.0.0,Culture=neutral,PublicKeyToken=da294bc4e1ae447d"/>
  </assemblies>
</compilation>

Replace this section with the following:

<compilation defaultLanguage="c#" debug="false"/>

Upgrading From TMCore07 or TMCore07 Service Pack 1

The database schema for TMCore07 Service Pack 1 has some enhancements over the schema used for TMCore07 SP1 and earlier. These new enhancements are primarily to support mixed x64 and x86 client architectures. The upgrade preserves all of your data.

From the TMCore07 SP2 release the installer will now attempt to automatically preserve your existing web.config files for the TMCore web services. This will work only if you install the upgrade to the same directory as the version being upgraded. In any event, we recommend that you make a manual backup of your web.config files and any other important files contained in the TMCore installation directory prior to applying the upgrade.

Procedure 3. To Upgrade from TMCore07/TMCore07 SP1

Install Microsoft .NET 2.0
This version of TMCore requires version 2.0 of the .NET framework. You MUST download and install this version of the framework before attempting to run the TMCore installer.
Register .NET 2.0 with IIS
If you have just installed .NET 2.0 you should register the framework with IIS. Refer to the section called “.NET Framework 2.0” for more information.
Install TMCore07 SP3
Run the installer for TMCore07 SP3. This will upgrade the TMCore binaries and documentation. Applications compiled against previous versions of TMCore and targetting .NET 1.1 will need to be recompiled to target the .NET 2.0 framework.
Upgrade The Database
Apply the following update scripts to the database in the order specified below.
1. install_directory/scripts/tmcore-2.0-to-2.2-upgrade.sql.
2. install_directory/scripts/tmcore-2.2-to-2.3-upgrade.sql
3. install_directory/scripts/tmcore-2.3-to-2.4-upgrade.sql
Run these SQL scripts against your TMCore database using SQL Server Query Analyzer or the command-line ISQL tool.
Update Web.Config Files
During the installation the existing Web.config files for the TMCore web services are backed up with the name Web.config.bak and a new web.config file is installed in their place. When upgrading from TMCore07 or TMCore07 SP1, you can simply copy these backup files back over the new web.config file with just two small amendments as noted below:
1. Update for TMService Web.config
  The Web.Config file for the TMService application may include a line like the following inside the configSections element:
```
<section name="queries" type="NetworkedPlanet.TMService.QuerySectionHandler, tmws, ..."/>
```
  If so, this assembly reference is no longer valid and in fact is not needed, only the class name is required. The section element should be replaced with the following:
```
<section name="queries" type="NetworkedPlanet.TMService.QuerySectionHandler"/>
```
2. Update For NPCLService Web.Config
  The Web.config file for the NPCLService application may include a line like the following inside the configSections element:
```
<section name="schemas" type="NetworkedPlanet.Npcl.WebServices.NpclWSConfigurationHandler, NetworkedPlanet.Npcl.WebServices, Version=1.1.0.0, Culture=neutral, PublicKeyToken=da294bc4e1ae447d" /> 
```
  The assembly reference is not correct in version number and is redundant - only the class name is required. The section element should be replaced with the following:
```
<section name="schemas" type="NetworkedPlanet.Npcl.WebServices.NpclWSConfigurationHandler"/>
```

Upgrading From TMCore05 Service Pack 3

The database schema for TMCore07 SP3 has some non-destructive enhancements over the schema used for TMCore05 SP3. We have provided SQL scripts to perform this database upgrade.

Procedure 4. To Upgrade from TMCore05 SP3 to TMCore07 SP3

Install Microsoft .NET 2.0
This version of TMCore requires version 2.0 of the .NET framework. You MUST download and install this version of the framework before attempting to run the TMCore installer.
Register .NET 2.0 with IIS
If you have just installed .NET 2.0 you should register the framework with IIS. Refer to the section called “.NET Framework 2.0” for more information.
OPTIONAL: Backup Web.config files
There have been some significant changes to the Web.config file formats beween TMCore05 and TMCore07.
If you wish to keep any aspects of the configuration of these Web.config files, you should move the files to a directory outside the TMCore installation directory hierarchy before continuing. After installation of TMCore07 you should manually merge the configuration files installed by the TMCore07 installer and the files that you saved in this step.
Uninstall TMCore05
Before installing TMCore07 you should first uninstall TMCore05. You can uninstall TMCore05 using the Add/Remove Programs option in the Control Panel.
Install TMCore07 SP3
Run the installer for TMCore07 SP3. This will upgrade the TMCore binaries and documentation. Applications compiled against TMCore05 SP3 and targetting .NET 1.1 will need to be recompiled against TMCore07 SP3 and target the .NET Framework version 2.0.
Upgrade The Database
BEFORE running any TMCore07 applications or web services, you MUST upgrade the database. To do this you must apply the following update scripts to the database in the order specified below.
1. install_directory/scripts/tmcore-1.3-to-2.0-upgrade.sql.
2. install_directory/scripts/tmcore-2.0-to-2.2-upgrade.sql
3. install_directory/scripts/tmcore-2.0-to-2.3-upgrade.sql
4. install_directory/scripts/tmcore-2.3-to-2.4-upgrade.sql
Run these SQL scripts against your TMCore database using SQL Server Query Analyzer or the command-line ISQL tool.
Upgrade The Web.Config Files
During installation, the pre-existing Web.config files for the TMCore web services are backed up as files named Web.config.bak. As there have been some significant changes to the Web.config file structure between TMCore05 and TMCore07, it is recommended that you manually merge any local configuration from the Web.config.bak file into the new Web.config file.

Upgrading From TMCore05 Service Pack 2

The database schema for TMCore07 SP3 has some non-destructive enhancements over the schema used for TMCore05 SP2. We have provided SQL scripts to perform this database upgrade.

Procedure 5. To Upgrade from TMCore05 SP2 to TMCore07 SP3

Install Microsoft .NET 2.0
This version of TMCore requires version 2.0 of the .NET framework. You MUST download and install this version of the framework before attempting to run the TMCore installer.
Register .NET 2.0 with IIS
If you have just installed .NET 2.0 you should register the framework with IIS. Refer to the section called “.NET Framework 2.0” for more information.
OPTIONAL : Backup Web.config files
There have been some significant changes to the Web.config file formats beween TMCore05 and TMCore07.
If you wish to keep any aspects of the configuration of these Web.config files, you should move the files to a directory outside the TMCore installation directory hierarchy before continuing. After installation of TMCore07 you should manually merge the configuration files installed by the TMCore07 installer and the files that you saved in this step.
Uninstall TMCore05
Before installing TMCore07 you should first uninstall TMCore05. You can uninstall TMCore05 using the Add/Remove Programs option in the Control Panel.
Install TMCore07 SP3
Run the installer for TMCore07 SP3. This will upgrade the TMCore binaries and documentation. Applications compiled against TMCore05 SP2 and targetting .NET 1.1 will need to be recompile against TMCore07 SP3 and must target the .NET Framework version 2.0.
Upgrade The Database
BEFORE running any TMCore05 applications or web services, you MUST upgrade the database. You must run the following scripts IN THE ORDER SPECIFIED BELOW.
1. install_directory/scripts/tmcore-1.2-to-1.3-upgrade.sql
2. install_directory/scripts/tmcore-1.3-to-2.0-upgrade.sql
3. install_directory/scripts/tmcore-2.0-to-2.2-upgrade.sql
4. install_directory/scripts/tmcore-2.2-to-2.3-upgrade.sql
5. install_directory/scripts/tmcore-2.3-to-2.4-upgrade.sql
Run these SQL scripts against your TMCore database using Query Analyzer or the command-line ISQL tool.
Upgrade The Web.Config Files
During installation, the pre-existing Web.config files for the TMCore web services are backed up as files named Web.config.bak. As there have been some significant changes to the Web.config file structure between TMCore05 and TMCore07, it is recommended that you manually merge any local configuration from the Web.config.bak file into the new Web.config file.

Upgrading From TMCore05 Service Pack 1

The database schema for TMCore07 SP3 has some non-destructive enhancements over the schema used for TMCore05 SP1. We have provided SQL scripts to perform this database upgrade.

Procedure 6. To Upgrade from TMCore05 SP1 to TMCore07 SP3

Install Microsoft .NET 2.0
This version of TMCore requires version 2.0 of the .NET framework. You MUST download and install this version of the framework before attempting to run the TMCore installer.
Register .NET 2.0 with IIS
If you have just installed .NET 2.0 you should register the framework with IIS. Refer to the section called “.NET Framework 2.0” for more information.
OPTIONAL: Backup Web.config files
There have been some significant changes to the Web.config file formats beween TMCore05 and TMCore07.
If you wish to keep any aspects of the configuration of these Web.config files, you should move the files to a directory outside the TMCore installation directory hierarchy before continuing. After installation of TMCore07 you should manually merge the configuration files installed by the TMCore07 installer and the files that you saved in this step.
Uninstall TMCore05
Before installing TMCore07 you should first uninstall TMCore05. You can uninstall TMCore05 using the Add/Remove Programs option in the Control Panel.
Install TMCore07 SP3
Run the installer for TMCore07 SP3. This will upgrade the TMCore binaries and documentation. Applications compiled against TMCore05 SP1 and targetting .NET 1.1 will need to be recompiled against TMCore07 SP3 and must target version 2.0 of the .NET Framework.
Upgrade The Database
BEFORE running any TMCore05 applications or web services, you MUST upgrade the database. You must run the following scripts IN THE ORDER SPECIFIED BELOW.
1. install_directory/scripts/tmcore-1.1-to-1.2-upgrade.sql
2. install_directory/scripts/tmcore-1.2-to-1.3-upgrade.sql
3. install_directory/scripts/tmcore-1.3-2.0-upgrade.sql
4. install_directory/scripts/tmcore-2.0-to-2.2-upgrade.sql
5. install_directory/scripts/tmcore-2.2-to-2.3-upgrade.sql
6. install_directory/scripts/tmcore-2.3-to-2.4-upgrade.sql
Run these SQL scripts against your TMCore database using Query Analyzer or the command-line ISQL tool.
Upgrade The Web.Config Files
During installation, the pre-existing Web.config files for the TMCore web services are backed up as files named Web.config.bak. As there have been some significant changes to the Web.config file structure between TMCore05 and TMCore07, it is recommended that you manually merge any local configuration from the Web.config.bak file into the new Web.config file.

Note

The database upgrade creates two new database roles, tm_reader and tm_writer. You may wish to put all topic map users (including the accounts used by IIS for web applications), into one or both of these groups. As the names suggest, the tm_reader group has read-only access to the TMCore tables, views and stored procedures; whereas the tm_writer group has read/write access to tables and read access to views and stored procedures.

Upgrading From TMCore05 1.0

There is no automated upgrade from pre-SP1 versions of TMCore05. It is therefore vital that you follow these instructions carefully if you wish to preserve the data stored in your TMCore05 database.

If you have topic map data you wish to preserve, you must perform the following steps:

Export the topic map(s) you wish to preserve as XTM files.
A command-line application for exporting some or all of the topic maps from a TMCore database can be downloaded from http://www.networkedplanet.com/support/tmcore05/utilities/tmexport/.
Delete the database used by the previous version of TMCore05.
This step is recommended but not required as the installation script will drop old tables, views and indexes as necessary.
Uninstall TMCore 05. If any files remain in the directory after the uninstall is complete (e.g. Web.config files that you locally modified), delete these files or move them to a separate backup location before continuing with the installation.
Install TMCore07 SP3 - following the instructions for a fresh installation given in this document.
Use the tmimport command to import the XTM files created in step 1.

Troubleshooting Guide

This section presents some common installation issues and the resolution for them.

Symptoms and Causes

The first step in troubleshooting your installation is to try and determine the cause of the problem. The following table lists some common symptoms and ways to determine the real cause of the problem.

Table 1. Troubleshooting Symptoms and Causes

Symptom	Possible Causes
Topic Map Web Service or NPCL Web Service Returns a 500 Error	The most common causes of this problem are either: The license file is not correctly installed. To check if this is the case, try running the tmimport program to import an XTM file into the database, running the program with the -v switch. If the program does not successfully import the XTM file, check the error messages to see if there is a message about the NetworkedPlanet.TMCore.TMAPI.TopicMapSystem component not being licensed. If this is the case, refer to the solution Ensure Correct License File Installation. The ASPNET user is not allowed to access the TMCore database. See the solution Grant Database Access to ASPNET user. The database connection string for the Web Service is not correctly configured. See the solution Configure Web Service Database Connection String.
The Topic Map Web Service returns HTML pages rather than XML.	The installation should automatically create the virtual directories tmws and tmnav on the Default Site of your IIS installation and set those virtual directories to be application directories. In some isolated cases it appears that although the virtual directory is created, it is not properly configured as an application directory. This problem can be solved by following the solution Enable Web Applications.
IIS reports "Page Cannot Be Found" when attempting to access the web applications	This can occur on IIS 6 if ASP.NET has not been registered or configured as an allowed web service extension. Please refer to the section called “.NET Framework 2.0” for details on how to register ASP.NET with IIS.

Solutions

To find the most appropriate solution for the installation problem you are facing, please refer to the section called “Symptoms and Causes”

Enable Web Applications

To enable a virtual directory as a web application:

Open the Internet Information Services (IIS) management console from the Control Panel.
Select the virtual directory, right-click and from the pop-up menu choose "Properties". For TMCore, the default virtual directories are named 'tmws' and 'npclws'.
In the 'Application Settings' section of the 'Virtual Directory' tab of the properties dialog, check if the 'Application name' text box is active. If it is not, then the directory has not been configured as a web application. To configure the directory, click the button marked 'Create'. You can leave the other settings at their default value.
Click 'OK' to commit the changes you have made to the virtual directory.

Configure Web Service Database Connection String

By default the database connection string is set to access a database called 'topicmap' on the same machine as the web server, using Windows authentication. If any of these three parameters are different for your installation, you will need to modify the connection string that the web service uses. The connection string can be found in the Web.config file of the web service application directory, inside the appSettings element. Look for the following:

<add key="networkedplanet.tmcore.dbconnect"  value="..." />

The value attribute contains the connection string used by the web service. This is a normal SQL connection string and you should edit this string to reflect the connection required by your system configuration.

Grant Database Access to ASP.NET Application Pool

When the Topic Map Web Service connects to the database using Windows authentication, it does so using a user account specified in the configuration of the web application. By default for IIS 5.0, this account is a user account on the local machine with the account name ASPNET. For IIS 6, the default application pool identity is the built-in account "Network Service".

Whatever application pool the topic map services run under must at least be granted access to the TMCore database with the tm_reader role (and to support any update operations, the tm_writer role must also be granted). Depending upon your security policies you may wish to create a new application pool with these additional privileges, or you may wish to grant the privileges to the default application pool.

What ever user account is used by the Topic Map Web Service MUST be granted at least read access to the TMCore database. If you wish to support the editing of the topic map through the web service, you MUST also grant write access to the database. The simplest way to grant read or write access is as follows:

If the account is not already registered as a database login, create a new login for this account using the SQL Server Enterprise Manager.
If using the default local machine's ASPNET user, then the login should be granted for the account Machine Name\ASPNET, where Machine Name is the name of the server machine e.g. APOLLO\ASPNET. If using the local machine's Network Service account, grant access to the local group Machine Name\IIS_WPG.
Add the database login for the account to the users listed under the TMCore database (this can be done through the Users item listed under the database in the SQL Server Enterprise Manager).
When adding the user, ensure that the default role tm_reader is checked, and that the role tm_writer is checked if you wish to allow topic map updates to be made through the Web Service.

Please refer to the SQL Server documentation for a detailed description of the procedure for adding a new Windows account as a database user.

Please refer to your IIS documentation for detailed instructions on how to create new application pools and the security and performance implications of doing so.

Ensure Correct License File Installation

Please refer to the section called “Installing the License File” for details on how the license file must be installed. When installing the license file, you must ensure that all user accounts that access the TMCore system (including the user accounts used by the Web Services) are granted permission to read this file.

Support

If you are experiencing problems with installation and configuration please contact <support@networkedplanet.com>.