Set up Tosca Distributed Execution with AOS | HTTPS

This chapter describes how to install and set up Tosca Distributed Execution with AOS (Automation Object Service) with HTTPS.

For information on other setup options, see the chapters below. All chapters include the necessary set-up steps for Unattended Execution or a proxy server.

Before you start

If you haven't yet, check out the following chapters:

After the setup

You can further customize Tosca Distributed Execution features after the setup. Explore additional configuration options in the following chapters:

Setup process

The subsequent chapters describe each setup step in detail. They are listed in the order that Tricentis recommends for your setup process.

Install DEX Server

The Tosca Distribution (DEX) Server is part of the Tosca Server.

To install the DEX Server, you need to install Tosca Server on the machine where you want the DEX Server.

For information on how to install Tosca Server, see chapter "Install Tosca Server".

Set up the DEX Server via Installer

If you install Tosca Server via Installer, you need to perform the following steps to set up the DEX Server:

  1. Make sure to select the relevant server feature(s):

    Distribution Server and Administration Console

    The Administration Console consists of several services. You need some of these services for Tosca Distributed Execution.

  2. To specify an HTTPS binding, select HTTPS on the Tricentis Tosca shared Settings screen.

  3. Finish the Tosca Server installation.

  4. Set up the HTTPS binding for Tosca Server and its features as described in chapter "Use Tosca Server with an HTTPS binding".

    • Define a certificate in the IIS Manager.

    • Adapt the SSL settings.

    • Start the Tosca Server website.

  5. Open the file appsettings.json, which is located at C:\Program Files (x86)\TRICENTIS\Tosca Server\DexAdmin. Perform the following changes:

    • Set the "Scheme" to https.

    • Insert a valid certificate thumbprint inside the quotation marks that follow "Thumbprint".

  6. Open the file appConfig.json, which is located at C:\Program Files (x86)\TRICENTIS\Tosca Server\DexAdmin\Frontend\assets. Perform the following actions:

    • Change the address protocol for baseUrl and landingPageUrl from http:// to https:// .

    • Restart the services Tricentis.DistributedExecutionService and Tricentis.DistributedExecutionMonitor in the Windows Task Manager.

  7. Execute the file _SetHttpsCertificate.cmd as an administrator, which is located at C:\Program Files (x86)\TRICENTIS\Tosca Server\DEXServer. When prompted, enter a valid certificate thumbprint.

  8. Start the Tricentis Service Configuration.

  9. In the Tricentis Service Configuration, go to the Tricentis Automation Object Service tab.

  10. Enter the address and port of the DEX Server into the Distribution Server Address field.

    Note that the address has to match the address in your HTTPS certificate.

    The default DEX Server port number is 5007. If you change the DEX Server port number, update its address accordingly: https://<address>:<port>.

  11. If you plan to integrate Tricentis Tosca with Elastic Execution Grid, make sure to fill out the settings in the Elastic Execution Grid integration section of the Tricentis Automation Object Service tab.

  12. Populate the field Certificate Thumbprint in the following tab(s):

    • Tricentis Tosca Server Landing Page

    • Tricentis Service Discovery

    • Tricentis Administration Console

    • Tricentis Authentication Service

    • Tricentis Automation Object Service

  13. Optionally, you can configure different ports than the default ports for your services.

Set up the DEX Server in unattended mode

If you install Tosca Server in unattended mode, you need to perform the following steps to set up the DEX Server:

  1. Make sure to select the relevant server feature(s):

    _4DEXServer , _5TestEventMonitor, and _10AdministrationConsole

    The Administration Console consists of several services. You need some of these services for Tosca Distributed Execution.

  2. To specify an HTTPS binding, add the MSI command USE_HTTPS=1.

  3. Finish the Tosca Server installation.

  4. Set up the HTTPS binding for Tosca Server and its features as described in chapter "Use Tosca Server with an HTTPS binding".

    • Define a certificate in the IIS Manager.

    • Adapt the SSL settings.

    • Start the Tosca Server website.

  5. Open the file appsettings.json, which is located at C:\Program Files (x86)\TRICENTIS\Tosca Server\DexAdmin. Perform the following changes:

    • Set the "Scheme" to https.

    • Insert a valid certificate thumbprint inside the quotation marks that follow "Thumbprint".

  6. Open the file appConfig.json, which is located at C:\Program Files (x86)\TRICENTIS\Tosca Server\DexAdmin\Frontend\assets. Perform the following actions:

    • Change the address protocol for baseUrl and landingPageUrl from http:// to https:// .

    • Restart the services Tricentis.DistributedExecutionService and Tricentis.DistributedExecutionMonitor in the Windows Task Manager.

  7. Execute the file _SetHttpsCertificate.cmd as an administrator, which is located at C:\Program Files (x86)\TRICENTIS\Tosca Server\DEXServer. When prompted, enter a valid certificate thumbprint.

  8. Start the Tricentis Service Configuration.

  9. In the Tricentis Service Configuration, go to the Tricentis Automation Object Service tab.

  10. Enter the address and port of the DEX Server into the Distribution Server Address field.

    Note that the address has to match the address in your HTTPS certificate.

    The default DEX Server port number is 5007. If you change the DEX Server port number, update its address accordingly: https://<address>:<port>.

  11. If you plan to integrate Tricentis Tosca with Elastic Execution Grid, make sure to fill out the settings in the Elastic Execution Grid integration section of the Tricentis Automation Object Service tab.

  12. Populate the field Certificate Thumbprint in the following tab(s):

    • Tricentis Tosca Server Landing Page

    • Tricentis Service Discovery

    • Tricentis Administration Console

    • Tricentis Authentication Service

    • Tricentis Automation Object Service

  13. Optionally, you can configure different ports than the default ports for your services.

