Skip to main content

Setting up a worker

A worker is a program that can be used to establish a connection between the VIKTOR platform and third-party software that runs outside the platform. With a worker a user is able to execute tasks using the third-party software and retrieve the results through the VIKTOR application.

A worker can be installed using the .msi (Microsoft Installer) file. Please select your integration of choice and use the button below to download the installer.

Download installer

Architecture​

The component diagram below shows how the VIKTOR worker communicates with the VIKTOR cloud. There is a slight difference between production and development environments as shown in Figure 1. Communication between the worker and the VIKTOR cloud is established by a TCP connection encrypted using TLS 1.2. This connection originates from the worker to the VIKTOR cloud. In this manner it is not required to open ports to the public internet on the machine or company network.

Simplified component diagram for VIKTOR platform

Requirements​

This section outlines the requirements of the VIKTOR worker. The VIKTOR worker can be installed on any machine that is used to run the third-party software to be integrated with.

Minimum requirements​

  • Processor: 64-bit AMD or Intel
  • Operating system: Windows
  • You have administrator rights on the machine (required for installation, for normal operation a user account can be used)
  • The third-party software that is to be integrated is installed and licenses are available
  • The VIKTOR worker requires outgoing TCP access to the internet over port 443. This is same port that is used for internet using HTTPS.
  • Processor: 64-bit AMD or Intel
  • Operating system: Windows Server
  • You have administrator rights on the machine
  • The third-party software that is to be integrated is installed and licenses are available
  • The VIKTOR worker requires outgoing TCP access to the internet access over port 443. This is same port that is used for internet using HTTPS.

Considerations for server requirements​

The requirements posed by the VIKTOR worker are negligible. the system requirements of the third-party software that is integrated with are leading. The recommended requirements for these software packages should provide you with a good starting point.

Often performance bottlenecks can be traced back to the following causes:

  • The machine is not running an operating system that is tailored to servers (for example Windows Server). This will often lead to a lower uptime because of unexpected updates or reboots.
  • Engineering software often does not use parallelization to write results, the only thing that you can facilitate in this good read and write speed. We therefore recommend equipping the server with SSDs.
  • Not all engineering software uses multiple cores and some programs have been built for 32-bit processors instead of 64-bit processors. In this case the maximum amount of RAM that can be used is 4GB. In conclusion more cores and more RAM does always improve performance.
  • Most engineering software only use graphics cards (GPU) for the the user interface and not to solve models, which is restricted to the central processing unit (CPU). Therefore, it might not be required to equip the server with high- performance GPUs.
  • If hardware is no longer a bottleneck the amount of available licenses might be the bottleneck. This can happen when all licenses are in use by other users. Some software allows pinning the license to make sure it is always available.
  • VIKTOR applications allow for parallelization of external analysis tasks with the worker. If enough licenses are available and the machine has enough capacity the worker can be configured to execute tasks in parallel.

Credentials​

A worker requires credentials to authenticate with the VIKTOR platform. These credentials are generated for a specific integration and environment and can be re-uses if a newer version of the worker (of the same type) is installed. Environment administrators are able to generate credentials for a specific integration in the administrator panel:

In the next modal, the credentials are generated and should be copied immediately as VIKTOR will not preserve this data for security reasons.

Installation​

In the introduction of this page you are able to download the worker installer for your integration of choice. The installer starts an installation wizard from which the worker can be configured. Administrator rights on the machine are required to perform the installation. During installation, you are guided through the following steps:

  1. Specification of the installation directory. The standard directory that is used for the installation is: C:\Program Files\Viktor\Viktor for <application> <software package> <version>

  2. Configuration of the worker. For some integrations the worker requires additional information to successfully execute tasks. Using the installation wizard you will be asked to fill the required information step-by-step.

  3. It is possible to configure the worker in such a way that multiple parallel routines can be started. This allows the worker to perform several tasks in parallel. During installation, you will be asked to supply the amount of parallel routines that the worker needs to start in the field 'number of parallel instances'.

  4. During the installation you are asked to insert the credentials for the worker.

  5. During installation, you can choose to create a ‘scheduled task’ for the worker. When this option is selected the VIKTOR worker will be automatically launched after a (re)boot of the server. We advise to use this option to make sure that the VIKTOR worker will automatically connect to the platform.

    note

    It is not possible to run a VIKTOR worker that integrates with SCIA Engineer as a scheduled task. For more information see here

  6. Subsequently, the user is presented the option to launch the VIKTOR worker. This allows you to inspect whether the worker is successfully configured and able to connect to the platform.

  7. Finally, you can choose to restart the server. If a scheduled task has been created in step 3 the worker will automatically be launched upon (re)boot. If you do not wish to restart the server you can manually start the scheduled task using the Windows Task Scheduler.

