Enterprise Tester

Initial Login and Licensing

Before you can use the application you will need to configure your organization name, an administrative user and license details. You will be prompted to do this the first time that you launch the application.

Generating a License Key

To do this copy the server key as listed on the screen and send it to Catch Sales to assist you in generating a license.  The sales team will provide you with the licence text required to enable your license.

Enter the license text into the Enterprise Tester License Text field and click on ‘Save’.

You are now ready to logon to Enterprise Tester.

SQL Login

Configuring SQL Server and Enterprise Tester to Use a SQL Login

This guide walks through the steps for creating a SQL login and updating the web.config file for Enterprise Tester using the login for authentication.

Create a SQL user name/login on the server you wish to access

• Open SQL Server Management Studio.
• Connect to the SQL server.
• Go to security->logins.
• Right click, select “New Login”.

• Select SQL Login.
• Enter the username and password you wish to use.
• Disable password policy enforcement, and ensure that the login does not expire, and does not require changing on next login.

• Click on user mappings.
• Find the Enterprise Tester database.
• Click the checkbox next to it, to give the new user access.
• Ensure the new user has either public and db_owner permissions, or public, datareader, datawriter and ddl permissions (as shown in the following screen shot).

• Click “OK” to save this new user.

Update the web.config file, so it uses the new SQL server login/password

• Locate Enterprise Tester’s web.config file (normally in C:\Program Files\Catch
• Limited\Enterprise Tester\Web\web.config).
• Open the file with a text editor.
• Locate the <connectionStrings> section in the configuration file.
• Update the connection string, removing any of the following properties:

  o Integrated Security=True;

  o AttachDbFilename=<path>;

  o Trusted_Connection=Yes;

• Add the User Id and Password properties, for the login/password you created prior.
• Save changes to the web.config file.
• Access the Enterprise Tester website, to ensure the database changes have worked.

User attached instance migration

User Attached Instance Migration after Data Recovery

This guide is intended to provide directions on how to migrate away from a User Attached instance to a standard database instance after data recovery has been performed. For details on what a user instance, see this MSDN article: http://msdn.microsoft.com/en-us/library/ms254504.aspx

Preparation

To proceed with migrating away from a user instance you will need to:

• Have a backup of your database, that backup file should end with the file extension .bak, if you have a zip file of the database backup provided from Catch limited, you will need to unzip the contents to the sql server’s hard drive first.
• Have Sql Server Express Management Studio installed – this can be downloaded from the following location:

  http://www.microsoft.com/downloads/details.aspx?familyid=C243A5AE-4BD1-4E3D-94B8-5A0F62BF7796&displaylang=en 

Last of all, before commencing installation please reboot the machine, and stop the IIS service (Start -> Control Panel -> Administrative Tools -> Internet Information Services -> local computer (right click) -> Restart IIS -> Stop Internet Services). This should prevent users from accessing Enterprise Tester, causing the existing database to attempt attachment.

Restoring the Database

Launch the Sql Server Management Studio via:

Start -> Microsoft Sql Server 2005 -> SQL Server Management Studio Express

Once loaded, connect to your local SQL Express instance (this should just be matter of clicking the connect button). If the Server Name textbox is blank then enter the text “.\SqlExpress” before clicking the “Connect” button.

Once connected expand the right hand tree node, then right click on the “Databases” node and select “New Database…”.

Enter “EnterpriseTester” as the database name, and click OK.

Expand the “Databases” node, you will now see a child database node underneath “EnterpriseTester”.

Right click on the “EnterpriseTester” node, select Tasks -> Restore -> Database.

On the Restore Database dialog, select the “From device” radio button.

Click the Elipsis button “…” to the right of the “From Device:” radio button.

Click the “Add” button.

Browse to the location where you saved the database backup file ending with the extension .bak, and select it.

Click “OK”.

Click the Restore “checkbox” next to the first entry in the “Select the backup sets to restore” list.

Click the “options” link on the left hand side, to view the options page.

Click the checkbox next to “Overwrite the existing database”.

You will see two entries “EnterpriseTester” and “EnterpriseTester_log” with the following “Restore  As” paths.

Double click on “Restore As” and change the paths from:

C:\db\new\EnterpriseTester.mdf
C:\db\new\EnterpriseTester_log.LDF

TO:

C:\Program Files\Microsoft SQL Server\MSSQL.1\MSSQL\Data\EnterpriseTester.mdf
C:\Program Files\Microsoft SQL Server\MSSQL.1\MSSQL\Data\EnterpriseTester_log.LDF

