Web Client Configuration | PLANTA Online-Hilfe

Information

Here you will find a description of the PLANTA Web Client configuration.

Basics

Information

There are several ways to apply configurations. Below, all options are listed from lowest to highest priority.
If a variable has been defined at more than one position, the position with the highest priority will be used:
1. appsettings.json: Main (default) configuration, changes are not recommended
2. appsettings.[Environment].json: environmental specific (e.g. production) configuration
3. Environment Variables
4. Command line parameter

Define parameters outside the JSON format

Information

You have to use a particular format for conversion variables and command line parameters:

Define parameters within a block

JSON:	Command line:
JavaScript `{ "ConnectionSettings": { "User": "username" } }`	`--ConnectionSettings:User=username`

Define parameters within an array

JSON:	Overwrite ServerB port in the command line:
JavaScript `{ "ConnectionSettings": { "Servers": [ { "Host":"serverA", "Port":1234 }, { "Host":"ServerB", "Port":4567 } ] } }`	`--ConnectionSettings:Servers:1:Port=9999`

Parameter

Information

The following parameters can be used to configure the Web Client.

Dotnet Settings

Information

The ASPNETCORE_ENVIRONMENT can be set to Development this will enable a button on the error screen which allows the copying of the stacktrace.

Connection Settings

Information

Parameters which define the server start and the communication with the PLANTA Server.
They must be defined within the ConnectionSettings block.

Parameter	Type	Default	Description
`CompressionLevel`	int	6	Zlib compression level, number between 0 and 9. Will be ignored if `UseCompression` = “false”.
`CultureCode`	string	de-DE	Culture Code which is used by the application. Depends on the host operating system. A list of culture codes can be found online as well.
`IndividualParameters`	string	null	`individual_parameters`-Parameter which is sent upon server start
`KeepAliveTimeout`	int	60	Time interval between keepalive signals sent to the PLANTA Server in seconds
`RoutingRequestTimeout`	int	5	Request timeout for routing requests to PLANTA link
`RoutingApiKey`	string	see `appsettings.json`	API key which the web client sends as the `Apikey` header with every routing request. Can be overwritten per installation, e.g. via the `ConnectionSettings__RoutingApiKey` environment variable. Without a value, the web client does not send a header and the webhook rejects the request
`RoutingWebHook`	string	null	The PLANTA link webhook which is required for routing
`PanelDestructionDelay`	int	1440	Time in minutes for which the web server saves panel information when the user has interrupted the connection or left the page
`Password`	string	null	`password` parameter which is sent upon server start
`SessionDestructionDelay`	int	7200	Time in minutes for which the web server saves session information when the user has interrupted the connection or left the page
`Servers`	array	null	List of the PLANTA Server must at least contain one entry. Further information
`UseCompression`	bool	true	Defines whether communication with the PLANTA Server is to be compressed
`User`	string	null	`individual_parameters` parameter which is sent upon server start
`UseSSL`	bool	false	Defines whether SSL is to be activated for communication with the PLANTA Server

Settings of the Servers parameter

Parameter	Type	Description	From/Up to Version
`Host`	string	server host name
`Port`	int	server port

gRPC Settings

Information

This block controls the gRPC connection to the PLANTA manager via which the web client loads the integrated agile board.
The parameters must be defined within the GrpcSettings block.
If ServerUrl remains empty, the address is formed from the host of ConnectionSettings:RoutingWebHook and the value of Port. An explicitly set ServerUrl takes precedence.
If no address can be formed, the startup records this in the log and only the agile board is unavailable. The rest of the web client continues to work.

Parameter	Type	Default	Description
`ServerUrl`	string	empty	Complete gRPC address of the manager, e.g. `http://manager:50051/`. If the value remains empty, the address is derived from the webhook
`Port`	int	50051	Port of the derived address. Has no effect if `ServerUrl` is set. Corresponds to the manager’s default setting and must be adjusted if the manager uses a different port
`UseTls`	bool	false	Determines whether the derived address uses `https`. Has no effect if `ServerUrl` is set. By default, the manager accepts gRPC unencrypted
`DefaultToken`	string	empty	Service token for calls without a session-specific token. Required for the Microsoft 365 integration
`ClientIdentifier`	string	empty	Identifier which the web client sends with gRPC calls

