Skip to main content

xSuite Interface Windows Prism 5.x – Online Help

xSuite Helix Proxy

The xSuite Helix Proxy is a special web service that runs independently of the regular processing scenarios. This web service acts like an HTTP proxy server and is used exclusively to forward HTTP requests from third-party applications to the xSuite Helix Cloud. Third-party applications do not usually support the Keycloak authentication procedure by themselves. The central task of the xSuite Helix proxy is to retrieve the required token from the Keycloak server and add it to the HTTP header data of the requests.

The xSuite Helix Proxy determines a matching rule for each incoming request based on the HTTP method and URL path of the request. This rule defines the target address in the xSuite Helix Cloud to which the request is forwarded. The forwarding rules are configured in the .Rule[] property. They will be evaluated at runtime in the order in which they are defined. The first matching rule will be used.

Notice

If there is any ambiguity, the more specific rules should be stated before the more general rules.

The proxy is called at the same base address as the other internal web services (i.e., at WebService.Url[]). To specify the target as either an internal service or, via the proxy, an external service, set the property WebService.UrlBasePath for the base path of the request. All requests starting with this base path will be processed by the internal services. All other requests will be processed by the proxy.

An authentication procedure defined for the internal web services does not apply to the proxy. The proxy basically does not support its own authentication for the incoming requests. Therefore, only authentication is performed on the target system, which is usually the xSuite Helix Cloud keycloak authentication.

Notice

The xSuite Helix Proxy should run in a standalone program instance that is not simultaneously responsible for running regular processing scenarios. This will ensure the highest possible data throughput.

Reduce or disable logging that is especially time consuming, especially logging to a relational database. The .ContentLogFolder configuration property should not be used in normal operation.

Property

Description

XSuiteHelixProxy.Activate

Boolean value enabling or disabling the xSuite Helix Proxy

If this value is missing, the activation of the xSuite Helix proxy is determined by whether at least one necessary rule is defined

XSuiteHelixProxy.ProxyServer

HTTP proxy server connection data

If the communication between the xSuite Helix Proxy and the xSuite Helix Cloud is to be performed via a normal HTTP proxy server, specify the connection data here.

Syntax: see Proxy Server Connection

XSuiteHelixProxy.Keycloak(*)

Properties for authentication against the xSuite Helix Cloud via a Keycloak service

Syntax: see Keycloak Authentication.

Caution: If this information is omitted, authentication data will not be included in requests to the proxy.

XSuiteHelixProxy.RequestTimeout

Timeout value in seconds for the requests that are forwarded to the xSuite Helix Cloud (optional)

The timeout value will apply globally to all requests. Default setting: No timeout value.

XSuiteHelixProxy.ForceConnectionClose

Boolean value determining whether the connection between client and proxy will be forcibly closed (HTTP header "connection: close")

Default value: false (the value sent by the client is used)

Notice

The proxy does not manage open connections from the proxy to the xSuite Helix Cloud. These connections are cut off again immediately.

XSuiteHelixProxy.ForceProtocolVersion

Specification of a fixed HTTP protocol version for the request from the proxy to the xSuite Helix Cloud (e.g., 1.1 or 2.0) (optional)

Default setting: The version transmitted from the client to the proxy is used.

XSuiteHelixProxy.CacheFileFilter

Filename filter for xSuite Helix Cloud web files that are cached at the proxy (optional)

As a rule, these are only static web files. As such, they do not have to be reloaded from the cloud each time they are called up.

XSuiteHelixProxy.ContentLogFolder

Folder path where the full contents of requests made to the proxy and responses returned from xSuite Helix Cloud are logged (optional)

This feature is primarily for the purposes of analysis and should not be used in normal operation.

XSuiteHelixProxy.Rule[].Name

Name of a forwarding rule for display in logging (optional)

XSuiteHelixProxy.Rule[].Method

Comma-separated list of HTTP methods (e.g., "GET", "POST") for which the rule applies (optional)

Default value: * (all methods)

XSuiteHelixProxy.Rule[].Path*

URL path of the request to which the rule applies

Specify the part of the URL after the .Url above, including the preceding / character. Write the path to correspond syntactically to a name filter (wildcard expressions and regular expressions are also permitted). Identify regular expressions with enclosing / characters.

XSuiteHelixProxy.Rule[].ToUrlMacro*

Field macro expression that results in the full target URL (including protocol/server/port) to which the request is to be forwarded

In the normal case of a static target address, specify a string constant here. If the target address starts with http(s): or file:, the constant will be recognized as such even if the surrounding quotes are omitted.

In the file: variant, the data contained in the response to the client does not originate from the xSuite Helix Cloud. Instead, a standard response is returned, the content of which is stored in a file. Specify the reference to this file in the form file:///{filepath} or file://{server}/{share}/{filepath}. Syntactically, the content of this file must correspond to an HTTP response, such as is also created as a log file via the .ContentLogFolder property.

If a regular expression is used in .Path and groupings are used in that expression, the corresponding subexpression of such a group can be referenced in the syntax ${group number}. For example, if the expression for the URL path is /\/TestService(.*)/, the group (.*) will dynamically retrieve the remaining part of the path. Place it in the target URL as $1 (e.g., http://testserver:8000/testservice$1).

XSuiteHelixProxy.Rule[].ResponseHeader[]

Definition of HTTP headers (optional)

These headers either 1) supplement the answer to the client with header lines from the original answer from the xSuite Helix Cloud or 2) overwrite existing header lines.

Syntactically, such a configuration value corresponds to the normal structure of a header (i.e. {name}: {value}).

Certain variables obtained from the header data of the original client request can also be used as values. The syntax for this is %RequestHeader.{Name}%. With this, you can create a response header such as one that refers to the "Origin" value of the client request: Access-Control-Allow-Origin: %RequestHeader.Origin%.

XSuiteHelixProxy.Rule[].RequestTimeout

Timeout value for the requests forwarded to the xSuite Helix Cloud, expressed in seconds (optional)

This value applies to this rule only. It applies only if it is less than the value defined in the parent property XSuiteHelixProxy.RequestTimeout.

Default setting: No timeout value.

In this section: