Note: This is a new installer process starting with WebTMA 7. It is recommended you review this entire document before beginning the install process. This process is designed to help simplify your WebTMA Installation. If you are running a version earlier than 7, it is required that you uninstall your previous WebTMA5 install before installing the new version if they will be residing on the same server. Please also make note of any virtual directory names of WebTMA components so that your user URLs remain the same as the previous install.
**New - If you would like to watch a step by step tutorial on installing and configuring the base product as well as the new UI/UX, click here to view: Click Me
This document covers:
- New Installs
- Updating your WebTMA7 version
Information Needed Before You Begin
- Name of the WebTMA database Server (server where the WebTMA database is installed or will be installed if on a new server)
- A SQL Username and Password used to access the WebTMA database. The SQL User needs to have DBCreator privileges and DBO for the database being updated
- Name of the WebTMA application server (server where the WebTMA application is installed or will be installed if on a new server)
- Server path, port and authentication information for the SMTP server that will be used for outbound messaging from WebTMA7
- SSRS server information and credentials if you will be using custom SSRS reports with the WebTMA7 application
- Your WebTMA7 license file and software Serial Key provided by TMA Systems (Note – A new license file and key is required if you are upgrading from WebTMA5. Your WebTMA5 license file is not compatible with WebTMA7. Please have an authorized support contact from your company email support at support@tmasystems.com to request a new license and license key)
Server Prerequisites
- Server specification should be met in accordance with those found here. WebTMA7 requires upgraded hardware capacity over WebTMA5. Please review the new requirements.
WebTMA7 File Backup and Documentation
If you have a previous version of WebTMA 7 installed on your server and are upgrading, back up these files (not applicable for new installs):
- clientsettings.json -- C:\Program Files\TMA Systems LLC\WebTMA 7\Sites\WebTMA7
- clientsettings.json -- C:\Program Files\TMA Systems LLC\WebTMA 7\Sites\MobileService
-
clientsettings.json -- C:\Program Files\TMA Systems LLC\WebTMA 7\Sites\InternalAPI
-
clientsettings.json -- C:\Program Files\TMA Systems LLC\WebTMA 7\Sites\PlatformAPI
-
clientsettings.json -- C:\Program Files\TMA Systems LLC\WebTMA 7\Sites\UIService
-
Web.config -- C:\Program Files\TMA Systems LLC\WebTMA 7\Sites\WebTMA7
- Web.config -- C:\Program Files\TMA Systems LLC\WebTMA 7\Sites\MobileService
Additionally, will want to document the previous configuration for the WebTMA7 Application before starting the upgrade (not applicable for new installs). To do this, you will want to capture information from IIS.
- Launch IIS Manager
- Open Default Website (or other website WebTMA is installed under)
- Record the following information about your WebTMA Virtual Directories and the website it’s installed under:
- Click the website header.
- Click bindings on the right.
- Take a screenshot or record the entries found here.
- Click on All WebTMA related virtual directories.
- Click Basic Settings on the right and make a screenshot or record the information for each virtual directory.
- Keep this information available in case it is required for reference during the new install.
Installation Steps
NOTE: The WebTMA 7 installer installs .NET 8 which is required for WebTMA7 to function properly.
New Installation
1. Install and setup SSRS Report Server. This link will open the Knowledgebase article on installing and configuring SSRS Report Server. https://knowledgebase.tmasystems.net/hc/en-us/articles/24093063137549-SSRS-Report-Servers-Installation-and-Setup
2. Download the WebTMA7 installer from the TMA Systems knowledgebase (https://knowledgebase.tmasystems.net/hc/en-us/articles/22369163858445). Place the installer exe file on the application server. Right-click and run WebTMA 7.exe as administrator.
-
- You must agree to the License terms and conditions to Continue.
- You may also change the default installation path here if necessary.
3. Next > Choose the default IIS Website. The default must already be configured on the server for the installation program to work. (Note: The Site must be secure - https)
4. Next > Enter Client Name that you want associated with the WebTMA application. This is an alphanumeric string that is typically the name of your company. This will display on some system reports, is used by our Universal Interface imports, and might be used on login page depending on how the Configuration File is setup.
5. Next > Enter SQL Server Connection Information for the database server where the WebTMA7 database will be installed:
6. Next > Configure SMTP Server Connection (see article on Email Settings if not using SMTP - https://knowledgebase.tmasystems.net/hc/en-us/articles/24093305422221-Email-Settings-If-Not-Using-SMTP )
7. Next > Configure SSRS Server Connection
8. Next > Select Features. Select all services and sites to be installed. Do not remove any of the selected items from the list. Features will be turned on/off based on your license file and configuration. Please install the full application to avoid future potential issues with enabling new features.
9. Next > Installation Folder tab can be used to change the default installation path if needed.
10. Select the Install button. This will take several minutes to complete depending on the processing power of your server.
11. Once the installation is complete, select the Finish button.
**Note: Once clicking finish, the information entered during the installation will be written to all clientsettings.json files located in the folders shown below. If any changes are made to the config file after the initial installation (IE changing SSRS servers, adding another client, etc.) each clientsettings.json file located in the shown folders below will need to be updated by copying the clientsettings.json file from C:\Program Files\TMA Systems LLC\WebTMA 7\Sites\WebTMA7.
12. URL Setup - Once the installation is complete, you are ready to configure the URL for the application. Your organization will need to determine if the URL to your WebTMA instance will be exposed internally (your company network only) or externally (published to the full internet). Once that is decided, you will need to register the URL for WebTMA. Once the URL is registered, you will edit the clientsettings.json file in the WebTMA7 folder to insert the Application Base URL, FrontendBaseURL, and the Client Host URL. In the example below, the EXAMPLECLIENTNAME is the client name you defined in Step 4 above. The Application Base URL is the full path URL you have registered for your WebTMA application. The Frontend Base URL will be the same as the Application Base URL with '/app' appended at the end. The Client Host URL is the client‐specific hostname that they application will automatically select the clientname on login page and display the company logo if matched. By following this configuration format, your users who manually login (not through SSO), will not be required to enter the Client Name in the login process.
{
"WebTMAClients": {
"EXAMPLECLIENTNAME": {
"ConnectionString": "...",
"ApplicationBaseUrl": "https://webtma.yourcompany.com/WebTMA7",
"FrontendBaseUrl": "https://webtma.yourcompany.com/WebTMA7/app",
"ClientHostUrl": "webtma.yourcompany.com",
...
"SSRSConfig": {
...
}
}
}
}
ConfigTool
The ConfigTool is used to update any configurations set by the installer and/or update your license file.
eTools is used to update the database when upgrading from a prior version of WebTMA7.
Launching the ConfigTool and eTools are toggleable upon completion of the installation process.
If you need to run the ConfigTool at a later time, it can be launched by selecting the WebTMAConfigTool.exe file. This is the default path but could be different depending on where you ran the installation program from (C:\Program Files\TMA Systems LLC\WebTMA 7\Tools\WebTMA7ConfigTool\WebTMAConfigTool.exe)
Configuration Tool Setup
On this screen you will be asked to browse to the configuration file. The default location is C:\Program Files\TMA Systems LLC\WebTMA 7\Sites\WebTMA7\clientsettings.json
The Config Tool should be set up as illustrated in the following screenshot using your server information.
When finished with all Config information, click save at bottom of tool.
In the Functions section you can test the data base connection or update your license if needed.
eTools
If eTools is necessary for an upgrade, it is highly recommended you fully back up your WebTMA database before going further.
Once your data is backed up, you can proceed using the following information:
- Server – The Server Name/IP address (and instance name if necessary) of your WebTMA database server.
- Database – The name of your WebTMA database.
- User Name – This should be a user with dbo access to the WebTMA database and requires permission to create/delete a temporary database as well.
- This should not be the same login as your WebTMA Application.
- Password – The password for the designated eTools User.
- Execute – The execute button starts the eTools process. It should take anywhere from 10 to 15 minutes for this to complete depending on the size of your database. When you see Upgrade process completed at the bottom, eTools has finished.
App Settings Configuration
1. Matching GUIDs
We have included matching GUIDs (Globally Unique IDentifiers) in the default appsettings.json files we provide, located under "JsonWebTokenKeys" > "IssuerSigningKey", in the following folders:
- WebTMA7
- InternalAPI
- PlatformAPI
GUIDs must match across these 3 folders in order for the app to run properly. For added security you may generate your own GUID using any online resource to use in place of the one we have provided.
Fresh installs will have matching GUIDs, while upgrades may need to check to ensure consistency across these files as existing appsettings.json files are not overwritten during installation. Upgrades experiencing variance across/missing “JsonWebTokenKeys” sections may find it easiest to copy and paste that entire section from one of these files into the other two. In the case the section is missing, the location where it is inserted in the order of attributes is not important, so long as it is left-justified and does not disrupt the structure of other sections.
2. IP Rate Limiting
We have included a commented-out section called “IpRateLimiting” in the default appsettings.json files we provide in the following folders:
- InternalAPI
- PlatformAPI
IP Rate Limiting is an optional security measure that can help mitigate potential security threats through controlling the rates of incoming requests allowed from a single IP address within a set of specified time frames. To enable, simply uncomment the section(s) and set your desired limits, then recycle the respective Application Pools for the limits to take effect.
3. Application Base Path
We have included a base application path which is used for routing in our application. The setting is found in the application settings config file:
- appsettings.json -- C:\Program Files\TMA Systems LLC\WebTMA 7\Sites\WebTMA7
In that file it is important that you indicate the relative path with a leading and trailing forward slash (i.e. "/"). The entry should look like this for most installations:
"ApplicationBasePath": "/WebTMA7/" .
UI/UX IIS Configuration
The following setup is required to enable the New User Interface/Experience (UX). The new UX runs under a separate application from the legacy WebTMA7 application interface.
1. URL Rewrite Module
A URL Rewrite Module must be installed on the target machine in order for the routing to work properly in IIS Manager. You can find a link at the bottom of this page: https://www.iis.net/downloads/microsoft/url-rewrite (x64)
2. WebDAVModule
The WebDAVModule must be removed for the WebTMA7 site in IIS Manager:
- Expand to/select site 'WebTMA7'
- Open Modules from middle pane
- Select WebDAVModule > click Remove on Actions pane
- Restart IIS
Enable Custom SQL for Dashboards
Instructions for enabling the custom SQL window for Dashboards can be found in this knowledgebase article.
Enabling Custom SQL Window for Dashboards for On-Premise Installation
Troubleshooting FAQ
- The new UI login page is not launching. Check the ClientHostURL in the client settings.json file. If your URL has http or https, please remove. The URL entry should look like "ClientHostUrl": "webtma.yourcompany.com"
WebTMA 7 Installation Terminology
clientsettings.json file – A configuration file used by WebTMA 7 for client‐specific settings.
ConfigTool – The configuration tool that installs with WebTMA 7 and is run after. Default install
location:
C:\Program Files\TMA Systems LLC\WebTMA 7\Tools\WebTMA7ConfigTool\WebTMAConfigTool.exe
ConnectionString – The connection string property for the database that WebTMA will connect to.
- ApplicationBaseUrl – The full, public‐facing base URL for this installation of WebTMA (e.g.https://webtma.testclient.com)
- ClientHostUrl – A client‐specific hostname. Will automatically select client on login page and display logo if matched.
- FrontendBaseUrl – Internal setting that WebTMA 7 uses and will be set automatically by the installer. If the new UI/UX is not launching properly, please confirm /app is part of the path (i.e. webtma.yourcompany.com/app)
- ApiBaseUrl – Internal setting that WebTMA 7 uses and should be set automatically by the installer.
- EnableSSO – Setting to allow Single Sign‐On, works in correlation with other necessary items.
- EnableEmailService – Setting to enable Email service in WebTMA 7 on premise clients
- EnableEmailGeneration – Internal setting that WebTMA 7 uses and should be set automatically by the installer.
- EnableBatchjobService – Setting to enable the Batch Job service to run against WebTMA
eTools – The database upgrade tool that is run after the WebTMA 7 installation.
SSRS Server – A Microsoft product for authoring and rendering reports; installation of this product is
a prerequisite for WebTMA 7 if you want reporting
SMTP server – An email server through which WebTMA 7 will relay outgoing emails
Web.config file – A configuration file used by WebTMA 7, not user editable with the exception of
backing up prior to an application upgrade.