Skip to main content

Integrations

There are different ways to connect to third-party software from a VIKTOR app. Some external programs run locally, while others are accessed online.

Summarizing the different methods to integrate with third-party software:

IntegrationInstallationUsageAdmin required
Personal workerlocalpersonalno
Organization workerlocalsharedyes
API tokenscloudsharedno
OAuth 2.0cloudpersonalyes

More information can be found inside the Develop apps page.

Workers​

A worker is a program created by VIKTOR 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.

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

Installation​

Environment administrators can set up integrations for the entire organization, while developers and users (unless disabled*) can create and set up integrations for personal use only. Select the correct tab below and follow the steps.

*

The use of personal workers in production workspaces is allowed by default. Developers can disable it for their maintained apps in the app edit dialog.

App Builder

Using the ETABS, PLAXIS, Revit, SAP2000, Tekla, or Python worker integrations inside the App Builder requires a separate opt-in, because there the agent generates and runs that code without a review step. See the App Builder guide for details.

A personal worker connects the software that is installed on your own machine, for your own use. Personal workers are installed and managed with VIKTOR Desktop: one app to install, authenticate, run, and monitor all your personal workers.

  1. Download VIKTOR Desktop (a single signed .msi Microsoft Installer) from the "My integrations" tab in your personal settings, or directly from the VIKTOR Desktop page, and install it (first time only)
  2. Launch VIKTOR Desktop and log in with your VIKTOR account via the browser
  3. Click "Add" and select the software of choice
  4. Follow the instructions to complete the worker configuration
  5. Start the worker

See the VIKTOR Desktop page for details.

Existing workers are not migrated

Personal workers that were installed with the previous per-worker installers keep running, but they are not migrated into VIKTOR Desktop. To fix this, re-install the worker via VIKTOR Desktop: add and configure it again, and uninstall the old installation using the "Add or remove programs" feature of Windows to avoid two workers with different configurations competing for the same tasks. See Migrate existing workers to VIKTOR Desktop. New personal workers can only be added through VIKTOR Desktop: the per-worker installer download and the connection-key flow are no longer available on the "My integrations" page for personal workers.

Operation​

Personal workers are started, stopped, and managed inside VIKTOR Desktop. The options below apply to organization workers and personal workers installed with the previous per-worker installers.

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.
  • (requires Administrator privileges) 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​

note

Creating a scheduled task requires Administrator privileges on your machine.

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 <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 <software package> <version>\viktor-worker-...-<version>.exe
    3. Start in (optional): C:\Program Files\Viktor for <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​

Personal workers managed with VIKTOR Desktop have formatted logs inside the app. The log-file locations below apply to organization workers and personal workers installed with the previous per-worker installers.

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.

Upgrading / Revoking​

An update of the VIKTOR worker might become available. For organization workers, 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.

For personal workers, updating is done via VIKTOR Desktop: when a worker update is available, VIKTOR Desktop prompts you to update, and once you confirm, the worker updates automatically. There is no per-worker installer to uninstall or rerun. Personal workers installed with the previous per-worker installers cannot be re-installed this way anymore, as the per-worker installers are no longer available: migrate the worker to VIKTOR Desktop to keep receiving updates.

If the worker is no longer used or needed, please contact your environment administrator to revoke the worker through the administration panel or remove personal workers through the "My integrations" tab. Subsequently, the worker can be uninstalled from the machine.

For personal workers managed with VIKTOR Desktop, removal and revocation are done per user: stop or remove the worker inside the app, and revoke access for the machine by clicking your profile in the top-right corner of VIKTOR Desktop and selecting "Log out". There are no per-worker connection keys to revoke.

VIKTOR Desktop itself is updated the same way as its workers: when a new version of the app is available, you are prompted to update, and once you confirm, it updates automatically. There is no need to reinstall the .msi.

Security​

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.

For personal workers, VIKTOR Desktop authenticates with a browser-based login (OAuth 2.1 with PKCE) that is bound to your VIKTOR account, instead of per-worker connection keys. See the requirements on the VIKTOR Desktop page for the details relevant to IT administrators.

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

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

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

OAuth 2.0 integrations​

OAuth 2.0 (Open Authorization) is an industry-standard protocol that allows secure authorization to third-party software, without sharing their credentials. This enables users to access their third-party data from within a VIKTOR application, without exposing their login password.

How it works (on a high level)​

Once the integration is set up by an organization admin and added to an application by a developer, the end user will be able to log in to the third-party software. Here is how it will work for an end user on a high level.

  1. User initiates connection: In an application, VIKTOR will redirect the user to the third-party software to request access.
  2. User grants permission: The user logs in (if not already), reviews the access request, and approves or denies it.
  3. Temporary authorization code issued: If approved, the third-party software sends a short-lived code to VIKTOR.
  4. Token exchange: VIKTOR exchanges that code for an access token — a credential we can use to access specific data or perform limited actions on behalf of the user.

Architecture​

OAuth 2.0 enables secure, token-based access to third-party services without exposing user credentials. When a VIKTOR application needs to access external data, OAuth 2.0 facilitates a secure handshake between VIKTOR, the third-party service, and the end user. The process uses industry-standard security measures including encrypted communication, time-limited tokens, and scope-limited permissions to ensure that access is both secure and controllable.

The diagram below shows how the protocol communicates with VIKTOR.

Diagram of OAuth 2.0 integration protocol

Requirements​

  • The third-party software to integrate with should support OAuth 2.0 in accordance with RFC 6749.
  • OAuth 2.0 URLs should use HTTPS encryption.
  • Support for PKCE (Proof Key for Code Exchange) is recommended for enhanced security.
  • Refresh tokens should be supported for long-lived integrations without requiring frequent re-authentication, so it is highly recommended to add offline-access scope whenever possible.
  • Scope-based permissions can be set to limit access to only specific data and operations required by the VIKTOR application.

Creating an OAuth 2.0 integration​

caution

You need to be an environment administrator in order to set up an OAuth 2.0 integration.

Environment administrators are able to set up the OAuth 2.0 integration for all applications. Developers are able to use existing integrations in their applications. The diagram below outlines how administrators, users, and developers engage with OAuth 2.0 integrations at different stages.

Diagram of OAuth 2.0 flow

Go to our list of supported software and choose the software that you would like to integrate with for the installation guide.

  1. Navigate to the "Integrations" tab in the Administrator panel

  2. Select the "OAuth 2.0 integrations" tab

  3. Click "Add OAuth 2.0 integration"

  4. Follow the steps provided in the modal

    1. Select the software of choice

    2. Fill in the basic information of the integration, including the app that the integration should be available to. You can choose to limit the integration to specific apps or allow all apps on the environment to use it.

    3. Fill in the credentials needed to establish a connection. These credentials can found in your third-party software app.

Credentials required for an OAuth 2.0 integration

Client secret

For security reasons, the client secret will not be retrievable from within VIKTOR once the integration is created.