ecopy sharescan® 5.0 sql installs guide › ci › fattach › get › ...mar 28, 2011 ·...
TRANSCRIPT
-
eCopy™ ShareScan® 5.0
SQL installs guide
Created by Rob O’Leary, 3/28/2011
-
5.0 SQL installs guide |2
ShareScan 5.0 has two SQL setup types:
Complete:
Installs and connects the local MS SQL Server 2008 Express R2 to the ShareScan Manager.
The default usernames and passwords are:
Username: sa Username: ecopy
Password: e+C0py2007_@x Password: e+C0py2007_@x
Custom:
Allows disabling the local install of MS SQL Server 2008 Express R2, and connects to an existing
local or remote database.
IMPORTANT FACT: The sa password will need to be supplied by the Customer’s IT Department.
-
5.0 SQL installs guide |3
You have two Custom options
Option One:
If the you would like to have the ShareScan database installed on an existing SQL server, disable the
"MS SQL Server 2008 Express R2" option.
-
5.0 SQL installs guide |4
Option two:
If you would like to connect to an existing ShareScan database installed on an existing SQL server,
disable "ShareScan Database".
This option should be selected in the case when you’ll have multiple Managers connecting to a single,
centralized database. When installing the 2nd, 3rd, etc. Managers without a database – you’ll need tospecify the existing database at the first startup of the Administrator Console.
Click “NEXT”.
-
5.0 SQL installs guide |5
You will then be prompted to connect to the Database Server:
IMPORTANT FACT: ShareScan only supports Mixed Mode Authentication. ShareScan does not support
Windows Integrated authentication).
You will need to enter in the SA username and password or an account with SYSADMIN permissions.
-
5.0 SQL installs guide |6
1. If any of the provided connection parameters are incorrect, then you may receive the followingerror message when clicking "Next".
Solution: Verify that all parameters are correct and try again.
Click “NEXT”.
The install will build out the SQL tables and stored procedures.
-
5.0 SQL installs guide |7
SQL Script commands
How to use database scripts:
The database backup and restore features are also offered via the Administration Console UI (Advanced
tab of the ribbon, Database button, Database Backup or Restore menu item) – for instructions and help
to use those, please consult with the ShareScan Administration Console Help.
This document provides details on how the command line scripts can be used for database backup andrestore. These scripts provide basic support for backing up and restoring an existing ShareScan
database. It is also possible to drop (delete) a corrupted database and create a new, empty one.
The backup and restore scripts can also be used as blueprints for a database administrator to set up an
automatic database backup.
ShareScan setup automatically installs four database scripts into the "C:\ProgramFiles\Nuance\ShareScan5\Server\Tools\Database" folder: db_inst.cmd, db_uninst.cmd, db_backup.cmdand db_restore.cmd
The user must provide proper parameters for the command line scripts. (Previous versions of these
scripts delivered with ShareScan have been using values pre-configured to use the local SQL Server
database, but these pre-configured values are now removed for security reasons).
SQL Scripts location:
C:\Program Files (x86)\Nuance\ShareScan5\Server\Tools\Database
Db_backup.cmd Runs a Backup on the DB
Db_inst.cmd Runs an Install on the DB
Db_restore.cmd Runs a Restore on the SQL DB
Db_uninst.cmd Runs an un-install on the SQL DB
-
5.0 SQL installs guide |8
5 SQL Query files:
eCopyShareScan.sql main SQL file
eCopyShareScan-Backup.sql Run when db_Backup.cmd is used
eCopyShareScan-Drop.sql Run when db_uninst.cmd is used
eCopyShareScan-Restore.sql Run when db_restore.cmd is used
ShareScanServer.sql Run when db_inst.cmd is used
Backing up a database
It is highly recommended to back up the ShareScan database when the initial configuration of the
system is complete. In order to backup an existing local database:
1. Make sure that Admin Console is not running
2. Launch a command line window and go to the "C:\ProgramFiles\Nuance\ShareScan5\Server\Tools\Database\" folder.
3. Enter and execute the following command:
db_backup.cmd [SQLSERVER] [backupUser] [backupPassword] [BackupFilePath]
(Please note that the names of the parameters shown by the script if you start it without parameters are
not precisely as shown above, as they are called ‘DatabaseUser’, ‘DatabasePassword’, and this naming
can be confusing – the “Usage” help provided by the command line scripts will be updated in the next
service pack. Please read the below information carefully to make sure you understand the purpose of
these parameters.)
-
5.0 SQL installs guide |9
The purposes of these parameters are:
[SQLSERVER] is the name (or IP address) of the SQL Server where the database to backup is hosted. This
should contain the instance name too, if the database is hosted in a named instance (versus to the
default SQL Server instance). Examples for valid SQLSERVER parameters:
BN-DBSERV1 The name of the machine where the SQL Server in use is installed
CORPDBSERVER\ECOPYDB A named instance of the SQL Server is created to host the ShareScan
database on the server ‘CORPDBSERVER’
10.140.112.12 The IP of the PC running the SQL Server is specified
.
(a period character)
The local SQL Server is used, with the default instance name. (This is
the case for the default installation of the SQL Server, created by the
ShareScan installer)
Please note that with the scripts you can perform backup or restore operation on remote SQL Servers
(i.e. SQL Servers running on another machine that you’re using to run the script) too.
[saUser] is the user name having the ‘sysadmin’ rights. This can be ‘sa’ (without quotes). If the ‘sa’
account is used/known only by the database administrator, then this can be another valid user (created
by the database administrator) that has the ‘db_backupoperator’ role assigned for the eCopyShareScan
database. NOTE: the ‘eCopy’ user (used by the ShareScan system for normal operations) is NOT
appropriate for this purpose, as it does not have the rights to perform a database backup.
[saPassword] password of the user described in the previous paragraph. If the database server is
installed by the ShareScan installer, then the ‘sa’ password will be e+C0py2007_@x
[BackupFilePath] the file name or the full file path you want to use as a database backup file. If only a
filename is specified, the backup file will be created in the backup folder of the SQL Server – this path is
set during the installation of the SQL Server, and will look like this:
C:\Program Files\Microsoft SQL Server\MSSQL10_50.MSSQLSERVER\MSSQL\Backup
(Depending on your SQL Server installation, the above example is from a default ShareScan installation
on a Windows7 OS. The easiest way of getting to know this path is to open the Database Backup or
Restore dialog in the ShareScan Administration Console.)
If you’d use the Administration Console to create a backup then the file name is created based on a file
naming rule
-
5.0 SQL installs guide |10
Backup-eCopyShareScan-MMDDYYYY-HHmmAA.bak
(MM = month, DD = day, YYYY=year, HH= hour, mm = minute, AA= AM/PM)
If you’re using the scripts discussed in this document, the file name specified by the last parameter can
be anything, but it is recommended to use the BAK extension. (The Restore dialog in the Administration
Console will show only the files having the BAK extension, that’s why we recommend this.)
If you specify a full file path, then the backup file will be created at the specified path on the server the
SQL Server is running (i.e. NOT the PC where you launched the db_backup.cmd script). Please make sure
the specified path does exist on the PC running the SQL Server you specify as the target of the backup
command. (1st parameter)
NOTE: Make sure you use double quotes to enclose this last parameter, if it contains a path (this is
required because of the backslash characters contained in the path).
The script stops the Manager and Agent services and creates a backup copy of the actual state of the
ShareScan database to the specified folder, into the file named as specified by the last parameter of the
command line. After completing the backup the script restarts the Agent and Manager services.
NOTE: Starting and stopping of the services performed by the script is meaningful only in the
case if you perform a database backup on the local machine. If you perform a database backup
on a remote database, or if there are multiple Managers connected to the database you want to
backup, you need to ensure that all the ShareScan Manager and ShareScan Agent services are
stopped before starting the backup operation, and restarted after completing the backup
operation successfully.
The result of the operation is logged into the file eCopyShareScan-Backup.log in the same folder from
where the command line script is started. It is a good practice to check the content of this log file to see
if there were no errors.
Example:
Db_backup.cmd BP-SHARESCAN1 sa e+C0py2007_@x db_backup_20110312.bak
This command will create a backup of the eCopyShareScan database hosted on the server named ‘BP-
SHARESCAN1’, and the backup file will be named as ‘db_backup_20110312.bak’ on that server, in the
folder described above. (And not on the PC from where we started the script – except if it was exactly
the PC named ‘BP-SHARESCAN1’)
-
5.0 SQL installs guide |11
Restoring a database
In order to restore a previous backup of the database:
1. Make sure that Admin Console is not running.2. Launch a command line window and go to the "C:\Program
Files\Nuance\ShareScan5\Server\Tools\Database\" folder.3. If you specify only the backup file name, then make sure that the database backup file (created
either by using the Backup – Restore dialog of the ShareScan Administration Console or by using
the db_backup.cmd script describe in the previous section) exists in the Backup folder that can
be found at C:\Program Files\Microsoft SQL Server\*\Backup – this folder certainly depends on
the installation path of the SQL folder and also can be different, if another path was specified
during the SQL Server installation. If you want to perform a restore operation from a backup file
that was created on another database server, then you need to copy the backup file into this
folder manually. (Or, you need to ask the database administrator to perform this copy
operation, if you do not have access to the physical server where the SQL Server is running.). Or,
if you want to perform the backup from another folder, specify the full path as the 4th parameter
of the script.
4. Enter and execute the following command:
db_restore.cmd [SQLSERVER] [backupUser] [backupUsrPassword] [BackupFilePath]
[eCopyUserPassword]
The meaning of the five obligatory parameters of the script is the same as for the Backup operation –
see the above section. The last parameter is an extra one, compared to the backup operation, and it
should contain the password that will be used as the password of the ‘eCopy’ database user used for
normal ShareScan operation.
NOTE: Please note that the password will be set to the value specified in the command line parameter
if there is no such user in the SQL Server. This means that if the ShareScan database was installed in
the same SQL Server previously, and the database users ‘eCopy’ and ‘eCopyAddressbookAdmin’ are
not deleted manually by the database administrator, then the passwords will not be overwritten with
the new value.
The script stops the ShareScan Manager and ShareScan Agent services and restores the ShareScan
database from the file specified. After completing the restore the script restarts the Agent and Manager
services.
NOTE: Starting and stopping of the services performed by the script is meaningful only in the
case if you perform a database restore on the local machine. If you perform a database restore
on a remote database, or if there are multiple Managers are connected to the database you
want to restore, you need to ensure that all the ShareScan Manager and ShareScan Agent
-
5.1 SQL installs guide |12
services are stopped before starting the restore operation, and restarted after completing the
restore operation successfully.
The result of the operation is logged into eCopyShareScan-Restore.log in the folder from where the
script is started. It is a good practice to check the content of this log file to see if there were no errors.
Creating a new, empty database
It might be necessary to recreate the entire database due to system failure and/or missing backup.
Please note that whenever you recreate the database you will lose all existing configuration settings
and you have to reconfigure the system. Creating a new empty database is a two phase process. First,
the existing database has to be dropped and then the new empty database has to be created.
In order to drop (delete) the existing database:
1. Make sure that Admin Console is not running.2. Launch a command line window and go to the "C:\Program
Files\Nuance\ShareScan5\Server\Tools\Database\" folder.3. Enter and execute the following command:
db_uninst.cmd
4. Verify that the following files no longer exist:
a. c:\Program Files\Microsoft SQL
Server\MSSQL10_50.MSSQLSERVER\MSSQL\DATA\eCopyShareScan.mdf
b. c:\Program Files\Microsoft SQL
Server\MSSQL10_50.MSSQLSERVER\MSSQL\DATA\eCopyShareScan_log.LDF
The script stops the ShareScan Manager and ShareScan Agent services and deletes the ShareScan
database. The result of the operation is logged into the file eCopyShareScan-Drop.log.
In order to create a new database:
1. Make sure that Admin Console is not running.2. Launch a command line window and go to the "C:\Program
Files\Nuance\ShareScan5\Server\Tools\Database\" folder.3. Enter and execute the following command:
db_inst.cmd
4. Verify that the following files are created:
a. c:\Program Files\Microsoft SQL
Server\MSSQL10_50.MSSQLSERVER\MSSQL\DATA\eCopyShareScan.mdf
b. c:\Program Files\Microsoft SQL
Server\MSSQL10_50.MSSQLSERVER\MSSQL\DATA\eCopyShareScan_log.LDF
-
5 SQL installs guide |13
The script creates a new, empty database and restarts the Agent and Manager services. The result of the
operation is logged into eCopyShareScan.log.
Here are some suggested links to install SQL Server
1. Download and install Windows Installer 4.5:
http://go.microsoft.com/fwlink/?LinkId=159623
2. Download and install .NET Framework 3.5 SP1:
http://go.microsoft.com/fwlink/?LinkId=159615
3. Download and install Windows PowerShell 1.0:
http://www.microsoft.com/windowsserver2003/technologies/management/powershell/downl
oad.mspx
4. Download SQL Server Express 2008 R2 from here:http://www.microsoft.com/express/Database/InstallOptions.aspx
-
5.0 SQL installs guide |14
5. Select New installation or add features to an existing installation
6. On the License Terms page select I accept the license terms and click Next
-
5.0 SQL installs guide |15
7. On the Setup Support Rules page make sure that all tests pass and click Next:
-
5.0 SQL installs guide |16
8. On the Feature Selection page select Database Engine Services, Management Tools - Basic andclick Next.
-
5.0 SQL installs guide |17
9. On the Instance Configuration Page choose Default Instance, and click Next.
IMPORTANT FACT: If you choose the “Named instance” option here, (for example, because you
already have a default installation of the SQL Server) then you’ll need to use that instance name
later on when specifying the database server for ShareScan. (Instead of the pure server name,
you’ll need to use Servername\Instancename).
-
5.0 SQL installs guide |18
10. On the Server Configuration page choose NT_AUTHORITY\NETWORK SERVICE for the SQL ServerDatabase Engine account and select Automatic for the SQL Server Browser Startup Type andclick Next.
-
5.0 SQL installs guide |19
11. On the Database Engine Configuration page select Mixed Mode and provide a password for the'sa' account. Remember the password, you will need it later.
IMPORTANT FACT: Mixed needs to be specified for the authentication mode.
-
5.0 SQL installs guide |20
12. On the Error Reporting Page click Next
-
5.0 SQL installs guide |21
13. Complete page make sure that the installation was successful and click Close
-
5.0 SQL installs guide |22
Verifying SQL Server installation:1. Launch SQL Server Management Studio
2. On the Connect to Server dialog change the Authentication to SQL Server Authentication, enter
sa in the Login field and provide the password for the sa account you have chosen during the
installation (in step #11) and click Connect.
-
5.0 SQL installs guide |23
3. Click New Query on the toolbar
4. In the new query window enter select @@version and click the Execute button. You should
receive the version of the SQL Server as a result
-
5 SQL installs guide |24
5. Expand the Databases node in the Object Explorer and make sure that there is no
eCopyShareScan database listed
6. Exit Database Management Studio
-
5.0 SQL installs guide |25
Verifying ShareScan database installation:1. Launch Database Management Studio and login with the sa account
2. Expand the Databases node in the Object Explorer and verify that the eCopyShareScan database
exists and the database contains tables
-
5.0 SQL installs guide |26
3. Expand the Security node in the Object Explorer and verify that both eCopy and
eCopyAddressBookAdmin logins exist
4 Click New Query on the toolbar
5 In the new query window enter the following commands:
DECLARE @HWFP nvarchar(100)
EXECUTE [eCopyShareScan].[ShareScan].[GetHWFP] @HWFP OUTPUT
PRINT @HWFP
-
5.0 SQL installs guide |27
6 Click the Execute button. In case of a successful command execution, you should see a 12-
character long identifier (containing hexadecimal characters) in the output window.
7 Exit Database Management Studio
8 Launch Admin Console
-
8.0 SQL installs guide |28
Troubleshooting SQL connection issues
The following message appears when opening the ShareScan Administration Console.
Due to this Database error, all options in Manager are disabled:
-
5.0 SQL installs guide |29
Open the Database in SQL Server Management Studio, it shows that the Tables for eCopyShareScan
Database did not get created:
-
5.0 SQL installs guide |30
Browse to "C:\Program Files\Nuance\ShareScan5\Server\Tools\Database"
Open the eCopyShareScan.log file
-
5.0 SQL installs guide |31
Changed database context to 'master'.Creating eCopyShareScan...DBCC execution completed. If DBCC printed error messages, contact your system administrator.Changed database context to 'eCopyShareScan'.Creating eCopyAddressbookAdmin...Creating ...Creating ShareScan...Creating eCopy...Creating ...Creating symKeyLicenses...Creating ShareScanCLRHelpers...Msg 5847, Level 16, State 88, Server BP-VM-server\SQLEXPRESS, Line 1Execution of .NET Framework code is disabled. Set "clr enabled" configuration option and restart theserver.
In order to successfully deploy the Tables, we need to set the CLR option enabled, running thefollowing query in SLQ Server Management Studio:
GOsp_configure 'show advanced options', 1;GORECONFIGURE;GOsp_configure 'clr enabled', 1;GORECONFIGURE;GO
-
5.0 SQL installs guide |32
You should see the following after running these commands:
-
5.0 SQL installs guide |33
Once done, please delete the partially created eCopyShareScan Database
You can delete the eCopy Database table by using the SQL Server Management Studio, or use can
use the db_uninst.cmd script (for example, if no MGMT Studio is installed) – they are
equivalent. If you delete the database with either method, it is NOT required to delete the MDF /
LDF files, because it will be deleted by the database delete operation.
IMPORTANT FACT: if the DB is not deleted, the next attempt to deploy it will fail it is NOT
recommended to delete the MDF / LDF files ONLY, if the DB has not been deleted
previously with any of the above methods, as it will result in an error in SQL Server.
However, if you’d have some corrupt state when the database would not exist in the SQL
Management Studio at all, but the MDF / LDF files would be there, then you should delete
the MDF / LDF files manually, but only in this special case.
-
5.0 SQL installs guide |34
-
5.0 SQL installs guide |35
Go to Services: restart the SQL Server service for this instance
Navigate to C:\Program Files (x86)\Nuance\ShareScan5\Server\Tools\Database\ Open a command line and run the Database Installer tool with the following parameters:
db_inst [SQL Server name] [SA account] [SA password]
Example: C:\Program Files (x86)\Nuance\ShareScan5\Server\Tools\Database>db_inst BP-VM-
W2K8X64R2\SQLEXPRESS sa P@ssword
You should see the following:
Stopping services...
The ShareScan Manager v: 5.0 service is stopping.
The ShareScan Manager v: 5.0 service was stopped successfully.
The ShareScan Agent v: 5.0 service is stopping.
The ShareScan Agent v: 5.0 service was stopped successfully.
Installing ShareScan 5.0 Database...
Server
eCopyshareScan
Done
Starting services...
The ShareScan Agent v: 5.0 service is starting.
The ShareScan Agent v: 5.0 service was started successfully.
The ShareScan Manager v: 5.0 service is starting.
The ShareScan Manager v: 5.0 service was started successfully.
Note: if any or both of the services (Agent or Manager) are stopped when running these scripts,
there may be error messages saying that the stopping of the service was unsuccessful – this
-
5.0 SQL installs guide |36
Errors can be ignored, as these will not have any effect for the outcome of the operations
performed by the scripts.
The Management Studio should now show the created Tables:
The ShareScan Manager will be able to launch without issue.
-
5.0 SQL installs guide |37
Tracing:The following trace files get created where the SQL scripts are run.
eCopyShareScan.logShareScanServer.log