TeamMate+

TeamMate+ Audit, TeamMate+ Controls, and TeamMate+ Public Sector

TeamMate Operational Utility

Last Updated: June 27, 2022

Table of Contents
Overview 3
Logging In 5
Routing Administration 6
Routing Database Configuration 12
Federated Security 14
Diagnostic Tools 15
Configuration Verification 19
Move Database 23
Global Database Converter 28
Ongoing Maintenance 34
Document Updates 35

ii
 Overview
This document applies to TeamMate+ Audit, TeamMate+ Controls, TeamMate+ Public Sector
and are herein referred to as TeamMate+.
This document covers the TeamMate Operational Utility, which provides tools to facilitate the
management of TeamMate+ Multitenancy, Federated Security, and the Global Database
Converter for on-premises (On-Prem) installations only. The functional areas that are currently
supported are:
l Realm database discovery
l Routing database population
l Routing database administration
l Diagnostic and troubleshooting tools to verify correct configuration
l Background service status

WARNING: This utility should ONLY be used with caution by a small,

trained, and trusted set of individuals within an organization, since misuse
can adversely impact the proper functioning of TeamMate+. Be sure to
create database backups regularly and before deleting Realm database(s)
as the underlying database(s) will be deleted.

Routing
A realm is a synonym for a tenant, which is comprised of the online transaction processing
(OLTP) DB and reporting DB for that realm. Each realm has a unique name.
The realm name may contain letters, numbers, and hyphens. Spaces or dots are not
supported. The name needs to be valid as an Internet host subdomain name. Realm names
are not case-sensitive.
TeamMate supports multitenancy through its routing engine, which resolves a realm name to
its corresponding realm databases and ensures that each realm is separate, independent, and
cannot be accessed from other realms. In TeamMate data centers, multitenancy is the norm,
and each realm belongs to a specific organization. On-premises TeamMate deployments are
typically single-tenant but multitenancy may be appropriate in some scenarios.

NOTE: The TeamMate Operational Utility supports up to 3 realms without

the installation of the TeamMate Operational Utility License Key. This
configuration will be referred to as a small multitenant configuration. If the
license key is installed, unlimited realm creation is allowed, and this will be
referred to as a large multitenant configuration.

Routing Database Setup

Multitenancy requires a routing database that serves as a directory for all realms. By
convention, the database should be named Routing and utilizes a standard TeamMate OLTP
Schema. Use TeamMateNG.TmDbAdmin.exe to create this database.
Since the routing database is critical to the operation of the entire multitenant environment, it
needs to be extremely robust. This means that for production environments, it should ideally be

TeamMate Operational Utility 3

 run on a clustered SQL Server, be backed up regularly, and procedures for maintaining and
restoring this database need to be in place to reduce recovery time in the event of a failure.

NOTE: The system realm in a large multitenant configuration is a special

realm and must point to the routing database. The only users that should
exist in this database are the operations staff who will administer the
multitenant environment. Hosted TeamMate+ organizations cannot access
the system realm (they can only access their own realm).

NOTE: In a small multitenant configuration, the system realm can be used

as a regular realm database in addition to the routing database. It is
possible to add an alias to the configuration to allow the realm to be
identified as something other than system for client usage.

There may be multiple separate environments, each with their own routing database. Routing
databases for different environments (e.g. DEV, QA, PROD) can be on different servers;
however, if they are on the same server, suffix each database name to clarify the environment
to which they belong.
At present, it is unnecessary to create a routing report database.

TeamMate Operational Utility 4

 Logging In
To log into the TeamMate Operational Utility
1. Launch TeamMate.Operational.Utility.exe.
2. Specify the information for your environment and login by clicking OK.

IMPORTANT: You must login to the system Realm to perform any

administration.

Example: Login for the TeamMate Operational Utility.

3. (Optional) If you need to login as a different user for any reason, choose File | Login As
from the menu, specify the requisite information, and click OK. You will be logged out of
your current session and commence a new session with the new credentials.
4. Claims are key/value pairs that are gathered when you login and are used throughout
your session. You may view the claims for the currently logged in user or other users by
selecting File | Claims from the menu. This can be helpful for diagnosing issues.
5. To close the application, select File | Exit.

TeamMate Operational Utility 5

 Routing Administration
There are a variety of tools in this utility that allow for administration of the Routing database.
Most of the routing tools display a list of items and their details in a grid.

To manage the routing database

1. Click on any row to select an item.
2. Click on any of the buttons at the to perform an operation (Add, Update, Delete) on that
item.