Install Tosca Commander

You need to install the full Tosca Commander client on the following machines:

  • All machines on which you want to create TestEvents and trigger their execution.

  • The machine that holds the Tosca Distribution Server.

For information on how to install Tosca Commander, see chapter "Install Tricentis Tosca".

Install Agents

The Agent installation is part of the Tricentis Tosca installation.

To install an Agent, you need to install Tricentis Tosca on every machine that should act as an Agent.

During the installation, you can select one of the following Agent types:

  • An Execution Agent, which can execute TestCases created with Engines 3.0.

  • A full client installation of Tosca Commander. These Agents can execute TestCases created with Engines 3.0 and Classic engines.

To install an Agent, follow the steps below:

  1. Start the installation of Tricentis Tosca.

  2. On the Type screen of the Tricentis Tosca installer, select your Agent type:

    • To install an Execution Agent, select Execution Agent.

    • To install the full client, select Tosca Commander.

Select an Agent type in the Tricentis Tosca installer

  1. Follow the instructions of the Tricentis Tosca installer to complete the installation.

Connect the Agents

Next, enable communication between the Agent and the DEX Server. You need to do this on every Agent machine.

To establish the connection, follow the steps below:

  1. On the Agent machine, open the ToscaDistributionAgent.exe.config file. By default, this file is located at %TRICENTIS_DEX_AGENT_HOME%.

  2. In the system.ServiceModel section, perform the following actions:

    • Change the security mode to Transport.

    • Enter the endpoint address of the DEX Server:

      https://<server IP address or host name>:<port>/DistributionServerService/CommunicationService.svc

      If you use an IPv6 address, the server address has to contain the IP address instead of the host name.

<system.serviceModel>
    <bindings>
        <basicHttpBinding>
            <binding name="BasicHttpBinding_ICommunicationService" sendTimeout="Infinite" maxBufferPoolSize="2147483647" maxBufferSize="2147483647" maxReceivedMessageSize="2147483647">
                <readerQuotas maxDepth="2147483647" maxStringContentLength="2147483647" maxArrayLength="2147483647" maxBytesPerRead="2147483647" maxNameTableCharCount="2147483647"></readerQuotas>
                <security mode="Transport"></security>
            </binding>
        </basicHttpBinding>
    </bindings>
    <client>
        <endpoint address="https://localhost:80/DistributionServerService/CommunicationService.svc"
                binding="basicHttpBinding" bindingConfiguration="BasicHttpBinding_ICommunicationService"
                contract="CommunicationServiceReference.ICommunicationService"
                name="BasicHttpBinding_ICommunicationService" />
    </client>
</system.serviceModel>
  1. If you use a self-signed certificate, enter the following code within the Configuration tags:

Copy
<system.net>
    <settings>
        <servicePointManager checkCertificateName="false" checkCertificateRevocationList="false" />
    </settings>
</system.net>
  1. If you want to use a proxy server, establish the communication between Agent and proxy. This step is only necessary if you want to use a proxy server. If not, you can skip it.

    To establish the connection, modify the settings ProxyAddress, ProxyUsername, and ProxyPassword in the userSettings section.

<userSettings>
  <Tricentis.DistributionServer.Properties.Settings>
  ...
    <setting name="ProxyAddress" serializeAs="String">
      <value>https://11.1.11.11:1111</value>
    </setting>
    <setting name="ProxyUsername" serializeAs="String">
      <value>User1</value>
    </setting>
    <setting name="ProxyPassword" serializeAs="String">
      <value >Proxypassword</value>
    </setting>
  </Tricentis.DistributionServer.Properties.Settings>
</userSettings>
  1. Save and close the file.

  2. Start your Agent.