Operation​

After installation the worker can be operated in two ways, namely:

  • Starting the worker manually via the desktop shortcut. During installation a shortcut to the VIKTOR worker is created on the desktop. You can start the worker by double-clicking the shortcut.
  • As scheduled task. During installation, you are asked to create a scheduled task for the worker. If this option has been selected the worker will automatically start after (re)boot of the server. We advise to run the worker as a scheduled task to make sure it is always connected to the platform.

Creating a scheduled task manually​

When you have selected the option ‘Create scheduled task’ during installation of the worker, the worker will launch upon (re)boot of the server. You can check if a scheduled task has been created using the Windows Task Scheduler. You will need to start the Task Scheduler with administrator rights. The program can be started using the 'Start Menu' or through 'Start' > 'Windows Administrative Tools' > 'Windows Task Scheduler'. If the scheduled task for the VIKTOR worker is not present you can create a task as follows:

  1. Select 'Create task' in the side menu . This action will open a new window.
  2. Supply a name for the task in the tab 'General', for example Viktor for <application> <software package> <version>
  3. Under 'Security options' :
    1. Select a user with the appropriate execution rights in the field 'When running the task, use the following user account'
    2. Check 'Run whether user is logged on or not'
      • To use this option the user account requires 'Log on as a batch job' rights
  4. Add a new trigger on the tab 'Triggers' using the 'New…' button.
    1. Begin the task: At startup
  5. Add a new action on the tab 'Actions' using the 'New…' button.
    1. Action: Start a program.
    2. Program/script: C:\Program Files\Viktor for <application> <software package> <version>\viktor-worker-...-<version>.exe
    3. Start in (optional): C:\Program Files\Viktor for <application> <software package> <version>\
  6. Uncheck 'Stop the task if it runs longer than' in the tab 'Settings'
  7. Save and start the task.

Activity monitoring​

A log is kept displaying all activity of the worker. This log shows at what time tasks have been started and completed. The location of the log file depends on the environment variables of the server. The logs are written to the C:\ProgramData folder or the first of the following variables %TMP%, %TEMP% en %USERPROFILE%. In the exceptional case that none of these variables are set the worker stores the log files in the Windows folder.

Shared licenses​

The VIKTOR worker only uses a license during execution of a task (e.g. running a simulation using the software package). If the program uses floating licenses this means that a licenses will only be taken from the license pool during the task. The license will be released upon completion of the task.

Troubleshooting​

If the worker is not able to connect to the platform or successfully complete tasks the following checks can be performed to fix the problem yourself:

  1. Inspect the log file. You can find this file in C:\ProgramData\Viktor\Viktor for <application> <software package> <version>\logs\worker.log. All errors that the worker encounters are logged in this file. In the exceptional case that %ProgramData% is not defined as an environment variable the log files are written to a different directory. In that case you can find the log in one of the following: [ %TMP% | %TEMP% | %USERPROFILE% | C:\Windows ] \Viktor\Viktor for <application> <software package> <version>\logs\worker.log.
  2. Inspect the configuration file of the worker. You can find this file in C:\Program Files\Viktor\Viktor for <application> <software package> <version>\config.yaml, unless you have chosen a different installation directory during installation of the worker.
  3. Inspect the availability of the licenses of the third-party software that is to be integrated with. In most cases this can simply be done by manually launching the program via the start menu.