NOTE: Double-clicking on an item is the same as clicking on the Update

button.

3. (Optional) Sort the data in ascending or descending order by clicking on any column
heading.
4. (Optional) Filter the data by typing in the filter text box.

NOTE: The count text box displays the number of items and the number of
matches.

Realms
Select Routing | Realms from the menu to display the Realm Add tool. This tool lists the
realms and contains the following key options:
l Dedicated Routing Database checkbox: Indicates whether the routing database is
exclusively used for routing purposes (dedicated) or if it has business data in it (shared).
Multitenant environments should have a dedicated routing database, whereas single-ten-
ant environments should have a shared routing/realm database. The TeamMate Worker
Service, which performs background processing for each realm (such as sending out
notifications), will skip the system realm (which is the routing database in a multitenant
environment). A warning icon appears next to this checkbox if it is configured differently
than expected.
l Details checkbox: Gathers additional details about each realm and display that inform-
ation in the grid, if checked.
l Realm Add tool: Allows you to create new or link to existing OLTP, Report, or Archive
databases and populate the corresponding routing information. You may specify altern-
ate data and log directories for the database files. The champion password may be over-
ridden from its default. To link to an existing database, choose a Database Server and
the existing Database Names will be listed.
l Realm Update tool: Provides functionality to administer the various aspects of Realms,
including supporting aspects such as Realm Databases, Realm Database Associations,
and Realm Aliases.

Add Realm
When adding a realm, specify the required information including:

TeamMate Operational Utility 6

 l Name
l OLTP
o Database Server
o Database Name
o Recovery model (most recently used setting is automatically selected)
l Report
o Database Server
o Database Name
o Recovery model (most recently used setting is automatically selected)
o Create ETL Job (check this box to create the ETL job for this realm)
n Add ETL Job Schedule(s) for when the ETL job should run.

Example: Add Realm

Example: New ETL Job Schedule

TeamMate Operational Utility 7

 Realm Databases
Select Routing | Realm Databases from the menu to display the Realm Databases tool. This
tool lists the realms and their corresponding OLTP, Report, and Archive database names, as
well as the servers they are on.

Realm Database Associations

Select Routing | Realm Database Associations from the menu to display the Realm
Database Associations tool. This tool lists the relationships between OLTP, report, and
archive databases.

Realm Aliases
Select Routing | Realm Aliases from the menu to display the Realm Aliases tool. This tool
lists the realm aliases and their corresponding realms.
Realm aliases are useful to map DNS subdomain names to realm names since the subdomain
names are captured from the host in the URL and may differ from the underlying realm name.
For example, gizmo = gamma.

Database Servers
Select Routing | Database Servers from the menu to display the Database Servers tool
available only in large multitenant configurations. This tool lists the database servers in the
environment. Defining the database servers in the environment is a prerequisite to other tools
in this utility. For example, the Routing Population tool discovers realm databases on the
servers in this list.

Example: TeamMate Operational Utility for Database Servers.

TeamMate Operational Utility 8

 To view and modify the properties
1. Click Add, select an item, and click Update. The Database Server Update dialog dis-
plays.

Example: Database Server Update dialog.

2. Specify the machine name, IP address, or instance name.

3. If SQL Server is configured to use a nonstandard port (not the default port 1433), spe-
cify that port, otherwise, leave the port field blank.
4. Click Normalize to update the Name field with the physical name. Normalizing data-
base server names is a best practice.
5. Click Test to verify that there is connectivity to that database server.

Web Servers
Select Routing | Web Servers from the menu to display the Web Servers tool. This tool lists
the web servers in the environment. If there is only one web server, then it is not necessary to
specify it; however, if there are multiple web servers, then each of them needs to be listed for
the configuration engine to work correctly.

Example: TeamMate Operational Utility for Web Servers.

TeamMate Operational Utility 9

 To view and modify the properties
1. Click Add or select an item, and then click the Update button. The Web Server Update
dialog displays.

Example: Web Server Update dialog.

2. Click Test to verify that the web server is running and accessible.

Routing Population
Select Routing | Routing Population from the menu to display the Routing Population tool
available only in large multitenant configurations. This tool allows you to discover existing
realm databases on the list of Database Servers and add their information into the routing
database, if not already there.
See "Discover Existing Realm Databases" on page 12 for more information.

Export Routing Information

Select Routing | Export Routing Information from the menu to display the Export Routing
Information tool available only in large multitenant configurations. This tool generates a SQL
script that removes the existing routing information and then populates the routing information
based on the current routing database. This can be useful for backing up and restoring the
current routing information, transferring the routing information to a different routing database,
etc.