Alternatively you can browse for these paths by clicking the Elipsis “…” button next to each path.

Click the “OK” button to proceed with restoring the backup.

Once completed you should see the message “The restore of database ‘EnterpriseTester’ completed successfully’.

Changing the Enterprise Tester Connection String

Open windows explorer.

Navigate to the Enterprise Tester installation directory (normally c:\Program Files\Catch Limited\Enterprise Tester)

Navigate to the subdirectory “Web”.

Open the file called “web.config” with a text editor, such as windows notepad.

Locate the default connection string, which should look similar to this:

And then replace the connection string with the following:

Test It

Restart the IIS service (Start -> Control Panel -> Administrative Tools -> Internet Information Services -> local computer (right click) -> Restart IIS).

Access the Enterprise Tester website, you should be presented with a login screen.

If instead an error is displayed the contact customer support and supply them with the following
information:

• The log.txt file (found c:\Program Files\Catch Limited\Enterprise Tester\Web\App_data).
• A screen shot or copy of the error message displayed when accessing the website.
• Version of Enterprise Tester.
• Operating System, Version & Service Pack details.

Performing Backups

Now that you have migrated away from a user instance, you should no longer user file copy to backup your database. Instead backups should be performed via Sql Management Studio.

This guide on MSDN provides details on how to do so:

http://msdn.microsoft.com/en-us/library/ms187510.aspx

Backups of databases can be automated as well with some simple scripting, more details can be
found here:

http://www.brianmadden.com/blogs/guestbloggers/archive/2007/05/07/how-to-automate-thebackup-of-a-sql-server-2005-express-data-store.aspx

Backup Support

Please note that backing up databases, and automation of backups is outside the scope of the support Catch Limited provides to Enterprise Tester customers – additional support needs to be handled by your in-house database administrators and database vendors.

Data migration from Trial version of Enterprise Tester

Introduction

This guide provides information on how to backup data from Enterprise Tester, and how to migrate from the trial version database to another version of sql server.

Backing up data from your trial version of Enterprise Tester.

Enterprise Tester, when installed via the MSI file, will use Sql Server Express Edition 2005 to store it’s data, making use of a feature of sql server express, which allows attaching a database file upon connect. While trialing and evaluating Enterprise Tester this provides a simple set-up, which makes it easy to uninstall the product cleanly at a later date, or to apply updates.

To backup your data while in this set up, the easiest approach is to stop the sql server express database server, copy the data files, and restart it again.

Stopping Sql Server Express

You can stop the Sql Server Express Edition server, by loading the services snap-in:Start -> Control Panel -> Administative Tools -> Services

Once loaded, locate the sql server express service, which normally has the name:SQL Server (SQLEXPRESS)

Right click, and select “Stop”. This will stop the service, which will allow the database files to be copied.

Copying the data files

Open windows explorer, and browse to the data folder of your Enterprise Tester install folder i.e. c:\Program Files\Catch Limited\Enterprise Tester\Data\

In this directory will be two files:

• EnterpriseTester.mdf
• EnterpriseTester_log.LDF

Copy these two files to another location, these are the backup files which you can restore at a later date if something goes wrong.

Restarting the Sql Server Express database server

Once your have completed the backup, right click on the “SQL Server (SQLEXPRESS)” service, and select “Start” to restart sql server express edition, at which point you can start using Enterprise Tester again.

Migrating your trial database to a be a permanent sql server Database

Introduction

When putting Enterprise Tester into production use, it’s recommended that you stop using the default “attach on connect” approach employed by the msi installer, and instead instantiate a permanent Sql Server or Sql Server Express database.

Advantages of permanent database

The advantages of doing this include:

• Your database administrator can handle configuring scheduled daily backups and maintenance.
• You can query the database using reporting tools.
• You can easily backup and restore snapshots of the database to create test / training versions of ET.

Before you start

Before starting the migration – you must have the sql server management studio tool available.If you do not, it can be downloaded and installed from microsoft:

http://www.microsoft.com/downloads/details.aspx?familyid=08E52AC2-1D62-45F6-9A4A-4B76A8564A2B&displaylang=en

These instructions assume the tools are installed on the same machine as Enterprise Tester.

Step 1 – Restart or Stop IIS

Either through IIS Manager:

• Click on Start -> Control Panel -> Administrative Tools -> Internet Information Services(IIS) Manager
• Right click on local machine node (should have the same name as your computer) and select Stop, or in IIS6, select All Tasks -> Restart IIS.

Alternatively you can open a windows command prompt and type “iisreset” – this will stop and restart IIS on the local machine, if you have the IIS command line tools installed.

