Who is this article for?

IT Administrators migrating the application to new servers.

No special access or permissions are required.

It can be necessary to move the back end to new servers, for example if moving to a new version of Windows server.

This article provides a checklist of steps to take and a worked example.

1. Preparation

1.1. Assumptions

This guide assumes:

• You have a working Internal Audit system (with or without Retain).
• You can use App Manager.
• You have admin access to your IIS server and permission to restore databases and add logins on SQL Server.
• The new application URL is different from the old one.
• Both new and old servers are in the same Windows domain.
• You are using the same application version.

1.2. Prerequisites

Before beginning the migration, ensure the following is in place:

• IIS and required modules are installed on the application server (as per the install guide).
• SQL Server is installed on the database server.
• Infrastructure updates are complete (URLs whitelisted, antivirus exceptions set).
• App Manager instances are set up and accessible.
• All users have checked in their data (no audits or documents are reserved).
• All client applications have been closed by users.

1.3. Process overview

To summarise, the process involves:

• gathering information about the current system.
• migrating the data and setting up an app instance in test.
• verifying the test system is working.
• reproducing the migration/install steps for the live system.

2. Gathering information

Before starting the migration, collect the following information from the existing system:

2.1. Service configuration

1. Open IIS Manager on the old application server
2. For each service (Service, FBA, Web Service, WebUI, and optional API and SamlMvc), check the advanced settings to identify which application pool is in use
3. Navigate to Application Pools and check the identity for each app pool in use
4. Record the service account usernames (e.g., domain\PentanaService)

2.2. Robot service configuration

1. Open Services (services.msc)
2. Locate the Pentana Robot service
3. Note the "Log On As" account being used

2.3. Database connection

1. Launch App Manager Config tab, select the Service tab
2. Check the service configuration to verify the connection string
3. Note whether integrated security or a SQL Server account is being used

2.4. Authentication method

If you don’t already know the authentication methods used by the desktop client and WebUI, you can check using these steps:

2.4.1. Desktop client

1. In the App Manager Config tab, select the Client tab.
2. Check the configSections area
3. If Pentana.TNG.ServiceInspectors section is not present: Windows authentication is in use
4. If Pentana.TNG.ServiceInspectors section is present: Check for the forgot password link section key
   • If not active: Single Sign-On via SAML is in use
   • If active: FBA is in use

2.4.2. WebUI

1. Open the WebUI configuration file
2. Look for the pentana.TNG.UI.Web.FBA section
3. Check if useSSO is commented out or active
   • If commented out: FBA is in use
   • If active: Single Sign-On via SAML is in use
   • If FBA section is missing entirely: Windows authentication is in use

2.5. File attachments storage

File attachments are almost always stored in the database, but check:

1. In the App Manager Config tab, select the Service tab.
2. Look for the file storage path section Pentana.Tng.UI.FileService
3. Normally the PhysicalPath key is commented out, and this means that all of the file data is held in the database.
4. If the PhysicalPath key is in use and has a UNC path specified, then the attachments are stored at that path and may need migrating too.

2.6. Mail server settings

1. In the App Manager Config tab, select the Service tab.
2. Record mail server settings from the FBA section at the top
3. Check for a system.net section (usually at the end) for complex mail configurations
4. Repeat this check in Robot, FBA, and WebUI tabs

2.7. Password rules

1. Check the App Manager Service, FBA, WebService, and WebUI tabs
2. Look for the Pentana.TNG.UI.Web.FBA section
3. Note any custom password rules that differ from defaults

2.8. Retain synchronization

1. Navigate to the Robot tab in App Manager
2. Connect to the robot service
3. Check if Retain synchronization is enabled (boxes will be ticked if in use)

If Retain is used then there may be work to do to migrate Retain.  That is outside the scope of this article, please contact Support for further guidance.

2.9. Client Deployment Method