Example: TeamMate Operational Utility for Export Routing Information.

TeamMate Operational Utility 10

 To export the routing information
1. Specify the path for the filename of the SQL script file.
2. Click Export. The file is created and the SQL script displays in the output window.
3. Optional. Copy the Output window to the clipboard to paste into another tool like SQL
Server Management Studio (SSMS).
4. Optional. Clear the output window.

To populate a database with the routing information

1. Launch SSMS.
2. Create a new query for the TeamMate+ routing database you want to populate.
3. Open the SQL script file you created in Step 2 from the To export the routing inform-
ation procedure,
-OR-
Paste the SQL script you copied in Step 3 from the To export the routing information
procedure.
4. Click Execute.

ETL Job Settings

Select Routing | ETL Job Settings from the menu to display the ETL Job Settings tool. This
tool allows you to specify the ETL job information to be used when adding a new realm. This
tool is also available from the Add Realm tool. The most recently saved ETL Job Settings are
used for subsequent ETL operations.

Example: ETL Job Settings

TeamMate Operational Utility 11

 Routing Database Configuration
Discover Existing Realm Databases
The Routing Population tool (available only in large multitenant configurations) analyzes the
databases on the realm database servers, correlates that to the existing information in the
routing database, and populates the routing database with any missing information. The tool
matches routing information between the realm database server and the routing database. If
match is found, that item is skipped (not updated). If no match is found, that item is added to
the routing database.
Ensure server or database names are correct prior to running the tool, as any subsequent
changes to those values will need to be done manually. The tool is designed for multiple
operations and may be run to perform an initial population, and subsequently each time a new
realm is added.

To discover existing realm databases

1. Select Routing | Database Servers from the menu. Add or modify the list so that all
database servers in your environment that have realm databases on them are defined.
2. Select Routing | Routing Population from the menu.

Example: TeamMate Operational Utility for Routing Population.

3. If the standard naming conventions have been followed, the default values of the LIKE
and Suffix fields are correct. The Optional OLTP database Suffix, if specified, is
excluded from the base OLTP database name that is used to correlate with its cor-
responding report and archive databases.

NOTE: You may specify multiple suffixes for report and archive DBs by
delimiting them with a vertical bar (|).

4. The Skip non-CM checkbox should typically be left checked.

TeamMate Operational Utility 12

 IMPORTANT: Ensure that any new databases are licensed. If not, any
unlicensed database will be rejected as “non-CM” database with this box
checked.

NOTE: The realm database server may contain other databases that are
not TeamMate+ databases. The tool will perform minimal schema checks to
identify such databases and skip them from processing.

5. Once you are ready to proceed, click Find Realms. This searches all databases that
match the criteria specified on each defined database server. It then associates OLTP,
report, and archive databases together for each realm, analyzes if routing information is
missing, and displays these realms in a grid.
6. Indicate the realms for which you would like to populate the routing information by
pressing Ctrl+ click, Shift+ click, or click and drag to make your selections.
7. Click Populate Realms. This populates routing information for the selected realms.
8. Once you are ready to proceed, click Find Realms. This searches all databases that
match the criteria specified on each defined database server. It then associates OLTP,
report, and archive databases together for each realm, analyzes if routing information is
missing, and displays these realms in a grid.

NOTE: If duplicate database GUIDs are detected, Routing Population will

not process those realms. Correct the duplications using the Duplicate
Database GUID tool and rerun the tool.

9. Use the splitter to adjust the amount of space for the grid compared to the output win-
dow.

Specify Correct Realm Names

Routing Database Population generates realm names in the format
<servername>.<databasename>, but these need to be changed to valid realm names.

IMPORTANT: Carefully review that the databases match properly and

update their realm names accordingly.

To specify realm names

1. Select Routing | Realms from the menu. The list of realms in the routing database dis-
play.
2. Select a row to modify, and then click Update.

TeamMate Operational Utility 13

 Example: Realm Update screen.

3. Modify the Name to the organization name, then click OK. The description is optional. If
you want to disable this realm, uncheck the Active checkbox. Disabling a realm will
make it inaccessible for users of that realm to login to TM+.
4. Repeat this process until all realms have a valid name representing the organization.

IMPORTANT: Correlate the correct realm name to the correct

corresponding databases.

Federated Security
To configure Federated Security for on-premises installations, refer to the Federated Security:
On-Prem: https://tmplus.teammatedocs.com/fedsec-onprem/TMPlus_OnPrem_Federated-
Security.pdf