Upgrading / Revoking​

An update of the VIKTOR worker might become available. In that case you can install the new version as follows:

  1. Uninstall the old version of the VIKTOR worker using the 'Add or remove programs' feature of Windows.
  2. Install the new version of the worker by running the Windows Installer and completing the installation wizard.

If the worker is no longer used or needed, please contact your environment administrator to revoke the worker through the administration panel. Subsequently, the worker can be uninstalled from the machine.

Supported integrations​

The table below shows the supported software packages that can be used in combination with a VIKTOR worker. In this table you can see whether the software package allows tasks to be executed in parallel. This means that multiple tasks can be executed simultaneously. The amount of licenses that are required to execute these tasks depends on the third-party software package. A license will only be used during execution of a task. However, in the worst case (i.e. all routines are executing a task at the same time) the amount of licenses will be equal to the amount of routines that have been started by the worker.

IntegrationParallelizationLicenses requiredWarningsOther considerations
AxisVMYes1 per routine
D-FoundationsYes1 per routine
D-Geo StabilityYes1 per routine
D-SettlementYes1 per routine
D-Sheet PilingYes1 per routine
D-StabilityYes1 per routine
ExcelYes1 per routine
GenericYes 1Depends on executableThis integration allows execution of executables on the server (within the boundaries of the configuration). Clear agreements should be made with the developer of the applicationThe configuration file needs to be completed manually
GRLWEAPUnknown 2Unknown 3This integration requires the GRLWEAP batch mode processing license
IDEA Statica ConcreteUnknown 2Unknown 3This integrations requires IDEA StatiCa Concrete v10.1 or newer
RFEMUnknown 2Unknown 3
SCIA EngineerNo1 per workerSee known issues

Security considerations​

In this section we highlight the measures taken to incorporate security in the design of the VIKTOR worker.

First of all, the worker only requires an outgoing connection to connect to the platform. Therefore, there is no need to open ports for incoming traffic or port-forwarding of incoming traffic to the machine from the outer network perimeter.

Secondly, the running the worker does not require administrator privileges to operate. Only during installation raised privileges are required.

Furthermore, a VIKTOR worker is built for a specific software package, so a worker is only able to perform one specific task. The exception to this is the generic worker, which we have developed to allow for integrations with software we do not have a specific integration with (yet). The following paragraph describes the way the generic worker can be used in more detail.

The generic worker can be used to execute executables on the machine. In order to prevent abuse, the executables that can be called using the worker are defined in the worker configuration file and thus are controlled by the administrator of the server. The configuration file can be found in C:\Program Files\Viktor\Viktor for <application> <software package> <version>\config.yaml, unless you have chosen a different installation location. The worker is not allowed to call any other executables than the ones defined in the configuration file. Furthermore, any additional arguments that are used to call the executable with are fixed. These arguments are defined in the configuration file as well. In conclusion the administrator of the server is in full control of the executables that can be called using the generic worker and can be limited to only those that are required to run the analyses required by the application.

Known issues​

SCIA Engineer​

The solver of SCIA Engineer cannot be executed from a Windows service or scheduled task, due to ‘session 0 isolation’. Therefore, it is required that the VIKTOR worker integration with SCIA Engineer run in a user environment. This implies that a user account should always be logged on to make sure that tasks can be completed successfully. The vendor of the software is aware of this problem and looking into ways to fix this.

In order to do this it is convenient to set up an account that logs on automatically upon (re)boot of the server. This account should have access to a SCIA Engineer license. To set up a VIKTOR worker to integrate with SCIA Engineer please proceed as follows:

  1. Create a new user account with appropriate access rights.
  2. Enable automatic logon for the account created in step 1, as described in this article. We want to stress that this logon procedure is “only advised when the computer has been physically protected and steps have been taken to prevent unauthorized users remotely accessing the register”.
  3. The VIKTOR worker is supplied as a Windows Installer (.msi file). You can configure the worker by completing the installation wizard.
  4. After installation a shortcut for the VIKTOR worker can be found on the Desktop and in the Start menu as Viktor for <application> <software package> <version>. By starting the application you enable the connection between the VIKTOR platform and the worker.
  5. It is also possible to create a scheduled task that runs the VIKTOR worker. The task should be run by the account created in step 1. Furthermore, make sure to check the box ‘Run only when the user is logged on’.

