Optional Tosca Distribution Server configurations

You can configure the behavior of the Tosca Distribution (DEX) Server.

Do not do this while tests are running. If you do, all currently running and queued tests are lost.

In this case, you have to restart Tosca Server and trigger them again.

General server configurations

The following configurations are available for Tosca Distributed Execution with Automation Object Service (AOS) and Tosca Distributed Execution without AOS:

Specify the synchronization interval between the DEX Server and the Agents.
Specify the synchronization timeout between the DEX Server and the Agents.
Whitelist specific domains so that the DEX Server only accepts Agents from these domains.
Change the path of the server log file.
Set up a custom DEX Server port.
Update the Consul and Ocelot configuration files.

Server configurations for Tosca Distributed Execution with AOS

The following configurations are only available for Tosca Distributed Execution with AOS:

Configure the connection retry interval between the AOS and the workspace.
Configure timeout period to check out the test results folder.
Change import results mode, if you upgraded from Tricentis Tosca 14.1 or earlier.

You can also set up Tosca Distributed Execution with AOS to work with multiple repositories. For more information, see chapter "Distributed Execution with AOS with multiple repositories".

Change synchronization interval

The synchronization interval determines how often a Tosca Distribution Agent asks the Tosca Distribution (DEX) Server for ExecutionLists to run.

By default, DEX Server and Agent synchronize once per minute.

With lower synchronization intervals, Agents spend less time in Idle mode, but there is more network traffic.

To change the synchronization interval, follow the steps below:

Open the Tricentis.DistributionServerService.exe.config file. By default, this file is located at C:\Program Files (x86)\TRICENTIS\Tosca Server\DEXServer.
Go to the applicationSettings section.
Set a different value for AgentSynchronisationInterval.
If you want to modify other general configurations you can do so now.
If you are done with your configurations, perform the following actions:
- Save and close the file.
- Restart the service Tricentis.DistributedExecutionService in the Windows Task Manager.

Example: a synchronization interval of 1 minute, 30 seconds:

<applicationSettings>
    <DistributionServer.Properties.Settings>
        ...
        <setting name="AgentSynchronisationInterval" serializeAs="String">
            <value>00:01:30</value>
        </setting>
    </DistributionServer.Properties.Settings>
</applicationSettings>
                                                    

Change Agent synchronization timeout

The Agent synchronization timeout interval determines the amount of time in which the DEX Server waits for an Agent to reconnect in the event of a disconnection.

By default, the DEX Server waits for five minutes before failing to execute any remaining items.

To change the Agent synchronization timeout, follow the steps below:

Open the Tricentis.DistributionServerService.exe.config file. By default, this file is located at C:\Program Files (x86)\TRICENTIS\Tosca Server\DEXServer.
Go to the applicationSettings section.
Locate the setting AgentSynchronisationTimeout. If this is not present in your Tricentis.DistributionServerService.exe.config file, include it as described in the example that follows the last step.
Set a different value for AgentSynchronisationTimeout.
If you want to modify other general configurations you can do so now.
If you are done with your configurations, perform the following actions:
- Save and close the file.
- Restart the service Tricentis.DistributedExecutionService in the Windows Task Manager.

Example: an Agent synchronization timeout interval of 8 minutes, 30 seconds:

<applicationSettings>
    <DistributionServer.Properties.Settings>
        ...
        <setting name="AgentSynchronisationTimeout" serializeAs="String">
            <value>00:08:30</value>
        </setting>
        ...
    </DistributionServer.Properties.Settings>
</applicationSettings>
                                                    

Whitelist domains

If you whitelist domains, the DEX Server only accepts Agents or Tosca CIClients from these domains.

Once an Agent or CIClient contacts the DEX Server, the server checks whether the domain of the user who started the Agent or CIClient matches the domain(s) on the list.

To whitelist domains, follow the steps below:

Open the Tricentis.DistributionServerService.exe.config file. By default, this file is located at C:\Program Files (x86)\TRICENTIS\Tosca Server\DEXServer.
Go to the applicationSettings section.
Set the value for UseAgentLdapAuthorization to True.
Enter your user domains as a value for AgentLdapValidDomains.
- You can enter multiple domains, separated by semicolons.
- You can also use wildcards, for instance tricentis.* or tri*.com.
If you set the value for UseAgentLdapAuthorization to True, but don't enter any domains, users receive an error when they try to execute their TestCases.
If you want to modify other general configurations you can do so now.
If you are done with your configurations, perform the following actions:
- Save and close the file.
- Restart the service Tricentis.DistributedExecutionService in the Windows Task Manager.

Example: two whitelisted domains