TeamMate Operational Utility 14

 Diagnostic Tools
The following diagnostic tools are provided to detect problems and show useful information
about the environment and its health.

Wrong Database GUID

It is critical that realm databases are only accessed by users of that realm. The expectation is
that each database has a unique GUID. The Wrong Database GUID tool verifies that the
database GUID for the realm database that is stored in the routing database matches the
database GUID in the realm’s OLTP database when making routing decisions. This check is a
safeguard against misconfiguration as well as cross-realm access.

To check for wrong database GUIDs

1. Select Troubleshooting | Wrong Database GUID from the menu.
The tool displays and automatically checks for any database GUIDs in the routing
information of the routing database that do not match the database GUID in the
corresponding Realm database.

Example: TeamMate Operational Utility for Wrong Database GUID.

2. Click Find Duplicates to refresh the list. This displays a grid of databases with their
Realm, DatabaseServer, DatabaseName, Routing GUID, and Realm GUID.
3. Select one or more rows at a time, and then click Fix GUIDs.
4. Each selected mismatch will be resolved by taking the GUID in the TM_Setting table in
the realm database and updating the NG_RealmDatabase table in the routing data-
base.
5. The grid will automatically refresh to show any remaining wrong database GUIDs.

TeamMate Operational Utility 15

 Duplicate Database GUID
The effectiveness of the database GUID check described in the preceding section would be
reduced by the presence of any duplicate database GUIDs. When new databases are created,
they are assigned a unique GUID; however, it is possible for duplicate database GUIDs to be
introduced into an environment. When existing databases are backed up and then restored as
a different database (when migrating a database from one environment to another), duplicate
database GUIDs may occur. The Duplicate Database GUID tool can detect and correct
duplicate database GUIDs.

To correct any duplicate database GUIDs

NOTE: If a database GUID is changed, its TeamMate license is invalidated,

and it must be relicensed, which this tool will facilitate in that relicensing.

1. Select Troubleshooting | Duplicate Database GUID from the menu. The tool displays
and automatically checks for duplicates.

Example: TeamMate Operational Utility for Duplicate Database GUID.

2. Click Find Duplicates to refresh the list. This displays a grid of databases with their
DatabaseGUID, DatabaseServer, DatabaseName, RealmName, and DatabaseType.
3. Before you can change a database GUID, the GUID must be added to a realm. If the
RealmName column of the database you want to change is blank, then select Routing |
Realm and either:
Create a new realm with this database in it.
-OR-
Add the database to an existing realm.
See "Realms" on page 6 for more information.
4. Once the database has a RealmName, select it and click Fix Duplicate.

TeamMate Operational Utility 16

 l If you are changing the database GUID of a report or archive database, then the out-
put window reports that the database GUID was changed, and you are done.
l If it is an OLTP database, then you need to relicense the database using the Unli-
censed Realms tool, in the next section.
5. Repeat this process until you have eliminated all duplicate database GUIDs in your
environment.

Unlicensed Realms
Each realm needs to be licensed for features to be available to users. Any unlicensed realms
display with this tool, which is accessed from Troubleshooting | Unlicensed Realms. You can
refresh the list by clicking Find Unlicensed.
Realms that have never been licensed and realms that do not have valid licenses can be
resolved with this tool.

Example: TeamMate Operational Utility for Unlicensed Realms.

To license an unlicensed realm

1. Select a row.
2. Click Generate Request to populate the License Request Data text box.
3. Click Copy Request to copy it to the clipboard.
4. Forward the request to Wolters Kluwer.
5. Wolters Kluwer will generate a license key and send it back to you.
6. Paste the response in the License Key textbox.
7. Click Apply License.
8. Repeat this process until you have eliminated all unlicensed realms in your envir-
onment.

TeamMate Operational Utility 17

 Routing Verification
The Routing Verification tool displays information in the routing database and immediate
indication of any misconfiguration by listing each realm, each database in that realm, and
critical information about each database by highlighting problems in red.
For example, if there are any discrepancies between the database GUID for a realm in the
routing database vs. the actual database GUID in the Realm database, this is invalid. This
issue can be resolved using the Wrong Database GUID tool. Also, routing to each realm
database is verified, and if any realm database is inaccessible via resolving the routing
information and attempting to connect to it, that is also invalid and displays in red.
Ultimately, the goal is to use this tool to quickly access pertinent information about each realm
database and to address any issue it detects so that no item is shown in red.

To verify routing
1. Choose Troubleshooting | Routing Verification from the menu. The Routing Veri-
fication window displays the realm databases matching the filter criteria.