Step 2 – Attach the database files in Sql Server Express.

Sql Server not Supported

These files cannot be directly attached in the Standard or Enterprise editions of Sql Server, the data files use compression which is incompatible with the non-express editions of Sql Server – so you must first attach them in the Express Edition of Sql Server, then create a backup of the databases, which can be restored into any version of Sql Server.

Start Sql Server Management Studio or Sql Server Express Management Studio.

When prompted to connect, connect to the .\sqlexpress database.

Once connected, right click on the “Databases” folder and select “Attach”.

The attach database dialog will appear. Click the “Add” button to attach the database file, browse to the Install folder of Enterprise Tester, and select the Data\EnterpriseTester.mdf. Normally the database is located in “C:\Program Files\Catch Limited\EnterpriseTester”.

Once the file is selected, the attach database dialog will look like this:

It’s suggested you change the name given to the attached database, so that it’s “EnterpriseTesterTrial”, like so:

Click OK to attach the database, it should now appear in the list of databases.

Backing Up the Database

Now that the database is attached, we can back it up – this will then allow us to restore the database onto any sql server we like. Right click on the EnterpriseTesterTrial database, then select Tasks -> Backup…

This will display the backup dialog, select a location for your backup file i.e. c:\temp\EnterpriseTesterTrial.bak and then click ok.

You will now have a backup of the Enterprise Tester trial database.

Restoring the database on another server

You can now restore the database on another server, such as the sql server your environment already uses for other applications. To do so you must:

• First, create a new database, that will be the target for the restoration.
• Restore the database.

To create a new database, right click on the “Databases” and select “New Database…”.The new database dialog will display:

Enter a name for your database, such as “EnterpriseTester” and click OK. A new database will appear in the tree with the name “EnterpriseTester”. Right click on this node, and select Tasks -> Restore Database…, the restore database dialog will appear.

From here you must select the location of the backup you wish to restore, locate the file from the previous step i.e. c:\temp\EnterpriseTesterTrial.bak.

Once a backup file has been selected, you must then select which backup to restore – there should be only a single item, just click the checkbox next to it.

Once the backup has been selected, select the “Options” page.

• Check “Overwrite the existing database (WITH REPLACE)”.
• Edit the “Restore As” value for both the “EnterpriseTester” and “EnterpriseTester_log” database files.
• By default these will be pointing the old location of the database files from the attached database, you must browse and locate the existing database and log files that you created when adding the database.
• Click OK to restore the database.

Finding the existing location of database files

The location of database files can vary greatly, you can determine the correct location by:

• Right clicking on the “EnterpriseTester” database and selecting Properties.
• When the properties dialog displays, select the “Files” page.
• Under “Database Files” scroll the display to the right, until you can see the “Path” column. This will display the path for each database files, use these paths when restoring the database from the trial version backup.

Changing the connection string for the application

Now that the database has been moved you must change the connection string for the application.

In the installation directory of Enterprise Tester, locate the “web.config” file, which is stored in the “Web” subdirectory.

Open this file with a text editor, and locate the “<connectionStrings>” section, which should look like this:

<connectionStrings>
<add name=”Default” connectionString=”Data Source=.\SQLExpress;AttachDbFilename=C:
\Program Files\Catch Limited\Enterprise Tester\Data\EnterpriseTester.mdf;Initial
Catalog=EnterpriseTester;User
Instance=True;MultipleActiveResultSets=true;Trusted_Connection=Yes;”/>
</connectionStrings>

You must now replace the existing connection string,
i.e. Data Source=.\SQLExpress;AttachDbFilename=C:\Program Files\Catch Limited\Enterprise
Tester\Data\EnterpriseTester.mdf;Initial Catalog=EnterpriseTester;User
Instance=True;MultipleActiveResultSets=true;Trusted_Connection=Yes;
with the connection string for the new sql server database.

If, for example our server was called “SQLPROD1″, this might mean we change the connection string to be:

<connectionStrings>
<add name=”Default” connectionString=”Data Source=SQLPROD1;Initial
Catalog=EnterpriseTester;MultipleActiveResultSets=true;Trusted_Connection=Yes;”/>
</connectionStrings>

For examples of valid Sql Server connection strings, please see the following website:
http://www.connectionstrings.com/sql-server-2008#p1

Once you have made your changes, click save, and then refresh Enterprise Tester in the browser to make sure it worked correctly.

Required Database Permissions

The user that accesses the database must have permissions to add, remove and alter tables and foreign keys. This is required by the automatic migration support in Enterprise Tester, which handles upgrading the database schema automatically.