Set up Agent RDP access

To set up the Agent to allow RDP access for Unattended Execution, follow the steps below:

  1. Open the Distributed Execution Monitor.

  2. In the Agent View, click on in the row of the Agent that you want to configure. This opens the Configuration window.

  3. In the Configuration window, go to the Unattended Execution tab and perform the following actions:

    • Select Allow to open remote connections to this agent.

    • Select Use RDP connection.

    • Populate the following fields:

Field

Optional?

Description

Username

 

User name of the Windows user who runs the Agent.

Password

 

Password of the Windows user who runs the Agent.

Desktop Width

yes

Change the default width of the remote desktop in pixels. The default value is 1600.

Desktop Height

yes

Change the default height of the remote desktop in pixels. The default value is 1200.

Color Depth

yes

Change the default color depth of the remote desktop. The default value is 16.

Configure Unattended Execution

  1. Click Save and close the window.

Activate Distributed Execution with AOS

To use Distributed Execution with AOS, you need to activate it on the Tosca Distribution Server.

To activate Distributed Execution with AOS, follow the steps below:

  1. Open the file Tricentis.DistributionServerService.exe.config. By default, this file is located at C:\Program Files (x86)\TRICENTIS\Tosca Server\DEXServer.

  2. Navigate to the section Tricentis.DistributionServer.Properties.Settings.

  3. Change the value of the setting EnableWorkspacelessExecution to True.

<setting name="EnableWorkspacelessExecution" serializeAs="String">
    <value>True</value>
</setting>
  1. Save and close the file.

  2. Restart Tricentis.DistributedExecutionService in the Windows Task Manager.

Administer licenses

You need to have a valid Tosca license on all machines where you install Tricentis Tosca:

  • Each Agent machine requires an ExecutionOnly license.

  • Each machine on which you create tests and trigger their execution needs an appropriate Tosca license. Which license you need depends on the kind of tests you create. For information on licensing options, contact Tricentis Sales.

  • To set up the AOS workspace on the DEX Server, you need a valid Tosca license.

    You only need this license to set up the workspace. Once Tosca Distributed Execution is up and running and you don't work with the DEX Server workspace, you no longer need a license for the server machine.

For information on how to set up licensing on your machines, see chapter "License management".

Set up workspaces

To use Tosca Distributed Execution with AOS, you need to set up separate multi-user workspaces.

These workspaces must have access to one common repository.

  • One multi-user workspace on each machine on which you create and trigger your tests. These are your user workspaces.

  • One multi-user workspace for the Automation Object Service (AOS). This workspace only exists to give the AOS access to the repository.

Create user workspaces

To set up your user workspaces, follow the steps below:

  1. Create them.

    • If you are already working with Tricentis Tosca and have a repository and workspaces, you can skip this step.

    • If you have not yet set up your repository and workspaces, do so now (see chapter "Create multi-user workspaces"). You need one workspace on every machine where a user should create and execute tests.

      When you create the very first workspace, make sure that the workspace name only contains alphanumeric characters and underscores _.

      Don't use any other special characters.

  2. Open any workspace that is connected to the repository.

  3. Go to Home->Project.

  4. In the Details tab, take note of the project root name.

    You need this name later, when you set up the workspace for the Automation Object Service.

If you have skipped step 1 because you already have a repository and workspaces, check the project root name.

The name must only contain alphanumeric characters and underscores _.

If your project root name contains any other special characters, you have to change it:

  1. Check out the project root element.

  2. Overwrite the existing name with the new name.

  3. Check in.

Check the project root name

Create the AOS workspace

This workspace gives the Automation Object Service (AOS) access to all objects in the common repository, such as your TestEvents and configurations.

Do not treat this workspace as a regular "working" workspace for users. It serves as a background workspace for the Automation Object Service.

If you start working in this workspace, you will break the Automation Object Service.

Do not use REST services with your AOS workspace; they will also break the Automation Object Service. The only exception to this rule is the AOS REST API, which allows you to perform AOS workspace tasks.

To set up your AOS workspace, follow the steps below:

  1. On the Distributed Execution (DEX) Server machine, open Tosca Commander.

  2. Go to Project->New. This opens the Create new workspace window.

  3. In this window, perform the following actions:

    • Select your repository type from the drop-down menu.

      Do not select a server repository. AOS does not work with Tricentis Server Repository workspaces.

    • Select Use existing repository and enter the connection string to your repository.

    • In the Select name for new workspace field, enter the project root name that you noted in your user workspace.

      Note that this workspace name must be unique on the DEX Server. You cannot have another workspace with the same name on the DEX Server.

      If you already have a workspace with the same name on the DEX Server, you must change the name of the other workspace.

    • Click OK to create the workspace.

    • Ensure that you have not selected Create slim workspace. The AOS workspace cannot be a slim workspace.

