Configuration

Overview
This section explains how to completely configure a WorkflowGen container, including the web.config file, iisnode configuration for Node.js applications, database connection strings, etc. Everything is configurable via an environment variable except the license file, which is configured via a volume.
WorkflowGen environment variables
WorkflowGen's image provides a number of specific environment variables that makes specific configurations possible. The following table provides descriptions of each of them:
Variable
Description & values
WFGEN_ADMIN_USERNAME
The username for the WorkflowGen administrator account
​
Changing this value is useful when you are configuring this image with an OpenID provider. You can set it to a username that exists on the provider that you have access to. Then, when you browse to WorkflowGen, you can authenticate with it and it will log you in as an administrator. 
​
For example, if you have a username on your provider named [email protected], then you can set this environment variable to this username and authenticate with it in the container to have administrative access to WorkflowGen. 

✏️ Note: If you change this, make sure to update the database as well.
​
Possible values: wfgen_admin (default)
WFGEN_DATABASE_CONNECTION_STRING
Required variable

The connection string of the main database source

This environment variable must be present, or else the container will throw an error and exit.
WFGEN_DATABASE_READONLY_
CONNECTION_STRING
The connection string of the read-only database source for a database setup with replicas
WFGEN_AUTH_MODE
This variable indicates which authentication method to be used by WorkflowGen
​
Possible values:
adfs
application (default)
auth0
azure-v1
basic
ms-identity-v2
okta
windows
WFGEN_GEN_APP_SYM_ENCRYPT_KEY
Indicates whether or not the ApplicationSecurityPasswordSymmetricEncryptionKey should be generated if no value is provided
​
If Y, the ApplicationSecurityPasswordSymmetricEncryptionKey is regenerated when the container restarts. It is not compatible for usage in production because the secrets will be encrypted with different keys. Therefore, use Y only for developing or testing a single container scenario.
​
Possible values: Y (default), N
WFGEN_LICENSE_FILE_NAME
File name (including extension) of the license needed in the C:\licenses volume
​
If none is specified, the first file found is taken.
WFGEN_START_SERVICE
Indicates what the container should run
​
You can either run the WorkflowGen web application or Windows Services, or both. In a cluster, you'd probably want to have multiple containers in web app mode and only one container in Windows Services mode. You can also divide more by running multiple containers in web app mode, one container in engine mode, and one container in directory sync mode.
​
Possible values:
all (default)
dir_sync
engine
web_apps
win_services
WFGEN_MACHINE_KEY_VALIDATION_KEY
Represents the validationKey property of the machineKey element in the web.config file
​
By default, IIS generates one when it isn't there. It's recommended to use this environment variable to share the machine key between instances of this container (e.g. in a web farm). See the Resolving view state message authentication code (MAC) errors and MachineKeySection Class Microsoft articles for more details.
WFGEN_MACHINE_KEY_DECRYPTION_KEY
Represents the decryptionKey property of the machineKey element in the web.config file
​
By default, IIS generates one when it isn't there. It's recommended to use this environment variable to share the machine key between instances of this container (e.g. in a web farm). See the Resolving view state message authentication code (MAC) errors and MachineKeySection Class Microsoft articles for more details.
WFGEN_MACHINE_KEY_VALIDATION_ALG
Represents the validation property of the machineKey element in the web.config file
​
The algorithm name used to generate the validation key. Default: HMACSHA256
WFGEN_MACHINE_KEY_DECRYPTION_ALG
Represents the decryption property of the machineKey element in the web.config file
​
The algorithm name used to generate the decryption key. 
Default: AES
WFGEN_DEPENDENCY_CHECK_INTERVAL
Time between dependency check retries in milliseconds
Default: 1000 (1 second)
WFGEN_DEPENDENCY_CHECK_RETRIES
Number of retries to attempt for each dependency check
Default: 10
WFGEN_DEPENDENCY_CHECK_ENABLED
Indicates whether or not the dependency check should be done
Possible values: Y (default), N
WFGEN_GRAPHQL_CORS_ENABLED
Enables CORS headers for the GraphQL API
Possible values: Y (default), N
WFGEN_GRAPHQL_CORS_ALLOWED_ORIGINS
Comma-separated list of origins from which CORS will allow requests
Default: *
Format-based environment variables
WorkflowGen's image also exposes various environment variables based on a specific format in order to configure more generic elements.
web.config
In WorkflowGen, the web.config file is the main point of configuration. Since a container is by definition ephemeral, any changes made in the Configuration Panel would not persist between container restarts. 
In order to set configuration properties in the web.config file, you need to use a specific format for an environment variable that will contain the value of the property you want to set; this format is WFGEN_APP_SETTING_<name>. 
For example, if you want to set the ApplicationUrl property in the web.config to https://mycorporation.com/wfgen, you would set the  WFGEN_APP_SETTING_ApplicationUrl=https://mycorporation.com/wfgen environment variable  in the container.
📌 Example with the run command
1
docker container run `
2
    # ...
3
    --env 'WFGEN_APP_SETTING_ApplicationUrl=https://mycorporation.com/wfgen' `