COM permissions​

Several workers communicate using Windows COM. The following integrations use COM:

  • Excel
  • AxisVM
  • RFEM

The user account running the workers needs to have the correct permissions. Although the permissions might be already correct for operating the worker from the desktop, running the worker as a scheduled task might require additional configuration. When you encounter problems it is helpful to inspect the 'Windows Logs' to see if any errors were raised during execution of the worker. The logs can be accessed using the following steps:

  1. Open 'Component Services' (Start > Component Services).
  2. Select 'Event Viewer (Local)'.
  3. Select 'Windows Logs'.
  4. Select 'System', this will open a list of logs of your system.
  5. Inspect these logs for any errors related to the usage of Windows COM, this can be done by looking at the source of the log, which will be labeled 'DistributedCOM'.

An error related to a lack of permissions might look like the example below:

Example of Windows error log

The information from this log can be used to correctly configure permissions. First of all, the permissions for the CLSID and APPID should be set in the registry. Please follow the steps below:

  1. Open the 'Registry Editor' as administrator.
  2. Go to Computer\HKEY_CLASSES_ROOT\CLSID\{INSERT_CLSID_FROM_LOG}. Use the right mouse button to select 'Permissions'.
  3. Add or select the user account you use to run the worker and select 'Full Control'. Click 'Apply' to store the new permissions.
  4. Go to Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Classes\AppID\{INSERT_APPID_FROM_LOG}. Use the right mouse button to select 'Permissions'.
  5. Add or select the user account you use to run the worker and select 'Full Control'. Click 'Apply' to store the new permissions.

Now the right permissions should be set in the DCOM config. Please follow the steps below to set the correct permissions:

  1. Open 'Component Services' as administrator and select DCOM Config (Console Root > Computer > My Computer > DCOM Config).
  2. To be able to see the corresponding AppIDs click 'View' and subsequently 'Detail', subsequently find the corresponding AppID from the event log.
  3. Click the entry with the right-mouse button and open 'Properties', select the 'Security' tab.
  4. Now select the option 'Customize' in 'Launch and Activation Permissions' and press 'Edit'.
  5. Add or select the user account you use to run the worker and select 'Local Activation' and close the window by clicking 'Ok'. Finally close the 'Properties' window by pressing 'Apply'.

Now the permissions should be configured correctly to run the worker from a local user account.

Microsoft Excel UI elements​

The scheduled task that is created by the installer to run analyses with Microsoft Excel is able to run without problems in most cases. However, when the scheduled task is run from the SYSTEM account with the setting 'Run whether user is logged on or not' it is not possible for Excel to load any UI elements. This will cause any macro that uses 'User forms' to hang. These forms are sometimes used for progress bars during macro calculations. We advise that any user forms are stripped from Excel workbooks that are used for analyses using the VIKTOR worker.

Microsoft has published an article with some considerations for server-side automation of Office programs, please read this article.

Microsoft Excel cells not updating​

There can be differences in the behaviour of a macro when running Excel headless as compared to using the GUI. Notably, if your macro changes the value of a given cell, the values of the cells that are dependent on that value will not be updated automatically if the GUI is not open. This can be fixed by using the Worksheet.Calculate function in your marco to make sure the cells are updated as needed. More information on how to use Worksheet.Calculate function can be found in this article

Footnotes​

  1. The Generic integration can only be run in parallel if the workingDirectoryPath is not specified. This means that a temporary working directory is created to run a job. ↩

  2. At the moment it is not clear whether this integration supports parallel routines. ↩ ↩2 ↩3

  3. In the worst case the number of required licenses is equal to the amount of routines started by the worker. ↩ ↩2 ↩3