Example configuration

JSON

{
  "ConnectionSettings": {
    "RoutingWebHook": "https://manager.example.com:23333/api/webclient/routing"
  },
  "GrpcSettings": {
    "ServerUrl": ""
  }
}

AI Settings

Parameter	Type	Description	From/Up to Version
`ChatHost`	string	URL of the AI assistant chat.

The PLANTA-KI Assistant is available in a separate container—that is where installation and configuration take place. If you have any questions, please contact your PLANTA consultant.

Data Protection Settings

Information

Parameters to control the Data Protection API.
They must be defined within the DataProtectionSettings block.

Parameter	Type	Default	Description
`ApplicationName`	string	PLANTA Webclient	The name of the application for data protection purposes.
`KeysDirectory`	string	%ApplicationFilesPath%/DataProtectionKeys	Directory path where data protection keys are stored.
`EncryptionAlgorithm`	string	AES_256_CBC	The encryption algorithm used for data protection, for possible values see here.
`ValidationAlgorithm`	string	HMACSHA256	The validation algorithm used for data protection, for possible values see here.
`EncryptionCertificateThumbprint`	string		The thumbprint of the encryption certificate used for data protection, if empty the keys file will not be encrypted.

Authentication Settings

Information

Parameters which are used to configure whether and how the reverse proxy informs us about the authenticated user. This requires the use of PLANTA secure.
The parameters must be defined within the AuthenticationSettings block.

Parameter	Type	Default	Description	From/Up to Version
`ProxyAuth`	bool	false	If this option is activated, the Web Client sends a message to the server during session initialization which informs him/her about the pre-authentication and the corresponding user code.
`JwtAuth`	bool	false	When enabled, the Webclient will use JWT/OIDC for authentication (enables OIDC flows). Deprecated from 3.7.2 Use `OidcEnabled` instead.	Up to 3.7.1
`JwtAuthOnClient`	bool	false	When true the client initiates the OIDC login flow by itself; otherwise the OIDC login flow will be initiated by reverse proxy. Deprecated from 3.7.2 Use `OidcEnabled` instead.	Up to 3.7.1
`OidcEnabled`	bool	false	Enables OIDC authentication. Replaces the previous parameters `JwtAuth` and `JwtAuthOnClient`.	From 3.7.2
`ProxyUserFormat`	string	plain	The format in which the value is provided. So far, only the "plain" format has been implemented, which passes the header value to the server.
`ProxyUserHeader`	string	x-forwarded-user	Name of the HTTP header field that contains the user ID authenticated by the reverse proxy.
`ProxyUserAccessToken`	string	x-forwarded-access-token	Name of the HTTP cookie that contains the JWT access token
`ProxyUserIdToken`	string	x-forwarded-id-token	Name of the HTTP cookie that contains the JWT access token
`AppPathBase`	string	/	Web base path that the reverse proxy uses for the Web Client, e.g. if the Web Client can be accessed on the reverse proxy under http://www.example.com/webclient, the base path will be /webclient.
`ProxyLogoutRoute`	string		Logout route which is opened when the user wants to terminate his/her session on the reverse proxy.
`OidcSettings`	OIDC Settings		Configuration for the OpenID connect authentication
`ReverseProxyJwtSettings`	ReverseProxyJwtSettings		Configuration for the JWT authentication via reverse proxy (Cloudflare by default).

ReverseProxyJWT Settings