4
    # ...
5
    advantys/workflowgen:7.16.0-win-ltsc2019
Copied!
For a list of web.config parameters and their descriptions and possible values, see the Web and Application Configuration Parameters appendix in the WorkflowGen Technical Guide.
iisnode configuration for Node.js applications
You can also set specific iisnode properties for each Node.js application. To do this, you need to set an environment variable with the following format: WFGEN_IISNODE_<node name>_<property name>. 
Replace <node name> with the name of the Node.js application (AUTH, HOOKS, GRAPHQL, or SCIM).

Replace <property name> with the name of the property you want to set for the <iisnode/> XML node in the specific Node.js application's web.config file.
For example, if you want to set the iisnode loggingEnabled property in the Auth application to true, you would set the environment variable WFGEN_IISNODE_AUTH_loggingEnabled=true.
📌 Example with the run command
1
docker container run `
2
    # ...
3
    --env WFGEN_IISNODE_AUTH_loggingEnabled=true `
4
    # ...
5
    advantys/workflowgen:7.16.0-win-ltsc2019
Copied!
Special iisnode options for Node.js applications
There are some special options that you can enable for each Node.js application by setting an environment variable that has the following template: WFGEN_ENABLE_IISNODE_OPTION_<node app name>. Then, you replace <node app name> with the name of the Node.js application (AUTH for example) and the value must be one of the following:
Value name
Description
exposelogs
Exposes the logs of the application through http. They will then be available at https://example.com/wfgen/auth/iisnode if the chosen Node.js application is AUTH. 
​
✏️ Note: This option is for debugging purposes only. It is not recommended to use it in production.
Trace configuration
You can activate .NET tracing for different WorkflowGen components using environment variables. Use the WFGEN_TRACE_<component>_<option>=<value> template with <component> as the name of the component you want to set the option on, <option> as the name of the option you want to set, and <value> as the value of the option.
Available components
WEB_APPS (web applications)
ENGINE (engine service)
DIR_SYNC (directory synchronization service)
NODE (Node.js components)
Options
Name
Description
LEVEL
Controls the amount of information traced and therefore written in files
​
Possible values:
ActivityTracing
All
Critical
Error
Information
Off (default)
Verbose
Warning
For more information on .NET tracing levels, see the SourceLevels Enum Microsoft article.
INDENT
Controls the indentation inside the trace logs
​
Default value: 4 (maximum: 8)
📌 Example
To enable tracing for web applications with an indentation of 2 and only trace errors for the engine with an indentation of 0, you would configure the environment variables as follows:
1
WFGEN_TRACE_WEB_APPS_LEVEL=Information
2
WFGEN_TRACE_WEB_APPS_INDENT=2
3
WFGEN_TRACE_ENGINE_LEVEL=Error
4
WFGEN_TRACE_ENGINE_INDENT=0
Copied!
Database configuration
Main connection string
The main connection string can be configured via the WFGEN_DATABASE_CONNECTION_STRING environment variable. You can put any string in this variable and its value will be put in WorkflowGen's web.config file at the MainDbSource connection string.
Here's how to specify the connection string with the run command:
1
docker container run `
2
    # ...
3
    --env WFGEN_DATABASE_CONNECTION_STRING=SomeConnectionString `
