Software integrations
VIKTOR allows you to perform analyses using third-party software directly from your app interface. This guide explains how to integrate external software into your VIKTOR application.
There are various ways to connect to third-party tools. Some software runs locally on the user's machine, while others are accessed through online servers. Each approach requires a different integration method, which will be covered in this guide.
Summarizing the different methods to integrate with third-party software:
| Integration | Installation | Usage | Admin required |
|---|---|---|---|
| Personal worker | local | personal | no |
| Organization worker | local | shared | yes |
| API tokens | cloud | shared | no |
| OAuth 2.0 | cloud | personal | yes |
Supported software
Currently, we provide dedicated integrations for the software packages listed in the table below. If the software package that you want to interact with is not listed below, you can make use of our generic integrations.
Whether or not the software package you want to integrate with is listed, please reach out to us if you need help setting up an integration through the Community Forum!
Workers
A lot of engineering software runs locally on your machine. While you could integrate with this software during development (the code runs on the same computer), this will break if your app is used by others in production. In production your app runs on a server and this server does not have access to your machine. Workers solve this issue.
A worker is a small application (executable) that is installed on the computer with access to the local software. It creates a secure connection with the VIKTOR platform, enabling the web applications to integrate with the local software and execute tasks.
A worker is always assigned to one or multiple apps and when executed will run in the background and wait for a 'task'. This task consists of the input(s) required for the software. When the worker receives the task, it will call the software and perform an analysis with the provided input(s). Meanwhile, the application from which the task is sent waits until the worker finishes the calculation and sends back the results. The following schematic shows this concept:
VIKTOR worker flow
Installation
Please follow the steps listed in installation to set up a worker.
Implementation example
Each worker integration makes use of viktor.ExternalProgram. The
ExternalProgram.execute method is the
trigger to send a task to the worker on the external machine.
The following piece of code shows an example implementation of an integration with SCIA Engineer:
import viktor as vkt
input_esa = ...
input_xml = ...
input_xml_def = ...
scia_analysis = vkt.scia.SciaAnalysis(input_xml, input_xml_def, input_esa)
scia_analysis.execute(timeout=300) # triggers the worker, wait until complete
results = scia_analysis.get_xml_output_file()
Multiple worker instances
The VIKTOR - worker interaction is configured such that it can easily be scaled up (or down). For example, the worker application can execute multiple instances (processes) of the software package.
Worker running multiple processes on single machine
Running parallel routines requires a worker version of at least v4.7.1 and should not be a generic worker.
A worker can also be executed multiple times across multiple different machines. Tasks are distributed randomly over the running worker instances, and thus multiple users can make use of the external integration at the same time.
Multiple workers across multiple machines
Parallel execution has to be supported by the software. Often each job will require an individual license of the software. So when 2 jobs run in parallel, this will probably require 2 software licenses as well. If no license is available, the worker will fail to execute the program and the external analysis will return a LicenseError to the VIKTOR application (unless a TimeoutError is returned first).
Worker status
Within the VIKTOR interface, a user can see the status of the connected workers via the icon in the top right corner:
This gives a user insights in:
- which workers are connected and available
- how many workers per external package are connected
- whether a worker is currently running a job or not
Worker status
Note that the worker status does not provide information about licenses being available or not.
Personal workers vs Organization workers
Personal workers connect software running on your personal computer to the VIKTOR cloud. This allows your own local tools to interact with VIKTOR securely.
Organization workers connect software running on your organization or cloud servers to the VIKTOR cloud. This allows for centralized, scalable, and shared connections that mutliple users within your VIKTOR environment can access.
| Integration | Installed on | Installed by | Purpose |
|---|---|---|---|
| Personal worker | Personal computer | Individual users | Connect local software |
| Organization worker | Organization's server | Admins | Connect organization-wide software |
API tokens
When you want to integrate with online software, you don't need a worker, but you do need to take care of authentication. Most online programms support the use of API tokens for external access. An API token is a substitute for the username and password in a manual login flow. This token (sort of password) should be kept secret and not stored in the source code. In VIKTOR you can insert these tokens through environment variables. This environment variable is available for all instances of this app and all users using this app.
OAuth 2.0
Some online software supports (or requires) a more elaborate authentication flow, called OAuth 2.0. OAuth 2.0 is a widely supported authorization protocol that allows users to grant third-party applications limited access to their data, without requiring them to share their passwords. In this type of integration, users are directed to an external login page to authenticate. The authentication is personalized and will only give access to parts of the external software that this specific user has access to.
Setting up and using an OAuth 2.0 integration is done as follows:
- Creating an OAuth 2.0 integration (admin)
- Implementing the integration in an app (developer)
- Using the integration by logging in (user)
VIKTOR provides both specific OAuth 2.0 integrations as well as a generic OAuth 2.0 integration, giving you the possibility to connect to any external software package that supports this protocol.
1. Creating an OAuth 2.0 integration (admin)
A VIKTOR admin creates an OAuth 2.0 integration on the integrations page of the environment. This integration defines the connection between VIKTOR and the external software and needs to be assigned to specific applications that can use this integration.
Each integration will get a unique name (e.g. databricks-workspace-1), which is used by the developer in the next step. More information on creating an OAuth 2.0 integration by the admin can be found here.
2. Implementing the integration in an app (developer)
With the integration name, the developer can start the implementation. First the integration is added in the config file. This is used by the platform to know that this app needs an integration and to trigger a login button for the user.
viktor.config.toml
oauth2_integrations = [
"databricks-workspace-1"
]
Secondly the logic that uses the integration can be implemented in the app. Often external software will provide examples and/or a Python SDK, making it easier to implement. In order to obtain the necessary token for authentication, you instantiate the OAuth2Integration class with the integration name and call the method get_access_token.
integration = vkt.external.OAuth2Integration('databricks-workspace-1')
access_token = integration.get_access_token()
# Example for Databricks (https://docs.databricks.com/aws/en/dev-tools/sdk-python#authenticate-the-databricks-sdk-for-python-with-your-databricks-account-or-workspace)
from databricks.sdk import WorkspaceClient
client = WorkspaceClient(
host="http://myworkspace.cloud.databricks.com/",
token=access_token
)
for cluster in client.clusters.list():
print(cluster.cluster_name)
For more information about the configuration in app code refer to viktor.config.toml.
3. Using the integration by logging in (user)
With everything properly setup, the app is ready to be used. When a user enters the app for the first time, a pop-up will be shown, explaining that the user needs to login before the app can be used. The user logs in, thereby allowing the app to access the external software and the integration can be used. After a period of inactivity, the user needs to re-login to reactivate the integration. This duration is configurable per integration by the admin.
User asked to connect their account(s) when entering an app