Example: TeamMate Operational Utility for Routing Verification.

2. Click Refresh, as necessary. The output shows the filter criteria and the matching
realm databases along with all their details.
3. You can change the filter values for database Type, Version, and Active status.

TeamMate Operational Utility 18

 Configuration Verification
Web server configuration is per machine. When there are multiple web servers in the
environment running in a web farm, it is crucial that each of them is configured verbatim. The
Configuration Verification tool provides visibility into the settings across each web server so
that any discrepancies can be identified and resolved.
This tool also provides the ability to reset the configuration cache on the web servers, as well
as analyze and report on any differences in the configuration cache across web servers. These
operations may be done for all realms or a subset of realms.

To verify configuration
1. Select Troubleshooting | Configuration Verification from the menu.
2. Click Display All and review the information. The active configuration values are
cached in each web site and are interrogated constantly.
3. If you need to change a configuration value in web.config, click Reset All. Each web-
site flushes its cached values. They can then be reloaded on demand to obtain and use
the latest values.

Example: TeamMate Operational Utility for Configuration Verification.

4. (Optional) You may Copy and paste the result into Excel for further analysis.

TeamMate Operational Utility 19

 Environment Verification
The Environment Verification tool analyzes the TeamMate configuration and its database
connections to ensure the most important settings are consistent and correct.
The report has the following color indications:
l Red: Problems that need resolving.
l Blue: Informational and should be considered, but do not necessarily represent a prob-
lem.
l Green: Indicates no errors found.
Review the report in the output text box to understand the details of the errors.
There is a triage that occurs in the following order for any configuration values. The first
location where a particular configuration value is found takes precedence:
l Registry: Common on development machines, used in some cases on build servers,
should typically be avoided on QA and PROD servers.
l Realm database: The TeamMate | Setup | Settings page allows for Realm values to be
specified. These are stored in the Realm database in the TM_Setting table in each OLTP
database.
l settings.config: Key value pairs in appSettings section.
l web.config/app.config: Key value pairs in appSettings section.

NOTE: Administrative privileges are required for this tool to run properly.
For example, if you get an error that a path does not exist, which you know
to exist, check that you have logged into Windows with an account with
administrative privileges and then check the tool again.

NOTE: Since there is a precedence order in the configuration settings, the

Effective column on the right indicates the actual settings that are used by
the application.

To analyze the TeamMate configuration using the Environment Verification tool

1. Choose Troubleshooting | Environment Verification from the menu.

TeamMate Operational Utility 20

 Example: TeamMate Operational Utility for Environment Verification.

2. Specify the UNC path to the root folder of the TeamMate website. Even if you are run-
ning this tool locally, specify the UNC path (i.e. instead of C:\, use \\machine\c$).
3. Click Analyze. This may take up to a minute or so to run.
l Green: Indicates no problems were found.
l Red: Review the output to understand the details of the errors that were detected.
4. Resolve the problems and re-run the tool until all results are successful with no errors
detected.

Active Realms
The Active Realms tool allows you to specify filter criteria and display realms that match the
criteria.
TeamMate+ performs background processing that relies on information in the routing
database. For example, the notifications service requests the list of active realms from the
routing database and then loops through each realm database to send out scheduled and
reminder emails. The routing engine verifies that it can connect to each realm database and
that the GUID in the routing database and the realm database matches. The realms in the
routing database should be the same version. The version defaults to the current code version
and is passed onto the request. The list of active realms that return only match that version.

To verify active realms using the Active Realms tool

1. Choose Troubleshooting | Active Realms from the menu. The realms matching the cur-
rent version of the utility for all database types display.

TeamMate Operational Utility 21

 Example: TeamMate Operational Utility for Active Realms.

2. Click Refresh, if needed. The output displays the filter criteria and the matching realm
databases along with their Version, database Type, and database Name.
3. You can change filter values for database Type and Version. By default, most back-
ground services perform processing on the active current version OLTP Realms.

Service Status
Select Troubleshooting | Service Status to view the status of the TeamMate background
services. The Service Status tool displays services running on machines, whether they are
currently running or not, and when the last heartbeat occurred.

TeamMate Operational Utility 22

 Move Database