4
    # ...
5
    advantys/workflowgen:7.16.0-win-ltsc2019
Copied!
Read-only connection string
If you have a read-only replica, you can configure it in the container as well. You can specify it with the WFGEN_DATABASE_READONLY_CONNECTION_STRING environment variable. It will be added to WorkflowGen's web.config file as a new entry in the connection strings with the name ReadOnlyDbSource.
Here's how to specify the read-only connection string with the run command:
1
docker container run `
2
    # ...
3
    --env WFGEN_DATABASE_CONNECTION_STRING=SomeConnectionString `
4
    --env WFGEN_DATABASE_READONLY_CONNECTION_STRING=SomeReadOnlyConnectionString `
5
    # ...
6
    advantys/workflowgen:7.16.0-win-ltsc2019
Copied!
Custom connection strings
You can also configure more connections to custom data sources if you need to. They can be configured using a specific environment variable format: WFGEN_CUSTOM_CONNECTION_STRING_<name>=<connection_string>. 
For example, if you want a data source named MyDataSource with the connection string value of MyConnectionString in the WorkflowGen web.config, you would specify the following environment variable: WFGEN_CUSTOM_CONNECTION_STRING_MyDataSource=MyConnectionString.
📌 Example with the run command
1
docker container run `
2
    # ...
3
    --env WFGEN_DATABASE_CONNECTION_STRING=SomeConnectionString `
4
    --env WFGEN_DATABASE_READONLY_CONNECTION_STRING=SomeReadOnlyConnectionString `
5
    --env WFGEN_CUSTOM_CONNECTION_STRING_MyDataSource=MyConnectionString `
6
    # ...
7
    advantys/workflowgen:7.16.0-win-ltsc2019
Copied!
Secrets
When using an orchestrator such as Kubernetes, you'll probably want to secure secrets using their built-in secret management tools. Follow the specific guide for your orchestrator to know how to create a secret.
For Kubernetes, see https://kubernetes.io/docs/concepts/configuration/secret/.
It's recommended to inject secrets into WorkflowGen containers as files because they won't be exposed as environment variables and they'll be removed from the container when it's stopped or removed.
Secrets management is only possible using an orchestrator.
In order to get the secret value in the file, you need to suffix any environment variable you want to get the value of this way with _FILE and set its value to the path of the file containing the secret. The container will then get the value in the file at the specified path and set the environment variable without the suffix with that value.
For example, let's say you want to set the license serial number in the web.config to WFG-SOME-LICENSE-KEY using the environment variable WFGEN_APP_SETTING_ApplicationSerialNumber, but you want to use a secret for the value. All you have to do is suffix the environment variable name with _FILE so it becomes WFGEN_APP_SETTING_ApplicationSerialNumber_FILE. Then, set the value of this variable to the path of the file containing the serial number.
📌 Example with Docker Swarm orchestrator
1
# Create the secret for the license serial number
2
"WFG-SOME-LICENSE-KEY" | docker secret create ApplicationSerialNumber -
3
​
4
# Create the container service in Docker Swarm
5
docker service create `
6
    # ...
7
    --env WFGEN_APP_SETTING_ApplicationSerialNumber_FILE=C:\ProgramData\Docker\secrets\ApplicationSerialNumber `
8
    --secret ApplicationSerialNumber `
9
    # ...
10
    advantys/workflowgen:7.18.3-win-ltsc2019
Copied!
For Kubernetes, you would create a ConfigMap that complements your secret like this:
1
apiVersion: v1
2
kind: ConfigMap
3
metadata:
4
  name: wfgen-config
5
data:
6
  WFGEN_APP_SETTING_ApplicationSerialNumber_FILE: C:\secrets\ApplicationSerialNumber
7
---
8
apiVersion: v1
9
kind: Secret
10
type: Opaque
11
metadata:
12
  name: wfgen-secret
13
data:
14
  # "V0ZHLVNPTUUtTElDRU5TRS1LRVkK" is the base64-encoded value of "WFG-SOME-LICENSE-KEY"
15
  ApplicationSerialNumber: 'V0ZHLVNPTUUtTElDRU5TRS1LRVkK'
16
​
Copied!
Then, you would map the ConfigMap as environment variables and mount the secret as a volume like this:
1
apiVersion: apps/v1
2
kind: Deployment
3
metadata:
4
  name: wfgen
5
spec:
6
  selector:
7
    matchLabels:
8
      # ...
9
  template:
10
    metadata:
11
      labels:
12
        # ...
13
    spec:
14
      containers:
15
        - name: wfgen
16
          image: advantys/workflowgen:7.18.3-win-ltsc2019
17
          # ...
18
          envFrom: # ConfigMap as environment variables
19
            - configMapRef:
20
                name: wfgen-config
21
          env:
22
            - name: WFGEN_START_SERVICE
23
              value: webapps
24
          # ...
25
          volumeMounts:
26
            # ...
27
            - mountPath: C:\secrets # Mount Secret as a volume
28
              readOnly: true
29
              name: secrets
30
      volumes:
31
        # ...
32
        - name: secrets # Mount Secret as a volume
33
            secret:
34
              secretName: wfgen-sec
Copied!
Configuring the authentication mode
For all authentication modes, you need to set WFGEN_APP_SETTING_ApplicationUrl and WFGEN_APP_SETTING_ApplicationSerialNumber in order to avoid unwanted behaviors.
Application authentication
In order to let WorkflowGen handle authentication and the storage of user passwords, you don't need to configure anything special in the container. Keep in mind that the default username for the WorkflowGen administrative account is wfgen_admin.
Windows and Basic authentication
In order to make Windows or Basic authentication modes work, your host needs to be in an Active Directory forest. Creating a user account on the host for Basic authentication won't work, because the IIS web server inside the container will try to find a user account registered inside the container instead of the host. For this reason, you need Active Directory.
To configure your Docker host to work with Active Directory to authenticate users, follow the Group Managed Service Account (gMSA) guide from Microsoft in its Windows Containers documentation.
Kubernetes supports gMSAs for Windows pods and containers as of version 1.18. See the Configure GMSA for Windows Pods and containers Kubernetes article for details on how to configure it. Keep in mind that not all cloud providers supports gMSAs with Kubernetes. For example, Azure Kubernetes Service doesn't support this feature.
You can't use Basic authentication with Kubernetes.
Azure v1 and Microsoft Identity Platform
For these providers, there is no special configuration to do other than setting the WFGEN_AUTH_MODE variable. For configuration instructions, see the WorkflowGen for Azure guide.
Active Directory Federation Services (AD FS), Auth0, and Okta
For these providers, there is no special configuration to do other than setting the WFGEN_AUTH_MODE variable. For configuration instructions, see the WorkflowGen Technical Guide.
Configuring your license
In order to configure your license, you need to set a specific environment variable with your license and copy your license file into a volume exposed to the WorkflowGen container. To do this, you first need to create a license volume or have your license at a specific path.
Create a volume
1
docker volume create licenses
Copied!
This will create a volume at a specific path on your file system (typically C:\ProgramData\Docker\volumes\licenses\_data) managed by Docker. You can get the path to the volume by executing the following command:
1
docker volume inspect -f "{{.Mountpoint}}" licenses
Copied!
Then, you need to copy your license file to this location:
1
Copy-Item C:\Path\To\WorkflowGen.lic $(docker volume inspect -f "{{.Mountpoint}}" licenses)
Copied!
Now, you can run the WorkflowGen container like so:
1
docker container run `
2
    # ...
3
    --env WFGEN_APP_SETTING_ApplicationSerialNumber=YOUR-WFG-LIC-NUM `
4
    --mount "type=volume,src=licenses,dst=C:\wfgen\licenses,readonly" `
5
    # ...
6
    advantys/workflowgen:7.16.0-win-ltsc2019
Copied!
Use a specific path
Here, you'll provide a path that you control as a volume to the container. You only need to pass the path when you run WorkflowGen:
1
docker container run `
2
    # ...