Because this access is only required during upgrades, it is possible for a Database Administrator to enable it during an upgrade, and once Enterprise Tester has successfully started, to remove the permissions from the user (or to change which user accesses the database).

Database configuration

To change which database is being targeted, the web.config file must be edited, and at a minimum there are 3 options which must be changed to support each database engine – as per the table below:

Oracle is no longer a supported database for Enterprise Tester.

Database Specific Notes on Setting the Character Set

MySQL

Enterprise Tester supports unicode strings in MySql databases, but you must ensure some steps are followed during initial setup.

Step 1 – Database Creation

When creating the database, you must specify UTF8 as the default character set and utf8 case insensitive as the default collation: 

 CREATE DATABASE `enterprisetester` CHARACTER SET utf8 COLLATE utf8_general_ci; 

Step 2 – Configuring Character Set in Connection String

If your connection string to the MySql database is: 

<add name="Default" connectionString="Server=10.1.1.1;Database=enterprisetester;Uid=etuser;Pwd=etpass" />

Then you must append the UTF8 character set declaration to end, like so:

<add name="Default" connectionString="Server=10.1.1.1;Database=enterprisetester;Uid=etuser;Pwd=etpass;CharSet=utf8;" />

If you have not set the UTF8 character set, there are ways to change the character set through a process of dumping out the database, performing a search/replace of all character set / collation declarations, then importing the modified database dump. Please consult your in-house MySql DBA for assistance.

PostgreSQL

Enterprise Tester supports unicode strings in Postgresql databases, but you must ensure some steps are followed during initial setup of the database. Before beginning, make sure you have a version of PostgreSQL that supports a column type of “uuid” (normally version 8.3 and later) as this is required by Enterprise Tester.

PostgreSql Databases must be created with a unicode encoding and we recommend using “UTF-8”. If you use a non-unicode encoding such as WIN1252 Enterprise Tester will still work, but you may experience some issues when restoring baselines from other ET instances, importing data or when users save textual data that contains unicode characters.

For Postgresql to support unicode strings, you must create the database with the ‘UTF8’ encoding, like so: 

CREATE DATABASE "enterprisetester"
  WITH OWNER "postgres"
  ENCODING 'UTF8'
  LC_COLLATE = 'en_US.UTF-8'
  LC_CTYPE = 'en_US.UTF-8';

Unlike MySql there is no need to change the connection string to accommodate UTF8 encoding. If you wish to learn more about setting the locale and collation for a PostgreSql database, please refer to the PostgreSql documentation: 

http://www.postgresql.org/docs/current/interactive/locale.html
http://www.postgresql.org/docs/current/interactive/collation.

Example Connection Strings

Each database also uses a slightly different connection string format – the http://connectionstrings.com/ website provides useful details of each connection string format.

Configuring a PostgreSQL Database

Before beginning, make sure you have a version of PostgreSQL that supports a column type of “uuid” (normally version 8.3 and later) as this is required by Enterprise Tester.

Configure web.config to connect to a database

Overview

Within the web folder you will find the file “web.config” – this is a XML file containing a number of settings which configure settings for the Enterprise Tester application, including what type of database to connect to and its connection string details.

By default this file is located:

Open the file using notepad, within it you will need to change 4 settings:

• “migration.providerName”
• Default connection string
• connection.driver_class
• dialect

These are the default settings:

“migration.providerName”

Default connection string

connection.driver_class

dialect

Following are the web.config values you will need for each type of database:

SQL Server

By default the web.config file comes with the settings necessary to connect to Sql Server or Sql Server Express – all you need to do is provide a connection string.

Your options are:

1. Use the provided database with user-attached connection string.

2. Connect to an existing database, using integrated security.

3. Connect to an existing database, using a sql username & password.

PostgreSql

Change Enterprise Tester to use these values:

migration.providerName: “Migrator.Providers.PostgreSQL.PostgreSQL82Dialect”
connection.driver_class: “NHibernate.Driver.NpgsqlDriver”
dialect: “NHibernate.Dialect.PostgreSQL82Dialect”

And update the connection string to be like this:

MySql

Change Enterprise Tester to use these values:

migration.providerName: “Migrator.Providers.Mysql.MysqlDialect”
connection.driver_class: “NHibernate.Driver.MySqlDataDriver”
dialect: “EnterpriseTester.Core.Dialects.MySqlDialectEx, EnterpriseTester.Core”

And update the connection string to be like this:

More examples of connection strings can be found here: http://connectionstrings.com/mysql#p28