Create the AOS workspace

  1. Open the Tricentis Service Configuration.

  2. In the Automation Object Service tab of the Tricentis Service Configuration, populate the following fields:

Field

Description

Workspace Folder

Path to the folder that contains the AOS workspace.

By default, the path is %TRICENTIS_PROJECTS%\Tosca_Workspaces.

Workspace Root Name

Name of the AOS workspace.

Username

Name of the user to access the workspace.

This user must have all necessary access and permissions for all objects in this workspace.

Password

Password of the user.

Add workspace in Tricentis Service Configuration dialog

  1. Click Save and close the Tricentis Service Configuration dialog.

Configure Distributed Execution with AOS for multiple common repositories (optional)

By default, Tosca Distributed Execution works with one common repository.

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

Connect Tosca Commander

Now you need to specify the connection between Tosca Commander and the DEX Server.

You need to do this on all machines where you want to create tests and trigger executions.

Alternatively, you can create project settings. In this case, the settings apply to all workspaces connected to the repository.

To connect Tosca Commander, follow the steps below:

  1. Open Tosca Commander.

  2. Go to Project->Settings->Commander->DistributedExecution->Server.

  3. As the value of the setting EndpointAddress, enter the address of the DEX Server:

    https://<server IP address or host name>:<port>/DistributionServerService/ManagerService.svc

    The default DEX Server port number is 5007.

    If you use an IPv6 address, the server address has to contain the IP address instead of the hostname.

  4. If you want to use a proxy server, populate the value of the setting Proxy with the complete network address of the proxy server:

    https://<server IP address or host name>:<port>

  5. Go to Project->Settings->Commander->DistributedExecution->Monitor Url.

  6. As the value of the setting Url, enter the address of the machine that holds the Tosca Distributed Execution Monitor:

    https://<server IP address or hostname of the machine that holds the DEX Monitor>:<port>/Monitor/

    The default DEX Monitor port number is 5008.

  7. Go to Settings->Tricentis Services.

  8. As the value of the setting ServerEndpointAddress, enter the address of Tricentis Service Discovery:

    https://<server IP address or host name>:<port>

    By default, Tricentis Service Discovery is installed on the same machine as the Tosca Distribution Server on port 5002.

Modify the settings

Set up parallel execution

This last step of the Tosca Distributed Execution setup is optional.

In it, you create a project root setting that allows users to define how Tosca should run ExecutionLists.

If all TestCases in an ExecutionList are independent of each other, users can split an ExecutionList between Agents. The Agents then execute the TestCases simultaneously, which speeds up the test run.

To create the project root setting, follow the steps below:

  1. Open a workspace which has access to the common repository and go to Home->Project.

  2. Check out the project root element.

  3. Go to the Properties definition tab.

  4. In the Properties definition tab, right-click ExecutionList and select Create Property from the mini toolbar.

  5. Rename the new property to TCDistribution.

  6. Ensure that Visible is selected.

TCDistribution property for all ExecutionLists

Perform AOS workspace tasks

Tricentis offers a REST API for the Automation Object Service.

The AOS REST API allows you to perform the following tasks on your AOS workspace:

  • Check what's happening in a particular AOS workspace.

  • Compact an AOS workspace.

    By default, there is no compact workspace task on the AOS workspace. As a result, retrieving and persisting data may slow down over time.

    To avoid this, Tricentis recommends that you compact your AOS workspace(s) regularly.

  • Close and re-open an AOS workspace.

    Tricentis Tosca treats the Automation Object Service as a separate workspace user. When you trigger an execution, AOS opens the workspace as a user. This locks the workspace; no other user can access it.

    If you need to check something in this particular workspace, for instance if the workspace isn't performing as expected or you need to adapt permissions, you can manually close the workspace. Closing the workspace doesn't discard anything. AOS finishes the running tasks and queues everything else.

    Once you are done, you must re-open the workspace. Then AOS can finish the queued tasks.

Access the AOS REST API

To access the AOS REST API, enter the following URL:

https://<IP address or hostname of the Tosca Distribution Server>:<AOS port>/swagger

  • If you use an IPv6 address, you must use the server IP address, not the hostname.

  • If you access the REST API from the machine that holds the Tosca Distribution Server, you can enter localhost instead of IP address/hostname.

  • Replace <AOS port> with the AOS port you have specified in the Service Configuration.

Perform your AOS workspace tasks

For information on AOS REST API requests and responses, see the Swagger documentation in the AOS REST API.

What's next

Now that you've set up Tosca Distributed Execution, you're ready to start testing! For more information, see chapter "Create and execute TestEvents".