The Move Database tool provides the ability to move a DB between different DB servers within
a data center. It is not intended to be used across data centers nor across routing DBs. It
utilizes backup/restore to move DBs between servers, and in addition to moving the DBs, it
updates routing info and will create or recreate the ETL job for the affected realm.
This tool is useful if there is a restructuring in the server environment that necessitates moving
DBs to different servers. If the OLTP and Reporting DBs are commingled on the same server,
and that server encounters performance issues during processing of reporting operations (for
example, running ETL jobs, running reports or dashboards, or handling reporting API
requests), which impact interactive TeamMate+ users, the typical resolution is to upsize the DB
server so it has sufficient capacity to handle both OLTP and Reporting loads simultaneously.
Upsizing is the generally recommended resolution for single-tenant and on-prem
environments. In a large multitenant environment (i.e. dozens or hundreds of tenants), an
alternative is to use the Move Database tool to offload reporting onto a different database
server so that the OLTP DB server is not burdened by reporting operations.

NOTE: A TeamMate Operational Utility License Key is required to use the

Move Database tool.

Example: Move Database tool.

This tool contains the following items broken down by area on the screen:

TeamMate Operational Utility 23

 l Database server and backup configuration:
o Database Server: Choose the target DB server from the drop-down list where you
want to move the selected DB(s) to. If you do not see a DB server you expect to be in
the list, use the Database Servers tool to add it and then return to the Move Database
tool.
o Backup File Location: Specify the path where .BAK files used during the Move Data-
base operation will be temporarily stored. This path must be accessible from both the
OLTP and Report DB servers (if they are different) and from the machine the Oper-
ational Utility is running on. Furthermore, read and write permissions must be granted
such that the OLTP DB SQL Server instance can perform the backup, the Reporting
DB SQL Server instance can perform the restore, and the Operational Utility can
delete the .BAK file when the Move Database operation is completed. It is strongly
recommended to specify a UNC path if the OLTP and Report DB servers are dif-
ferent, but alternatively, the same drive letter could be mapped on both DB servers to
this file location.
l ETL Job Creation: When an OLTP or Reporting DB is moved, the Move Database oper-
ation needs to update the routing information and recreate the ETL job with the correct
information. ETL jobs can either use SQL Server or Windows Authentication, and each
requires different information to be specified in order to create the ETL job:
o SQL Authentication:

Example: Move Database tool: ETL Job Creation area for SQL Authentication.

n OLTP Username: Specify the OLTP DB login. It is the SQL user with permissions
over the OLTP database. It can be a sysadmin or a non-sysadmin user.
n OLTP Password: Specify the OLTP DB password.
n Report Username: Specify the Reporting DB login. Leave blank if same as OLTP
Username. It is the SQL user with permissions over the Reporting database. It can
be a sysadmin or a non-sysadmin user. This can be leave as blank if the user is
the same as the OLTP database.
n Report Password: The password for the Report database user. Leave blank if
same as OLTP Password.
n Job Owner: Specify the login for the job owner. This should typically be “sa” or
another sysadmin. It is the user with sysadmin role for the Reporting database,
and who will be the owner of the ETL job.
n SSIS Location: Specify the folder where the TeamMate SSIS files are located.
The Reporting DB SQL Server instance needs to be granted read permissions to

TeamMate Operational Utility 24

 this folder. You can copy these from the Bin folder in the TeamMate+ installation
or TeamMate+ tools installation.
o Windows Authentication:

Example: Move Database tool: ETL Job Creation area for Windows Authentication.

n Username: Specify the Windows account name (Domain\Login) to be linked to

SQL credential which will be linked to the SSIS proxy.
n Password: Specify the Windows account password.
n SSIS Proxy Name: Specify the SSIS proxy name.
n SSIS Location: Specify the folder where the TeamMate SSIS files are located.
The Reporting DB SQL Server instance needs to be granted read permissions to
this folder. You can copy these from the Bin folder in the TeamMate+ installation
or TeamMate+ tools installation.
l Move: Click this button to start the Move Database operation. It will move each DB
whose checkbox was checked in the Grid to the target DB server. The progress of each
move operation will be output in the logging area along with any errors.
l Cancel: Click this button to cancel the current and any remaining Move Database oper-
ations. Any Move Database operations that have already been completed will not be can-
celed.
l Grid:
o Refresh: Click this button to refresh the grid with the latest information in the Routing
DB.
o Count: Displays the total number of DBs in the Routing DB.
o Selected Row Count: Displays the total number of DBs that have been selected to be
moved.
o Grid: Shows the list of DBs in the Routing DB. Check the checkbox on each row that
you would like to move to the target DB server. Ineligible DBs will be disabled. The
system Realm DB cannot be moved, nor can DBs which are unavailable because
they cannot be connected to, nor can DBs that are already on the target DB server.
l Logging: Provides feedback of the operation state, focusing on failures. All log events
are stored in the Routing DB in the UTIL_DBMoveLog table.