Parameter	Type	Defaut	Description
`HeaderKey`	string	`Cf-Access-Jwt-Assertion`	HTTP header key that contains the application JWT from the reverse proxy (default: `Cf-Access-Jwt-Assertion`). The authentication service also checks if the header name contains `Cf-` to detect Cloudflare usage. The HTTP header key that contains the application JWT from the reverse proxy. The authentication service also checks whether the header name contains `Cf-` to recognize the use of Cloudflare.
`IssuerUrl`	string		Expected `iss` claim value of the incoming token (e.g. your Cloudflare Access Issuer URL).
`JwksUrl`	string		JWKS end point URL used for validating the token signature.
`Audience`	string		Expected `aud` claim value. In Cloudflare Access, it is usually the 64 digit hex tag.

Notes

When JwtAuth is true and JwtAuthOnClient is false, the client tries to find the tokens made available by the reverse proxy either in cookies (standard OIDC cookies) or in the configured HeaderKey. If HeaderKey contains a Cf prefix and a matching request header exists, the reverse proxy/Cloudflare flow is used. .
After successful validation, the client sends an XML message of the <ProxyToken type="1" .../> type that contains the application token in access_token to the backend. The backend must support type="1" and access_token as validated reverse proxy JWT.

OIDC Settings

Information

Parameter for configuring the OpenID connect authentication.
They must be defined within the AuthenticationSettings.OidcSettings block.

Parameter	Type	Description	From/Up to Version
`ClientId`	string	Oauth client ID that is used for token validation.
`ClientSecret`	string	Client secret that is used for authentication to the OIDC provider.
`DiscoveryUrl`	string	URL for the OIDC discovery document. Deprecated from 3.7.2 Use `IssuerUrl` instead.	Up to 3.7.1
`IssuerUrl`	string	The base issuer URL of the OIDC provider (e.g. `https://login.microsoftonline.com/tenant/v2.0`). Replaces `DiscoveryUrl`. The discovery URL is derived automatically.	From 3.7.2
`Scope`	string	Access area requested by the OIDC provider.

Authentication: Examples and Setup

Information

Below are common configuration scenarios and concrete examples for setting values via appsettings.json, environment variables, or command line.

Example A — Reverse-proxy header authentication (proxy tells backend the user ID)

appsettings.json:

JSON

{
  "AuthenticationSettings": {
    "ProxyAuth": true,
    "ProxyUserHeader": "x-forwarded-user"
  }
}

Environment variable (Windows PowerShell):

PowerShell

$env:AuthenticationSettings__ProxyAuth = "true"
$env:AuthenticationSettings__ProxyUserHeader = "x-forwarded-user"

Example B — Cloudflare Access / Reverse-proxy JWT (reverse proxy injects application JWT)

appsettings.json:

JSON

{
  "AuthenticationSettings": {
    "JwtAuth": true,
    "JwtAuthOnClient": false,
    "ReverseProxyJwtSettings": {
      "HeaderKey": "Cf-Access-Jwt-Assertion",
      "IssuerUrl": "https://your-team.cloudflareaccess.com",
      "JwksUrl": "https://your-team.cloudflareaccess.com/cdn-cgi/access/certs",
      "Audience": "PASTE_THE_64_CHAR_HEX_TAG_HERE"
    }
  }
}

Notes

The application will detect Cloudflare usage when the configured HeaderKey contains Cf- and a matching header exists on the request.
Ensure JwksUrl, IssuerUrl and Audience exactly match the token claims issued by Cloudflare Access. If they do not match validation will fail.

Example C — OIDC client-initiated login with PKCE (browser performs OIDC flow)

appsettings.json:

JSON

{
  "AuthenticationSettings": {
    "JwtAuth": true,
    "JwtAuthOnClient": true,
    "OidcSettings": {
      "ClientId": "APPLICATION_CLIENT_ID",
      "ClientSecret": "YOUR_CLIENT_SECRET",
      "DiscoveryUrl": "https://login.example.com/.well-known/openid-configuration",
      "Scope": "openid profile email"
    }
  }
}

Behavior

The client will start the Authorization Code flow with PKCE and exchange the authorization code for id_token/access_token in the browser.
Tokens are validated and then forwarded to the backend with ProxyToken type="0".

WebAPI Authentication Settings

