Universal plugin

The Universal plugin provides a standardized interface to the Vienna Test System (VTS), enabling:

• Person management (creation, updating, searching and sending invitations for an online test)

• Export of test results in PDF, CSV and SPSS formats

• Various other operations such as the retrieval of test status or triggering an archiving operation

Communication is handled via a SOAP 1.2 Web Service, ensuring compatibility with open standards and integration flexibility.

Overview of functionality

SOAP (Simple Object Access Protocol) is a standard for sending messages between systems and applications. It offers a reliable way to exchange information. The Universal plugin includes a SOAP web service that supports different message types, allowing external systems to control the VTS or get data from it. Although SOAP supports various transport methods, the Universal plugin uses only HTTPS for communication.

The Universal plugin web service is passive, meaning it only reacts to incoming messages. It does not initiate any communication on its own and relies entirely on external systems to send requests or commands.

Authentication

The Universal plugin requires WS-Security authentication using a UsernameToken over HTTPS. All SOAP requests must be sent over a secure HTTPS connection, and the WS-Security header must include a UsernameToken containing the valid username and password. No client certificates are required. When testing with tools like SoapUI, ensure that WS-Security is enabled with UsernameToken, and set the password type to either plain text (PasswordText), as required by your environment. Username and password for authentication are configured in the plugin config file, see also Universal plugin | UP-VIS-Settings-file.

Setup and configuration

In order for the SOAP web service to be available, the Universal plugin must be configured in the VIS settings file. By default, the plugin listens to port 9010. If this port is unavailable or already in use by another application, it can be easily changed within the configuration file.

Here is a short step by step guide on how to configure a minimal working setup. For advanced options please refer to the sections below.

1. Adapt the VIS settings file

The Universal plugin must be enabled and configured in the VIS settings file by default located in C:\Program Files\SCHUHFRIED GmbH\Vienna Test System 8\IntegrationService\appsettings.json
Note: This is the default installation path. If the Vienna Test System was installed to a different location, the actual path may vary accordingly.

This file contains the configuration of all available VIS plugins. All settings relevant to the Universal plugin can be found under the section starting with “UniversalPlugin”.

"UniversalPlugin": {
  //...
}

1.1. Enable the Universal plugin

In order to use the Universal plugin, ensure the value of the Enabled property is set to true (it is enabled by default).

"Enabled": "true", 

1.2. (Optional) Configure a custom port

If a port different to the standard one shall be used to listen to incoming requests, it needs to be changed in a setting named “Urls”, outside of the section “UniversalPlugin”.

"Urls": "https://localhost:9010",

1.3. Apply changes

After saving changes to the settings file, you must restart the Windows service “WTS Service” for the system to apply the updates and load the plugin with the new configuration. If you are unsure how to restart a Windows service, you may also reboot your machine.

2. Test your setup

2.1. Verify service operation

To confirm that the Universal plugin is running correctly, open a web browser and navigate to the plugin’s Metadata Exchange (MEX) endpoint:

https://[machineName]:[port]/mex

For example, if running locally on the default port:

https://localhost:9010/mex

This endpoint provides metadata about the service and should be accessible if the plugin is properly configured and operational. The following screenshot shows how it should look like in the web browser:

Please note that the “singleWsdl” endpoint does not work due to legacy reasons (namespace collisions that cannot be resolved in order to maintain compatibility).

2.2. Samples

A sample project can be downloaded from the following link: https://dev.azure.com/SchuhfriedGmbh/SchuhfriedPublic/_git/VisSamples.

Consider reading the project’s README.md before running it.

2.3. Troubleshooting

In all cases, you may check the log files for any hints about what could be wrong (see: Universal plugin | Logging )

• The MEX service endpoint cannot be reached in browser

  • A firewall may block incoming connections to the configured port. Ensure that incoming connections on the specified port are accepted.

  • Verify that the configured port matches the port used in the URL

  • Ensure the “WTS Service” has been restarted and all settings are correctly applied

• Messages are terminated with 401 or 403 HTTP status codes

  • Ensure that messages are properly authenticated (see above)

• Messages are terminated with error status codes

  • Ensure that there are no inconsistencies in your data, e.g. malformed fields or a reference to a non-existing test battery.

  • Check the logs for information about possible issues.

Further information and reference

The following sections contain more detailed information about the various topics related to the Universal plugin and its functionality.

VIS settings file

The Universal plugin must be enabled and configured in the settings file of the VIS by default located in C:\Program Files\SCHUHFRIED GmbH\Vienna Test System 8\IntegrationService\appsettings.json
Note: This is the default installation path. If the Vienna Test System was installed to a different location, the actual path may vary accordingly.

This file contains the configuration of all available VIS plugins. All settings relevant to the Universal plugin can be found under the section starting with “UniversalPlugin”.

Settings reference

Urls

UniversalPlugin.Enabled

UniversalPlugin.DefaultTestBattery

UniversalPlugin.CertificateSearchKind

UniversalPlugin.CertificateSearchValue

UniversalPlugin.UsernameToVisService

UniversalPlugin.PasswordToVisService

AppSettings.Service.MandantName

AppSettings.Service.Language

Example

"Urls": "https://localhost:9010",
"UniversalPlugin": {
  "Enabled": "true",
  "DefaultTestBattery": "",
  "CertificateSearchKind": "FindBySubjectName",
  "CertificateSearchValue": "SchuhfriedSelfSignedCertificate",
  "UsernameToVisService": "customUsername",
  "PasswordToVisService": "customPassword"
},

Interface description

A complete description of the interface is available in the WSDL file available via the interface’s Metadata Exchange (MEX) endpoint (https://[machineName]:[port]/mex).

Below is a summary of the available endpoints:

Endpoints

IMex interface

IUniversalPluginService operations

IUniversalPluginServiceStreamed operations

IUniversalPluginSpecialCaseService operations

Data types

The data types used in the available operations are specified in the WSDL document. The names of the fields should be self-explanatory.

Logging

The VIS and Universal plugin generate log data that can be used to analyze their functionality. This data is recorded in the following log files:

C:\ProgramData\Schuhfried\Logs\VTS.Integration.Service.log