Example: Logging area of the Move Database tool.

TeamMate Operational Utility 25

 o Expand Log List: Select to increase the size of the log window for easier viewing.
o Copy: Click to copy the displayed log text to the clipboard.
o Clear: Click to clear the log window.
o Date Calendar: Use in coordination with the CSV export to determine the beginning
date of the exported log data. Future Dates cannot be selected.
o Auto-Open: Use in coordination with the CSV export, which will automatically open
the saved CSV file. If Excel is installed on the system, then this launches Excel.
o CSV Export: Click to save the exported log data.
l Progress: Displays a progress bar and Total Elapsed time.

Using the Move Database tool

To use the Move Database tool

1. Select Database | Move Database.
2. Choose the target DB server from the drop-down list where you want to move the selec-
ted DB(s) to. Select any checkbox for a DB row that you want to move to the target DB
server.

NOTE: When the server is selected, the grid is refreshed leaving all the
databases to be moved available to be selected with a checkbox and all the
databases that cannot be moved to that server are greyed out and disabled.

3. Specify the Backup File Location.

4. Specify the required fields in the ETL Job Creation area.
5. Click Move. The Move Database operation begins.
6. If you need to stop the Move Database operation before it completes, click Cancel.
7. Once the Move Database operation completes, the grid will be updated to reflect the
result.
8. Review the logging information and take necessary actions as needed to troubleshoot
and resolve problems.

Caveats

WARNING: The Move Database operation must only be performed off-

hours. It is complex, involves numerous steps, and is resource intensive.
For data integrity, it closes all other DB connections and temporarily
restricts access to the DB being moved, so TM users will encounter errors if
they attempt to work while the Move Database operation is running.

Estimating how long the Move Database operation will take to run is difficult and will vary
widely because it is dependent on DB size, hardware performance (RAM, CPU, I/O, storage
subsystem, etc.), and network bandwidth. Internal testing of various sizes of OLTP and Report
DBs with mainstream hardware suggest that you may estimate between 30-60 seconds per
GB for the size of the DB being moved. For example, moving a 10 GB DB may take between 5-
10 minutes, but again, the actual time will vary based on your environment.

TeamMate Operational Utility 26

 The Move Database Operation performs a variety of verification checks before processing and
also checks for problems during processing. Under normal circumstances, the Move Database
operation either successfully completes, or if there is a problem, it will log the problem and
revert the environment back to its original state.
Under rare circumstances, such as forcibly terminating the Operational Utility process during
the Move Database operation or a fatal error being encountered, it is possible that:
l the backup file is not cleaned up,
l the ETL job is not created,
l the routing information is not properly updated, or
l the DB being moved is left in a single-user or read-only state.
These rare outcomes may be resolved manually through the File Explorer, SSMS, or the
Operational Utility. If the DB being moved is left in a single-user or read-only state, it can be
resolved by opening SSMS and executing the following query in the master DB (replace
<DatabaseName> as appropriate for your environment first):
ALTER DATABASE [<DatabaseName>] SET READ_WRITE WITH NO_WAIT;
ALTER DATABASE [<DatabaseName>] SET MULTI_USER;

TeamMate Operational Utility 27

 Global Database Converter
The Global Database Converter includes the Batch Global Database Upgrader to support
many databases for conversion at one time.

Example: Global Database Converter.

The converter contains the following items broken down by area on the screen:
l Routing Database information: This displays the routing database selected during
login.

Example: Routing Database information.

l Grid: This area includes selected and total Database counts.

TeamMate Operational Utility 28

 Example: Grid area.

l Select DB Pairs (OLTP & Report): Select to check the matching pair for the selected
database pairs.
l Load Routing DB: Click to query the Realm database for all Realms and their asso-
ciated databases.
l Conversion Operations: This is only enabled/available when at least one database is
checked.

Example: Conversion Operations area.

o CPU Utilization: Adjust the amount of CPU saturation across all CPUs on a given sys-
tem. The application automatically determines the number of CPUs and sets the
value to the maximum available.
n Concurrent: Select to convert the databases at the same time, up to the given
available CPUs.
n Sequential: Select to convert the databases one after the other.
n Clear: Click to reset any changes made to CPU Utilization. (This button applies to
both Conversion Options and Filters.)
n Convert: Click to start the conversion process.
n Cancel: Click to cancel all remaining selected (checked) databases not yet con-
verted.
l Filters:

Example: Filters area.