Parameter	Type	Default	Description	From/Up to Version
`APIKey`	string	APIKEY	API key which is used to access the web API end points

Adaptive Card Settings

Signature Settings

Parameter	Type	Default	Description	From/Up to Version
`RsaPrivateKeyXml`	string		XML formatted private RSA key for signing Adaptive Cards

Upload Settings

Information

Parameters that define the behavior in file uiploads.
They must be defined within the FileUploadSettings block.

Parameter	Type	Default	Description
`CompressionLevel`	int	6	Zlib compression level, number between 0 and 9. Will be ignored if `UseCompression` = `false`
`AllowedExtensions`	string	.doc, .docx, .xls, .txt	File endings which can be uploaded
`MaxFileSize`	int	2000000	Maximum size of files in kB
`ChunkSize`	int	100000	If a number > 0 is defined, the file will be uploaded in chunks according to the specified size. If 0 is defined, the file will be iploaded in a request.
`TemporaryFilePath`	string	.	Path under which the files are temporarily saved during upload

Help Center Settings

Information

Parameters to configure the links and commands used in the Help Center menu.
They must be defined within the HelpCenterSettings block.

Parameter	Type	Default	Description
`MainHelpUrl`	string	https://help.planta.de/	URL for the main help center page.
`VideoTutorialsUrl`	string	https://www.youtube.com/@planta_gmbh/videos	URL for video tutorials.
`TextTutorialsUrl`	string	https://help.planta.de/de/project/	URL for text-based tutorials/documentation.
`PrivacyPolicyUrl`	string	https://www.planta.de/datenschutzerklaerung/	URL for the privacy policy page. When set, a privacy policy link will be displayed in the feedback component.
`AiConfigurationUrl`	string	https://help.planta.de/de/tec/Container-ab-39.5.24/konfiguration-des-ki-assistenten-fur-webclient	URL for AI assistant configuration documentation. This link is shown when the AI assistant is disabled to help users learn how to set it up.
`ModuleHelpCommandId`	int?	null	Optional command ID to execute for module-specific help.
`FieldHelpCommandId`	int?	null	Optional command ID to execute for field-specific help.
`MaxFeedbackTextLength`	int	1000	Maximum character length allowed for feedback comment text. This limits how much text users can enter in the feedback form.
`FeedbackTo`	array	null	List of feedback destinations. Each destination has a `Name` and optional `Args`. Supported destinations: `Console`, `Logger`, `File`, and `Service`.

Feedback to Destination Details

Information

Console: Logs feedback to the console.
Logger: Logs feedback using the application's logger.
File: Logs feedback to a file. Requires Args.filepath (path to the file) and Args.encoding (file encoding, e.g., utf-8).
Service: Sends feedback to a service. Requires Args.url (URL of the feedback service).

Example configuration for FeedbackTo:

JSON

"FeedbackTo": [
  { "Name": "Console" },
  { "Name": "Logger" },
  {
    "Name": "File",
    "Args": {
      "filepath": "%ApplicationFilesPath%/feedback.log",
      "encoding": "utf-8"
    }
  },
  {
    "Name": "Service",
    "Args": {
      "url": "http://localhost:5159/api/feedback"
    }
  }
]

Message Dumper Settings

Information

Message Dumper saves the communication with PLANTA Server: one xml file per session.
The parameters must be defined within the MessageDumperSetting block.

Parameter	Type	Default	Description
`Enabled`	bool	true	Activate Message Dump feature
`LogDirectory`	string	.\Logs\Dump	Path under which message dump files are saved
`AllowUrlParameter`	bool	true	Create an XML recording of a session. It is started by adding `?client_create_dump="true"` to the URL.

Session Log Settings

Information

Every session writes its own log file.
Users download their session log via the Session logs dialog.
- Access to other users’ logs is a customizing right and can be restricted further via DownloadAccess.
The parameters must be defined within the SessionLogSettings block.