1. On a client PC, launch the application
2. Open Task Manager
3. Locate the running Pentana client process (right click on the process and Open file location)
4. Check the folder path:
   • If it is some obscure path like \AppData\Local\Apps\2.0\[random text] then the client is installed using ClickOnce
   • If the path is Program Files: MSI or other deployment method is used

3. Taking old system offline

1. Ensure your users have any checked out work or reserved documents checked in
2. Close App Manager
3. Verify the message queue is empty
4. Stop the Robot service and set it to Disabled
5. If Retain is in use, stop the Retain services
6. Stop all Pentana application pools in IIS Manager

4. Migrating the database

4.1. Preparation and backup

1. Connect to the old database server
2. Back up the Pentana database
3. Take the old database offline to prevent any data changes

4.3. Restoring on new server

1. Copy the backup file to the new database server
2. Restore the database from the backup file
3. Verify the correct login is in place, and that it is mapped to the user in the database

5. Setting up application server

5.1. Transfering installation files

1. On the old application server, locate the folder containing:
   • App Manager instances
   • Installation files
   • Any custom DLLs / a CustomerFiles folder
2. Zip the entire folder
3. Transfer to the new application server
4. Unzip the files

5.2. Configuring App Manager

1. Launch App Manager on the new server
2. When prompted, browse to the transferred App Manager instances folder
3. Select the appropriate instance (UAT or Production)
4. Check the Install Files section is pointing to the correct path for the installation set
5. Update all configuration pointing to old locations.  Expand each section in turn and update relevant text:

5.2.1. Variables

• Expand the configuration variables section
• Update the SQL server instance name
• Update the site address
• Update the help URLs
• Review machine keys (can keep the same for convenience or change per installation guide)

5.2.2. Main service

• In the Main Service section, update the main service connection string
• Update the authentication database connection string
• Update the WebUI connection string

5.2.3. WebUI

• Update the authentication database connection string

5.3. Saving and reconnecting

1. Save the configuration
2. Close and reopen App Manager to establish connection to the new database
3. Verify the connection indicator shows green

5.4. Setting up message queue

1. Open Computer Management
2. Navigate to Message Queuing
3. Create a new private queue with an appropriate name (e.g., PentanaUAT).  Ensure Transactional is ticked
4. Set permissions:
   • Grant the Pentana service user full control
   • Grant the Pentana Robot user full control

5.5. Installing components

In App Manager, go to the Config tab:

1. In the Main Service section, click Install
2. Go to the Robot section and Install
3. Go to the Web Application section and Install
4. Go to the Client section, and Install

5.6. Configuring IIS application pools

1. Open IIS Manager
2. Locate the Pentana application pools created by App Manager
3. For each Pentana application pool, change the identity to the correct service account

5.7. Configuring Robot service

1. Open Services (services.msc)
2. Locate the Pentana Robot service
3. Change the "Log On As" account to the correct robot service account
4. Set startup type to "Automatic (Delayed Start)"

5.8. Setting folder permissions

5.8.1. Robot service folder

1. Navigate to C:\Program Files (x86)\[Robot folder]
2. Grant the robot service account Modify permissions (for log file writing)

5.9. Web service folders

1. Navigate to C:\inetpub\wwwroot\[Pentana UAT instance]
2. For each service folder (Service, WebService, WebUI), grant the Pentana service account Modify permissions (for log file writing)

5.10. Copying additional files

5.10.1. License file

1. On the old server, navigate to c:\inetpub\wwwroot\[pentana instance]\Service.
2. Copy the license file.
3. On the new server, paste it into the service folder.

5.10.2. Help files

1. On the old server, locate the Help and Web Help folders.
2. Copy both folders.
3. On the new server, paste them into the matching location.

5.11. Configuring authentication

The default configuration uses:

• Windows authentication for desktop client
• FBA for WebUI

If using SAML or different authentication methods, update configurations according to the documentation at this stage.

5.12. Configuring message queue