<applicationSettings>
    <DistributionServer.Properties.Settings>
        ...
        <setting name="UseAgentLdapAuthorization" serializeAs="String">
            <value>True</value>
        </setting>
        <setting name="AgentLdapValidDomains" serializeAs="String">
            <value>tricentis.com;google.*</value>
        </setting>
    </DistributionServer.Properties.Settings>
</applicationSettings>
                                                    

Change the log file path

The file ToscaDistributionServer.log logs all activities of the DEX Server, for instance when an Agent registers with the server or when TestEvents are distributed.

By default, the system saves the file to C:\ProgramData\TRICENTIS\ToscaServer\DistributionServer\logs.

If you have write access to this directory, you can specify an alternate path.

To specify an alternate path, follow the steps below:

Open the Tricentis.DistributionServerService.exe.config file. By default, this file is located at C:\Program Files (x86)\TRICENTIS\Tosca Server\DEXServer.
Go to the log4net section.
Enter a different path in the value for LogFileAppender.
If you want to modify other general configurations you can do so now.
If you are done with your configurations, perform the following actions:
- Save and close the file.
- Restart the service Tricentis.DistributedExecutionService in the Windows Task Manager.

Example: custom path to the log file

<log4net>
    [...]
    <appender name="LogFileAppender" type="log4net.Appender.RollingFileAppender">
        <param name="File" value="C:\ProgramData\CustomPath"></param>
        <param name="AppendToFile" value="true"></param>
        <rollingStyle value="Size"></rollingStyle>
        <maxSizeRollBackups value="10"></maxSizeRollBackups>
        <maximumFileSize value="10MB"></maximumFileSize>
        <staticLogFileName value="true"></staticLogFileName>
        <layout type="log4net.Layout.PatternLayout">
            <param name="ConversionPattern" value="%date [%thread] %-5level %logger - %message%newline"></param>
        </layout>
    </appender>
</log4net>
                                                    

Configure workspace retry interval

This option is only available for Tosca Distributed Execution with AOS.

After you execute a TestEvent in Tosca Commander, the Automation Object Service (AOS) accesses the workspace. If that fails, it tries again after 90000 milliseconds (90 seconds).

To configure a different time interval, follow the steps below:

In Windows Task Manager, check if the service Tricentis.ToscaAutomationObjectService is running. If it is, stop it.

This might take a little time. You can double-check the Processes tab in Windows Task Manager to make sure that it doesn't list Tricentis.ToscaAutomationObjectService.TcApiExecutor.exe.
Open the file Tricentis.ToscaAutomationObjectService.TcApiExecutor.exe.config. By default, the file is located at C:\Program Files (x86)\TRICENTIS\Tosca Server\AutomationObjectService.
Go to the applicationSettings section.
Enter a new value in milliseconds for WaitTimeInMsForOpenWsRetry.
If you want to modify other AOS configurations you can do so now.
If you are done with your configurations, perform the following actions:
- Save and close the file.
- Restart Tricentis.ToscaAutomationObjectService in the Windows Task Manager.

Example: retry interval is 10000 ms

<Tricentis.TcApiExecutor.Properties.Settings>
    <setting name="WaitTimeInMsForOpenWsRetry" serializeAs="String">
        <value>10000</value>
    </setting>
    [...]
</Tricentis.TcApiExecutor.Properties.Settings>
                                                    

Configure results folder checkout

This option is only available for Tosca Distributed Execution with AOS.

To save test results, the Automation Object Service (AOS) needs to check out the test results folder. If another service has already checked out the folder, the AOS cannot check it out.

By default, the AOS repeatedly tries to check out the folder for 600000 milliseconds (10 minutes).

To configure a different time period, follow the steps below:

In Windows Task Manager, check if the service Tricentis.ToscaAutomationObjectService is running. If it is, stop it.

This might take a little time. You can double-check the Processes tab in Windows Task Manager to make sure that it doesn't list Tricentis.ToscaAutomationObjectService.TcApiExecutor.exe.
Open the file Tricentis.ToscaAutomationObjectService.TcApiExecutor.exe.config. By default, the file is located at C:\Program Files (x86)\TRICENTIS\Tosca Server\AutomationObjectService.
Go to the applicationSettings section.
Enter a new value in milliseconds for MaxWaitForCheckout.

If the AOS cannot check out the test results folder within this timeout period, or it cannot connect to the workspace within the connection retry interval that you specified, it saves the test results to the hard drive.

When the AOS restarts, it tries to save the test results to the common repository again. The timeout period for this retry attempt is the same that you set in the MaxWaitForCheckout setting.
If you want to modify other AOS configurations you can do so now.
If you are done with your configurations, perform the following actions:
- Save and close the file.
- Restart Tricentis.ToscaAutomationObjectService in the Windows Task Manager.