Parameter	Type	Default	Description
`DownloadAccess`	string	AllUsers	Defines who may list and download session logs. “AllUsers”: users with customizing rights reach every session, all others only their own. “CustomizersOnly”: without customizing rights, the menu entry is not displayed. “Disabled”: the menu entry is not displayed for anyone
`MinimumLevel`	string	Information	Lowest level an event must reach to be written to the session log. A lower value also lowers the global minimum logging level and therefore affects all log sinks

Example configuration

JSON

{
  "SessionLogSettings": {
    "DownloadAccess": "CustomizersOnly"
  }
}

Virtualization Settings

Information

Virtualization is used to only render what is visible on screen to improve performance.
Within VirtualizationSettings block.

Parameter	Type	Default	Description
`Enabled`	bool	true	Whether to enable virtualization feature

Repositioning Modules Settings

Information

This parameter enables a feature that allows module windows to be positioned anywhere within a view (e.g., within the module bar or at the edge of a panel).
The parameter must be defined within the DockingSettings block.

Parameter	Type	Default	Description
`DockPanelEnabled`	bool	false	Enables docking, stacking as tabs, collapsing, and rearranging modules in the panel.

Example configuration

JSON

{
  "DockingSettings": {
   "DockPanelEnabled": true
  }
}

Status Message Settings

Information

This block controls how the web client displays the status messages sent by the server.
There are three display options which can be turned on and off independently of one another and filtered by status: the pop-up message at the bottom of the screen, the status chip in the module’s action bar, and the classic status bar in the lower-left corner.
The parameters must be defined within the StatusMessageSettings block.
In ascending order, the statuses are Working, Info, Success, Warning, and Error. Each display option shows the range from MinimumLevel to MaximumLevel (both limits included). If the upper limit is below the lower limit, the display option shows nothing.

Parameter	Type	Default	Description
`AllowUserSettings`	bool	false	Allows users to change the status display options for themselves in the Status Messages (PLANTA logo → ? → Status Messages) settings window. Alternatively, the gear icon in the list of recent messages opens the same settings window, provided the status chip is turned on. With “false”, there is no way of accessing the settings window. All display options then correspond to the existing settings in this block.
`Toast:Enabled`	bool	false	Turns on the pop-up message at the bottom of the screen
`Toast:MinimumLevel`	string	Success	Lowest status which is displayed as a pop-up message
`Toast:MaximumLevel`	string	Error	Highest status which is displayed as a pop-up message
`Toast:TimeoutMs`	int	2000	Display duration in milliseconds. Warnings and errors remain on screen regardless of this value until the user closes them. With “0”, the message is given a close button instead of the elapsing line
`Toast:Placement`	string	Center	Position at the bottom of the screen at which the messages appear, configurable with the values “Left”, “Center”, or “Right”. The messages are then displayed in a bar directly above the panel bar.
`Toast:CardsBeforeStacking`	int	3	Number of warnings and errors which are displayed separately one below the other before older messages are stacked above them. Values below 1 are treated as 1. Can only be set per installation. The Status Messages window does not offer this value.
`Pill:Enabled`	bool	false	Turns on the status chip in the module’s action bar
`Pill:MinimumLevel`	string	Working	Lowest status which the status chip displays. A message below it leaves the current content in place
`Pill:MaximumLevel`	string	Error	Highest status which the status chip displays. A message above it leaves the current content in place
`LegacyBar:Available`	bool	true	Determines whether the classic status bar exists in the client at all. With “false”, it disappears from the user interface and from the Status Messages window, and a stored user setting which refers to it is ignored.
`LegacyBar:Enabled`	bool	true	Turns on the classic status bar. Has no effect while `Available` is set to “false”
`LegacyBar:MinimumLevel`	string	Working	Lowest status which the classic status bar displays
`LegacyBar:MaximumLevel`	string	Error	Highest status which the classic status bar displays
`LegacyBar:TimeoutMs`	int	2000	Display duration in milliseconds, here for all statuses including warnings and errors. With “0”, the message remains until the next one replaces it.

Example configuration

