Tekla Model Sharing on-premises server installation and management guide

The following illustration shows the main components, communications, and data storages of the Tekla Model Sharing on-premises server. In the illustration, Microsoft SQL Server and Tekla Model Sharing on-premise servers are shown to be installed on separate hosts, but they can also be run on the same host, depending on the hardware and the load (users and models) for the server.

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.

Hardware

This 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

Tekla Model Sharing allows you to share any additional files, such as reference models, within the model folder if you choose so. If you choose to share reference models with Model Sharing, you need to include them to your estimates for disk space, network and server capacity. The average figures used above will then be higher: Baseline model version sizes will grow, and each change packet that has a new reference model file will be that much bigger, even zipped.
 

Software

• 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 installation

Install 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 installer

In 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 installer

1. 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.

 

 
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 
• "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

1. 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.
2. 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.

3. 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 database

When 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 DataSharing9 as the Default database for that "Login" account.
  On the User Mapping page as shown below:

• check that this Login to have "Users mapped to this login" the database "DataSharing9" is selected
• 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 service

When 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

1. 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.
2. 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 server

You can monitor the On-Premises Server through Windows Event Viewer.

Enabling on-premises server on Tekla Structures installations

On-premises server usage must be enabled by running an additional installer on each workstation where Tekla Structures is installed.

1. Download the installer to enable on-premises server selection
2. Run the installer on each Tekla Structures client machine that needs to connect to an on-premises server.

3. 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.

 

When you need to upgrade an existing server installation, download the newest version installer from Tekla Downloads.

The upgrade installation is done with the following steps:

1. Stop the on-premises server meaning the Tekla Model Sharing 3 Windows service
2. Take a full backup of the SQL server database
3. Run the installer. The installer will also provide the possible needed SQL schema update scripts.
4. Check if any SQL schema updates need to be run for the newly installed version, see the separate chapter below.
5. 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. 
6. Start the on-premises server meaning the Tekla Model Sharing 3 Windows service
7. 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
3.11.3	3.12.217	UpgradeSchema_9_6_to_9_12.sql
3.11.3	3.13.9	UpgradeSchema_9_6_to_9_12.sql

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.

For best practices of the SQL Server database backup and restore, study the Microsoft documentation, such as  Back Up and Restore of SQL Server Databases. Then plan and choose your backups and restore strategy based on business criticality. As recommended in the documentation test and practice restoring. Ensure that your data is backed up before any software or hardware upgrade.

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:

1. 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.
2. Backup the SQL Server database.
3. After completion of step 2 backup the file folders containing the model data (BLOBs).
4. Start the Tekla Model Sharing service if it was stopped in step 1

1. Stop the Tekla Model Sharing service.
2. 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.
3. Restore the file folders containing the model data (BLOBs). Make sure your file backup is later than the SQL database that you restored.
4. Start the Tekla Model Sharing service.
    

Sharing operations fail in Tekla Structures

If 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 database

When 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 Internet

If you cannot log in to https://account.tekla.com, check that your firewall is allowing to access https://account.tekla.com.
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 traffic

If 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.config file located in the TeklaStructures\<Version>/nt/bin folder.
Note: Set the correct HTTP proxy hostname and port depending on the actual environment.

<?xml version ="1.0"?>
<configuration>
<runtime>
...
</runtime>

<startup>
...
</startup>

<!-- BEGIN HTTP PROXY SETTINGS -->
<system.net>
<defaultProxy enabled="true" useDefaultCredentials="true">
        <proxy proxyaddress="http://DEFINE_IP_ADDRESS_HERE:DEFINE_PORT_HERE" usesystemdefault="False" />
</defaultProxy>
</system.net>
<!-- END HTTP PROXY SETTINGS -->

</configuration>
 

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"

The Tekla Model Sharing on-premises server is by default backward compatible, but not forward compatible.

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.