3
    --env WFGEN_APP_SETTING_ApplicationSerialNumber=YOUR-WFG-LIC-NUM `
4
    --mount "type=bind,src=C:\Path\To\Your\Licenses,dst=C:\wfgen\licenses,readonly" `
5
    # ...
6
    advantys/workflowgen:7.16.0-win-ltsc2019
Copied!
Bringing the WorkflowGen website offline
You can bring the web applications inside WorkflowGen's container offline by executing a script embedded in the image. This is useful to ensure that the site is still available when you want to perform maintenance tasks on its data without anything new being written. With pure containers, you can execute the following command:
1
docker container exec -i wfgen powershell C:\set-state.ps1 Offline
Copied!
With Kubernetes, you can use kubectl:
1
kubectl exec -i wfgen-pod -- powershell C:\set-state.ps1 Offline
Copied!
You must do this for each WorkflowGen container that is running. The recommended approach is to scale down the number of containers to one and execute the set-state.ps1 script once.
If you browse to your WorkflowGen website, you'll see the default offline web page. You can customize this web page by adding your own HTML file at the path <wfgen appdata>\Templates\server\offline.htm. If this file is present, it will be taken instead of the default one. If you have a volume for WorkflowGen's data, you can execute the following script:
1
$offlinePath = ".\offline.htm"
2
$serverTemplatePath = [io.path]::Combine(
3
    $(docker volume inspect --format "{{ .Mountpoint }}" wfgdata),
4
    "appdata" , "Template", "server"
5
)
6
​
7
if (-not (Test-Path $serverTemplatePath)) {
8
    New-Item $serverTemplatePath -ItemType Directory -Force
9
}
10
​
11
Copy-Item $offlinePath $serverTemplatePath
12
​
Copied!
You can bring the site back online by executing the following command:
Docker CLI
kubectl
1
docker container exec -i wfgen powershell C:\set-state.ps1 Online
Copied!
1
kubectl exec -i wfgen-pod -- powershell C:\set-state.ps1 Online
Copied!
Using an orchestrator
Kubernetes
Kubernetes also has a built-in object called ConfigMap to manage pod configuration. See the Configure a Pod to Use a ConfigMap Kubernetes article for more information and instructions on how to use it. You should use this object to configure environment variables for WorkflowGen.
You can also manage sensitive information by protecting it further in the orchestrator in a secure area. See the Secrets Kubernetes article for more information and instructions on how to use it. You should use this object to protect sensitive information such as the WorkflowGen license key, usernames, passwords, cryptographic keys, API keys, etc.
Using your own configuration files
In order to use your own configuration files, you should build your own WorkflowGen image using the WorkflowGen onbuild image variant. See the Custom Image page in the WorkflowGen Image section for more information.
Using an external configuration manager
Some popular configuration managers support Docker containers out-of-the-box. Here are a few links to their specific documentation to get you started:
Chef
​Docker Cookbook - Chef Supermarket​
​Chef and Kubernetes​
Ansible
​Ansible and Docker​
​k8s – Manage Kubernetes (K8s) objects​
Puppet
​Puppet in Docker: running Puppet on container-centric infrastructure​
​Installing Kubernetes with the (certified!) Puppet Kubernetes module​
WorkflowGen Image - Previous
Recommended Architectures
Next - WorkflowGen Image
File Management
Last modified 1yr ago
Overview

WorkflowGen environment variables

Format-based environment variables

`web.config`

📌 Example with the `run` command

iisnode configuration for Node.js applications

📌 Example with the `run` command

Special iisnode options for Node.js applications

Trace configuration

Available components

Options

📌 Example

Database configuration

Main connection string

Read-only connection string

Custom connection strings

📌 Example with the `run` command

Secrets

📌 Example with Docker Swarm orchestrator

Configuring the authentication mode

Application authentication

Windows and Basic authentication

Azure v1 and Microsoft Identity Platform

Active Directory Federation Services (AD FS), Auth0, and Okta

Configuring your license

Create a volume

Use a specific path

Bringing the WorkflowGen website offline

Using an orchestrator

Kubernetes

Using your own configuration files

Using an external configuration manager

Chef

Ansible

Puppet