Default setting, only the classic status bar displays messages:

JSON

{
  "StatusMessageSettings": {
    "AllowUserSettings": false,
    "Toast": { "Enabled": false, "MinimumLevel": "Success", "TimeoutMs": 2000, "Placement": "Center", "CardsBeforeStacking": 3 },
    "Pill": { "Enabled": false, "MinimumLevel": "Working" },
    "LegacyBar": { "Available": true, "Enabled": true, "MinimumLevel": "Working", "TimeoutMs": 2000 }
  }
}

Test of the new display options, counts and results in the status chip, warnings and errors as pop-up messages, user settings released:

JSON

{
  "StatusMessageSettings": {
    "AllowUserSettings": true,
    "Toast": { "Enabled": true, "MinimumLevel": "Warning" },
    "Pill": { "Enabled": true, "MinimumLevel": "Working", "MaximumLevel": "Success" },
    "LegacyBar": { "Available": true, "Enabled": false }
  }
}

Chart Export Settings

Information

Parameters to control chart export functionality.
Must be defined within the ChartExportSettings block.

Parameter	Type	Default	Description
`ExportScaleFactor`	int	4	Scale factor for exported chart images. Higher values produce higher resolution images but increase file size.
`MaxUploadsPerMinute`	int	60	Maximum number of chart exports allowed per minute (rate limiting).
`MaxFileSizeBytes`	int	15728640	Maximum file size for exported chart images, in bytes (default is 15 MB).

Example configuration

JSON

{
  "ChartExportSettings": {
    "ExportScaleFactor": 4,
    "MaxUploadsPerMinute": 60,
    "MaxFileSizeBytes": 15728640
  }
}

Page Size Settings

Information

Parameters for configuring custom page sizes for PDF export.
The parameter must be defined within the PaperFormatSettings block.

Parameter	Type	Default	Description	From/Up to Version
`Formats`	Array		List of custom page size configurations. Each format must include a localized name and dimensions in millimeters.

Define parameters within an array

{
  "PaperFormatSettings": {
    "Formats": [
      {
        "Name": {
          "de": "A0",
          "en": "A0",
          "fr": "A0",
          "pt": "A0"
        },
        "Size": {
          "Width": 841,
          "Height": 1189
        }
      },
      {
        "Name": {
          "de": "Tabloid",
          "en": "Tabloid (11x17 in)",
          "fr": "Tabloïd",
          "pt": "Tablóide"
        },
        "Size": {
          "Width": 279,
          "Height": 432
        }
      }
    ]
  }
}

Logging Settings

Information

The PLANTA Web Client uses Serilog for logging.
Serilog uses so-called "Sinks” for showing logs. The Web Client currently supports the following sinks:
- Console
- File

Metrics Setting

Information

Parameters to configure Prometheus metrics endpoint and telemetry.
Must be defined within the MetricsSettings block.

Parameter	Type	Default	Description
`PrometheusEndpoint`	string	/metrics	The Prometheus endpoint path for metrics scraping. Configure this to change the URL where metrics are exposed.
`MeterName`	string	planta_webclient_metrics	Name of the custom OpenTelemetry meter for application metrics. This identifies the meter in OpenTelemetry.
`MetricsPrefix`	string	planta_webclient_	Prefix to add to custom application metrics names. This helps identify custom metrics from this application in monitoring systems. Note: Default system metrics (ASP.NET Core, Runtime, HTTP Client) do not use this prefix.

Example configuration:

JSON

{
  "MetricsSettings": {
    "PrometheusEndpoint": "/custom-metrics",
    "MeterName": "my_application_metrics",
    "MetricsPrefix": "my_app_"
  }
}

Change Host URL

Information

ASP.Net Core applications use ports 5000 (http) and 5001 (https) by default.
With the Urls parameter it can be overwritten as follows:

JSON:	Commanfd line:
JavaScript `"Urls": "http://localhost:9000;https://localhost:9001",`	`--Urls:http://localhost:9000;https://localhost:9001`