Example: timeout period is 1000000 ms

<Tricentis.TcApiExecutor.Properties.Settings>
    [...]
    <setting name="MaxWaitForCheckout" serializeAs="String">
        <value>1000000</value>
    </setting>
</Tricentis.TcApiExecutor.Properties.Settings>
                                                    

Set a custom DEX Server port

By default, DEX Server runs on port 5007. To use a different port, follow the steps below:

Open the Tricentis.DistributionServerService.exe.config file. By default, this file is located at C:\Program Files (x86)\TRICENTIS\Tosca Server\DEXServer.
Replace the port number in each of the four baseAddresses with the desired port number.

Choose a new DEX Server port number

Save and close the file.
If you have an HTTPS binding, configure the HTTPS certificate to use the new port. To do so, run the following command with administrator privileges:

cd C:\Program Files (x86)\TRICENTIS\Tosca Server\DEXServer\

_SetHttpsCertificate.cmd <certificate thumbprint> <desired port>

Replace the fields <certificate thumbprint> and <desired port> with their respective values.
Restart the service Tricentis.DistributedExecutionService in the Windows Task Manager.
Open the appConfig.json file. By default, this file is located at C:\Program Files (x86)\Tricentis\Tosca Server\DexMonitor\Frontend\assets.
Replace the baseUrl port number with the desired port number.
Save and close the file.
Restart the service Tricentis.DistributedExecutionMonitor in the Windows Task Manager.
Configure the Agents to use the new port. This process differs according to the setup type:
- Distributed Execution with AOS: "Start and connect Agents"
- Distributed Execution with AOS (HTTPS): "Connect the Agents"
- Distributed Execution without AOS: "Start and connect Agents"
- Distributed Execution without AOS (HTTPS): "Connect the Agents"
Configure Tricentis Tosca to use the new port. To do so, go to Project->Settings->Commander->Distributed Execution->Server and update the EndpointAddress setting accordingly.
If you use Automation Object Service, update the Distribution Server Address with the new port number in the Automation Object Service tab of the Tricentis Service Configuration.
Update the Consul and Ocelot configuration files with the new port number.

Consul and Ocelot configuration

You must update the Consul and Ocelot configuration files if you perform any changes to the default port or endpoint address of the DEX Server. The sections below explain in detail where to find these files and how to update the relevant properties.

Update the Consul configuration file

Update the following property values in the Consul configuration file of the service. This file is located at C:\Program Files (x86)\TRICENTIS\Tosca Server\Gateway\Consul\config\DistributionServerService.json:

Property	Description
port	Enter the port used to address the DEX Server.
http	Enter the complete address, including port, used by the DEX Server: <http or https>://<name of host>:<port>

Update the Ocelot configuration file

To update the Ocelot configuration file of the DEX Server, follow the steps below:

Open the ocelot.json file which is located at C:\Program Files (x86)\TRICENTIS\Tosca Server\Gateway.
Search for one element with the ServiceId value DistributionServerService.
Update the values of the following properties in this element:

Property	Description
DownstreamScheme	Enter either http or https depending on the binding you chose.
Port	Enter the DEX Server port.

Apply the changes

Restart the following services to apply the changes:

Tricentis.DistributedExecutionService
Tricentis.GatewayService
ConsulService

Change import results mode

As of Tricentis Tosca 14.2 LTS, you no longer have to create results folders for your TestEvents. Tosca automatically saves results to the respective ExecutionLists. However, the upgrade process doesn't delete any existing results folders or results.

If you want to continue using results folders from Tricentis Tosca 14.1 STS or earlier, you can configure the Automation Object Service to do so.

To configure Tosca Distributed Execution with AOS for results folders, follow the steps below:

After the upgrade, access the machine that holds Tosca Server.
Open the appsettings.json file. By default, this file is located at C:\Program Files (x86)\TRICENTIS\Tosca Server\AutomationObjectService.
Go to the setting ImportResultsMode and change the value from ExecutionLog to TestMandate.

{
  "AutomationObjectServiceConfig": {
    "ImportResultsMode": "TestMandate",
    "DexBaseUrl": "http://localhost:12345",
    "DexCallTimeout": 30000,
    "MaxWorkspaceConnections": 10,
    "SendRequestRetryAttempts": 1,
    "SendRequestRetryInterval": 5000,
    "TaskCallTimeout": 3600000,
    "TcApiWorkspaceFolder": "%TRICENTIS_PROJECTS%\\Tosca_Workspaces",
    "Workspaces": [
      {
        ...
      }
    ]
  },
                                                        

Save and close the file.
Restart the service Tricentis.ToscaAutomationObjectService in the Windows Task Manager.

For more information on results folders, see the Tricentis Tosca 14.1 STS manual.