o Checked: Select to list databases that are checked to be converted. This is disabled
until at least one row has been checked.
o Converted: Select to list databases that have been converted successfully.
o Not Converted: Select to list databases that have not been converted, which includes
any that have previously failed.
o Failed: Select to list databases that have failed during a previous conversion.
o Type Realm: Enter any portion of a given realm name, then press Enter to limit the
list of databases matching the Realm name filter condition entered here.

TeamMate Operational Utility 29

 o Type DB Name: Enter any portion of a given database name, then press Enter to
limit the list of databases matching the Database name filter condition entered here.
o Clear: Clears any filter conditions set and returns the list to the state prior to the filter.
(This button applies to both Conversion Options and Filters.)
l Logging: Provides feedback of the operation state, focusing on failures. All log events
are either put in the Windows Application Event log or s SQL table, if available. Once a
database is converted to the most current version, the events are then logged in that
table in the selected Routing Database.

Example: Logging area.

o Expand Log List: Select to increase the size of the log window for easier viewing.
o Copy: Click to copy the displayed log text to the clipboard.
o Clear: Click to clear the log window.
o Date Calendar: Use in coordination with the CSV export to determine the beginning
date of the exported log data. Future Dates cannot be selected.
o Auto-Open: Use in coordination with the CSV export, which will automatically open
the saved CSV file. If Excel is installed on the system, then this launches Excel.
o CSV: Click to save the exported log data.

NOTE: When CSV controls are disabled, no SQL Log table is available.
Logs go to Windows Application Event.

Using the Global Database Converter

To use the Global Database Converter

1. Select Database | Global Database Converter.
2. Select the Load Routing DB to load grid data.

NOTE: When loading a Routing Database that has not been converted, only
the Load Routing DB button and the Routing option in the table are available
for selection.

TeamMate Operational Utility 30

 Example: Grid data after loading the routing database (Load Routing DB) before conversion.

To convert the database

1. Select the checkbox in the only available row. The Conversion Operations are avail-
able.
2. Click Convert to begin conversion.

Example: Conversion options after selecting the DB.

After a successful conversion, the screen refreshes and becomes locked/disabled. All
other databases are now unlocked/enabled to allow queuing of converting multiple
databases.

TeamMate Operational Utility 31

 Example: Refreshed view of the DB.

3. Select any checkbox for a database row. The selected database is placed in a queue to
be converted.
4. Click Convert. The batch conversion begins.

To filter databases
1. Select the desired filter option to limit the list of databases.
2. When finished, press Clear to return to the original non-filtered list, including addi-
tionally checked rows.

Examples

Example: Results with no data available.

Example: Results of using the Checked filter.

Example: Results of using the Converted filter.

TeamMate Operational Utility 32

 Example: Results of using the Not Converted filter.

NOTE: Failed is included, since it has not been converted. The Failed result
includes the day it failed and shows when re-loading the data from the
server using the Load Routing DB button.

Example: Results of selecting Failed filter.

Logging
Logging consists of writing to the Windows Application Event Log by default. Logs are
persisted in a SQL table for conversions history.

TeamMate Operational Utility 33

 Ongoing Maintenance
As new realms are added, follow the process outlined in this document to:
l Populate the routing database with the information for the new realm databases.
l Update the realm names as appropriate.
Run the diagnostic tools periodically to verify that there are no problems.

TeamMate Operational Utility 34

 Document Updates
This table lists the document updates by product release date:
Date Update
July 2022 Document updates:

l Added Add Realm section. See "Add Realm" on page 6 for more
information.
l Added ETL Job Settings section. See "ETL Job Settings" on
page 11 for more information.
April 2022 Document updates:

l Added Move Database section. See "Move Database" on page

23 for more information.
May 2021 Document updates:

l Removed Cognos content throughout the document.

March 2021 no document updates.
December 2020 Document updates:

l Added Export Routing Information section. See "Export Routing

Information" on page 10 for more information.
September 2020 Document updates:

l Routing section: Added support for up to 3 realms without install-

ation of the TeamMate Operational Utility License Key. See
Page 3 for more information.
l Routing Database Setup section: Added note for distinction of
large and small configurations. See Page 3 for more information.
l Routing Administration section: specified that the Database
Servers tool is available only in large multitenant configurations.
See Page 6 for more information.
l Routing Database Configuration section: specified that the
Routing Population tool is available only in large multitenant con-
figurations. See Page 12 for more information.
l Federated Security section: completely referenced in a sep-
arate document. See Page 14 for more information.

TeamMate Operational Utility 35