Tekla Model Sharing on-premises server installation and management guide
This document is intended for users installing and managing Tekla Model Sharing on-premises server.
Note that Model Sharing on-premises server is designed and intended to use in a closed LAN / (VPN / WAN) environments only. This means that the installation, servers, and software (OS, any middleware as for example MS SQL Server in this case), network (LAN / VPN / WAN) must be managed by the customers as Trimble has no control over them.
Please note that you need to have the skills and administrator rights to manage Microsoft Windows Operating System and SQL Server databases.
Windows administrator rights are needed for the installation. Network administrator rights and skills are needed for possible firewall adjustment or setting up VPN / WAN connections.
Overview of the Tekla Model Sharing on-premises server architecture
Tekla Identity and Trimble Identity services are accessed to check the Model Sharing license based on the user identity. So for that, there needs to be internet access allowed to account.tekla.com and identity.trimble.com addresses.
Note that there is no Management Console application for the on-premises server but with the on-premises server installation settings, one user account can be set to always get the owner rights for all the models in one on-premises server.
Skills and management rights
You need to have the skills and administrator rights to manage Microsoft Windows Operating System and SQL Server databases.Windows administrator rights are needed for the installation. Network administrator rights are needed if company and server firewall settings need to be adjusted.
HardwareThis is the description of the virtual server set-up that was used when testing the server. The tests are simulating typical TS usage with model version uploads and downloads. Successful tests have been run with up to 100 users.
Depending on the number of simultaneous users and complexity of the models that are shared, you might need to scale up the hardware especially the disk space.
The server has 4 virtual cores.
In most of our tests, the SQL Server has been run on the same host with the on-premises server. Separating the database server to another/dedicated host will share the load. The size of the SQL database is currently relatively small, as the actual model data is kept in Windows file folders. For example, the database size on a test server with 38 000 models and 78 000 versions is 340 MBytes.
The disk space needed for the model data depends heavily on the complexity of the models that are going to be modeled. For example, you could estimate roughly the space needed with the following rough/average figures:
- Each baseline of a model version taking about 100 MB
- At least 1 baseline is used with the initial sharing
- Every now and then a new baseline is created when the user decides to do so
- Let’s estimate 1 baseline for 100 versions here
- Each version (changes made to model) taking 5 MB
- For one average-sized model, you could estimate about 2000 versions to be created over the time
- For one model the estimate would then be:
- 20 baseline versions = 20 x 100 MB = 2 GB
- 2000 x 5 MB versions = 10 GB
- Windows Server 2012 or later.
- SQL Server 2012, 2014, 2016, 2017 or 2019 with SQL Server Management Studio.
- Use the default compatibility settings for the required SQL Server
- Collation for SQL Server: In most cases, a computer runs the Windows system locale that matches the collation requirements for the Tekla Model Sharing server. Currently, Model Sharing server is not depending on the collation. For more information, see Using SQL Server Collations.
- The needed .NET Framework version is included in the installer and will be automatically installed if not already installed.
Basic workflow for server installationInstall the server following the steps below:
Step 1: Download the installer from Tekla Downloads.
Step 2: Run the installer.
Step 3: Create an SQL server database and schema using the sql script delivered by the installer.
Step 4: Set up SQL server authentication and access rights to the created database.
Step 5: Start the installed Windows service.
Each step is described in more detail below.
Step 1: Download the installerIn order to be able to download the server installer you need to have:
- Ordered a Model Sharing on-premises server license from Trimble
- Received a confirmation that Trimble has enabled the installer to download to the named person that has a valid Tekla Identity.
With the granted access, you can download the server installer.
Step 2: Run the installer1. Start the installer using a Windows account with administrator rights.
2. Fill in the required information in the Service Configuration "SQL Server database parameters" dialog box (see below). At this point of installation it is not critical to know any of the final or existing values for the database, so just give the ones according to your best knowledge. You can easily change these later on by running the installer again.
- For SQL Server authentication mode the default and recommendation is Windows Authentication
- Using SQL Server Authentication is mostly for backward compatibility. Note that using this option the SQL Server credential are stored in plain text in the server.
In case several SQL Server instances are used you then have to point out the instance used in the form that SQL Server uses: <HOSTNAME>\<INSTANCE NAME>.
Note also that in case your SQL Server is running in a separate host check that TCP/IP is allowed in SQL Server Configuration Manager to allow TCP/IP connections from remote hosts.
3. Proceeding with Next button you get to the following Service Configuration dialog:
- In case the default ports (9997 or 9000) are reserved in the host define other port numbers that are free
- Note: "port number for clients to connect" is the only one that TS users need to know and give when setting up the connection to the server
- Select the file folder to store the model data. Make sure that the folder exists.
4. Proceeding with Next button you can set the Optional Settings
- "SMTP mail server for sending emails":
- Give the SMTP server name or IP address. The server is used for notifying users when they get access to some model.
- Default: no SMTP server, you can leave this empty if there is no SMTP server available or you do not want/need to use any.
- "Server DNS name or IP":
- In cases (e.g. some VPN scenarios) where the Windows Server hostname is not visible for the users, you can here define the name or IP address that will be used when connecting the server
- Default: Windows hostname of the server is used as default if left empty
- "Owner user (email) for all the models":
- The user account (in account.tekla.com) with the email defined here is always added as Owner for all the models stored in this on-premises server
- this way the given user is guaranteed to always have Owner rights in Tekla Structures (TS) for all the models and act as an administrator
- the user-defined here cannot be removed or her role as Owner cannot be changed in TS
- NOTE: when the "Owner user email" is changed the owner rights remain for the previous Owner user (email) until taken away explicitly from the models by any other owner user. Likewise setting the "Owner user email" to empty does not remove the owner rights given before that.
- Default: empty
- The user account (in account.tekla.com) with the email defined here is always added as Owner for all the models stored in this on-premises server
- "Keep time for deleted models"
- time in days that the models marked as deleted in Tekla Structures are permanently deleted from the on-premises server
- Default: 30 days, minimum 1 day
- Note: This setting and feature are available from on-premises server version 3.13.38
5. Then proceed with Next button to finalize the installation
A new Windows service with the name Tekla Model Sharing 3 is installed with the given parameters. The service is not started automatically at this point, and you will start it manually after completing the whole installation.
Step 3: Create the SQL server database and schema
- Connect to your database server using Microsoft SQL Server Management Studio. Your Windows account need to have the right to create a new database on the SQL Server.
- Locate the SQL file that will create the database and SQL schema for the Tekla Model Sharing on-premises server to use. The installer places the file in the following folder:
The file name is in form
CreateSchema*.sql s and there is always only one file starting with that naming pattern for example:
CreateSchema_9_12.sql. The numbers in the name representing the database schema version.
- Open the file in Microsoft SQL Server Management Studio and run the script. This will create the database with the name
DataSharing9. The script will also create the schema to the new database.
Step 4: Check and adjust Microsoft SQL Server authentication and access rights to the created databaseWhen using the default and recommended Windows authentication method with SQL Server that the Windows account (username) is the owner of the created database.
Note: Depending on the SQL Server Management Studio version, the user interface may differ from the images below.
In SQL Server Management Studio from the Security --> Logins folder you can see all the "Login" accounts as shown below:
Open the "Properties" dialog using the pop-up menu with the name of your Windows account (TEKLAAD\teklarp in this example) as shown in the picture below.
It is recommended to set the created Model Sharing
DataSharing9as the Default database for that "Login" account.
- check that this Login to have "Users mapped to this login" the database "
- In the "Database role membership for: DataSharing9" the db_owner is selected
Click OK to save the changes made to the Login.
Step 5: Set the used Windows account as "Log On" to the serviceWhen using the recommended Windows authentication for SQL Server, you need to set the correct Windows account and password to the Tekla Model Sharing 3 Windows service.
Important: Make sure that you set the Windows account that you have given the access rights to the database. Note also, that this account has to have read and write rights to the file folders to store the model data (given when running the installer). Especially if you have been running the installer with another Windows account the access rights needs to be adjusted.
You can do this by opening the Services application in Windows.
Locate Tekla Model Sharing 3 service and open its properties.
Set the right Windows account and password on the Log On tab, see the image below:
Step 6: (Re)start the installed Windows service
- Start the installed Windows service by the name Tekla Model Sharing 3. In case the service is already running restart it to make sure the latest settings are in use.
- Use Windows Event Viewer to browse the events and that there are no errors from the Tekla Model Sharing 3 service. Note that there might be an information message showing that the service process has started successfully but still the service might not be able to connect to the database. That's why it is important to browse the events backward too.
Monitoring the on-premise serverYou can monitor the On-Premises Server through Windows Event Viewer.
Enabling on-premises server on Tekla Structures installationsOn-premises server usage must be enabled by running an additional installer on each workstation where Tekla Structures is installed.
- Download the installer to enable on-premises server selection
- Run the installer on each Tekla Structures client machine that needs to connect to an on-premises server.
- To add the on-premise server hostname and port to Tekla Structures client, click the + icon located next to the Service selection list, then click Connect to the Server and see the list of models that you have access to.
Server upgrade installation
The upgrade installation is done with the following steps:
- Stop the on-premises server meaning the Tekla Model Sharing 3 Windows service
- Take a full backup of the SQL server database
- Run the installer. The installer will also provide the possible needed SQL schema update scripts.
- Check if any SQL schema updates need to be run for the newly installed version, see the separate chapter below.
- In case the Windows Authentication is used for SQL Server check that the correct Windows username and password are given to the Windows Service properties "Log On" tab.
- Start the on-premises server meaning the Tekla Model Sharing 3 Windows service
- Use Windows Event Viewer to verify that there are no errors from the service and that there are information messages showing that the service has started.
Perform database schema version upgrade when needed
|From version||To version||Update script name|
Note that by default the provided SQL schema update scripts are warning about the database backup and the scripts won't run until the following row is commented or removed from the script:
SET @BackupNeeded = 1
If needed you can check the current database schema version using the GetSchemaVersion.sql script, located in C:\ProgramData\Tekla\ModelSharing\v3\Database. By default the C:\ProgramData\ folder is hidden from Windows File Explorer, so you need to enable showing hidden folders.
BEFORE RUNNING ANY DB SCHEMA UPDATE SCRIPTS MAKE A BACKUP OF THE DATABASE with SQL server backup tools! It is also recommended to stop the on-premises server (Tekla Model Sharing 3 Windows service) before the backup and keep stopped while running the SQL schema update script(s).
Run all the needed upgrade scripts starting from the oldest version that has not been run yet. The starting point/script depends on your current database schema version.
The SQL upgrade script checks the current database schema version when you start to run the script, and it will not run if the current schema version does not come before the upgrade script.
Data backup and restore
The basic rules for backup and restore on-premises server data are dependent on the basic architecture of the on-premises server: The SQL database is used for bookkeeping of the actual model data stored as normal files in the disk. So the content of the SQL database defines what model versions can be found from the disk. Backing up a consistent copy of the SQL database first ensures that all the files (model versions) referenced in the database are consistently written into the disk.
To back up the SQL database and the related model data (file folders) follow these steps in the given order:
- Optionally: Stop the Tekla Model Sharing service (Windows service). Stopping the service will ensure that your backup is consistent. That is, of course, a must requirement in cases like when moving the installation from one hardware to another.
- Backup the SQL Server database.
- After completion of step 2 backup the file folders containing the model data (BLOBs).
- Start the Tekla Model Sharing service if it was stopped in step 1
To restore a backup follow these steps in the given order:
- Stop the Tekla Model Sharing service.
- Restore the backup of the SQL database. Make sure your database backup restored is earlier than the complete file backup you are going to restore.
- Restore the file folders containing the model data (BLOBs). Make sure your file backup is later than the SQL database that you restored.
- Start the Tekla Model Sharing service.
Sharing operations fail in Tekla StructuresIf your model sharing operations fail in Tekla Structures check the client log files for any errors that might give you some hints about the problems. Many times it is network connectivity and then you will see "timeout" errors in the logs.
Ensure that the "Tekla Model Sharing 3" Windows service is running.
Check for any errors from server machine Windows Event Viewer --> Windows Logs --> Application where the source is "Tekla Model Sharing 3". Browse all the rows with that source and ensure that none of them is in the "Error" level.
Ensure that any firewall does not block the traffic to TCP/IP ports used. Inbound traffic must be allowed to your server TPC ports 9000 and 9997 (when you use the default ports set with installer). To check that the ports can be reached using for example Telnet and try to connect to both ports.
Ensure that the SQL Server is running properly. Note: In case you cannot connect to the SQL Server host or database you will see some error messages related to this by using Windows Event Viewer
Model sharing server cannot connect to the SQL Server databaseWhen the server process cannot connect to the SQL Server host or database you will see error messages related to this by browsing the log events with Windows Event Viewer.
In case your SQL Server runs in different server host ensure that you can connect to that outside of the database server: Make sure your firewall allows the connection to the SQL Server host and that your SQL Server allows remote connections (protocols), see Troubleshoot Connecting to the SQL Server Database Engine
Cannot access Tekla Identity from InternetIf you cannot log in to
https://account.tekla.com, check that your firewall is allowing to access
Note that some older Tekla Structures versions do not give any message for the user about this and just silently fails to login. So the username is not shown in this case in the upper right corner after a login attempt.
Check if any firewall does not block the traffic to https://account.tekla.com and https://identity.trimble.com.
Check that in case http proxy is used you can connect to it using Tekla Structures. See the following chapter:
Http proxy with authentication is used for all HTTP trafficIf all the HTTP(S) communication is routed through a HTTP proxy that requires authentication, the following HTTP proxy related settings must be added to the settings in the
TeklaStructures.exe.configfile located in the
Note: Set the correct HTTP proxy hostname and port depending on the actual environment.
<?xml version ="1.0"?>
<!-- BEGIN HTTP PROXY SETTINGS -->
<defaultProxy enabled="true" useDefaultCredentials="true">
<proxy proxyaddress="http://DEFINE_IP_ADDRESS_HERE:DEFINE_PORT_HERE" usesystemdefault="False" />
<!-- END HTTP PROXY SETTINGS -->
So you need to change the DEFINE_IP_ADDRESS_HERE:DEFINE_PORT_HERE part with the IP address (or hostname) and port number for example: "http://10.0.0.200:8080"
Server version compatibility
On-premises server version 3.11.x works with Tekla Structures up to 2018i.
On-premises server version 3.12.x works with Tekla Structures up to 2020.