1. In App Manager, navigate to the Config > Service tab.
2. Locate the section <Pentana.Tng.Notification> (will be commented out by default).
3. Remove the comment markers.
4. Update the queue name to match your queue (e.g., replace visionqueue with PentanaUAT).
5. Save the configuration.

5.13. Configuring additional elements

If needed, configure:

• Additional password requirements
• Complex mail server configurations
• File store configurations

5.14 Configuring SSO via SAML (Optional)

5.14.1. Desktop

If your desktop client authenticates using SSO via SAML:

1. Go to the old server.
2. Navigate to c:\inetpub\wwwroot\[pentana instance].
3. Copy the folder SamlMvc.
4. Paste to the corresponding location in the new server.
5. In IIS Manager, convert the new folder to application, and ensure the correct app pool is specified.
6. In App Manager, in the Config > Service tab, locate the section <Pentana.Tng.Service>.
7. Uncomment the key UseSAMLAuthentication.

This brings across all the certificates and most config settings.

You will also need to update the client config file vision.exe.config.

5.14.2. WebUI

If your WebUI authenticates using SSO via SAML:

1. Go to the old server.
2. Navigate to c:\inetpub\wwwroot\[pentana instance]\WebUI.
3. Copy the folder Certificates.
4. Paste to the corresponding location in the new server.
5. In App Manager, in the Config > WebUI tab, locate the section <Pentana.Tng.UI.Web.Vision>.
6. Uncomment that section.

You will also need to change your Idp where it references the app server URLs.

5.15. Moving API (Optional)

If you are moving the API to the new server:

1. Go to the old server.
2. Copy the API and any secondary ServiceAPI folder.
3. Paste to the corresponding location on the new server.
4. In IIS Manager, convert the new folder(s) to application, and ensure the correct app pool is specified.
5. Open API\Web.config in Notepad and update the connection string and site address values.
6. Save.
7. Open ServiceAPI\Web.config (if present) and update the connection strings and site address values.
8. Save.
9. Open Edge.
10. Open the following URL:  https://server.domain.com/[pentana instance]/API/auth/ResetKeys.
11. Then, open https://server.domain.com/[pentana instance]/API/auth/GetPublicKey.

This copies across all configuration, and creates the certificates required by the API service.

6. Testing and validation

6.1. Testing service connectivity

From a client PC, browse to the service endpoint, e.g.  URL https://server.domain.com/PentanaUAT/Service/TngService.svc.

This verifies that the service is running and can connected to the database.

6.2. Starting Robot service

On the application server, start the Robot service and verify it starts without errors.

6.3. Testing Desktop client

From a client PC:

1. Navigate to the client URL
2. If an old client is installed, uninstall it via Add/Remove Programs
3. Install the new client.  If you are using ClickOnce, the URL will be like https://server.domain.com/PentanaUAT/Client.
4. Launch the client, verify it opens successfully and that you can login
5. Test the help pages by clicking Help
6. Test mail server connectivity by e.g. triggering a password reset email (right-click a user, select Add FBI Identity, Reset Password)
7. Have real users log in from their locations to verify access

6.4. Testing WebUI

From any device:

1. Navigate to the WebUI URL (e.g. https://server.domain.com/PentanaUAT/WebUI).
2. Log in with valid credentials.
3. Verify the help links work correctly.

6.5. Testing optional components

If applicable, verify:

• API functionality
• Excel Importer functionality

7. Go-live

When you're ready for go live:

1. Schedule the production migration.
2. Repeat all steps for the production environment.
3. If specifying different application names between old and new installations, client reinstallation will not be necessary.

Considerations:

• Always take the old database offline after backup to prevent accidental data additions
• Keep the same folder paths between servers when possible to minimize configuration changes
• This process assumes you're maintaining the same application version

8. Walkthrough

Each of the links below shows you a video demonstration of each of the steps described above:

• Overview and gathering information
• Taking the system offline
• Moving the database
• Installing on a new server