DSW User Guide



Most of the configuration is done through Settings (accessible by Administrator).

Configuration Files

Configuration files are used for setting the server-side configuration. Since 3.0 release, the configuration for server and document worker components overlap. Therefore, you can have a single configuration file for both.

Server Configuration

For reference, see configuration of the DSW Deployment example.


This configuration section is used only by Server and covers basic configuration of the application.
  • serverPort (int, default: 3000) = Port that will be the web server listening on.
  • secret (string) = Secret string of 32 characters for encrypting configuration in database and JWT tokens.
  • clientUrl (URI) = Address of client application (e.g. https://localhost:8080).
  • serviceToken (string) = Randomly generated string for API authentication of service endpoints.
Keep your secret and serviceToken secured! Changing secret will require re-configuration of secrets stored in the database, e.g., token for Registry.
If you need to change your secret, you need also replace all values encrypted by secret that are stored in the database as follows:
  1. 1.
    Note somewhere values from Settings: Client ID and Client Secret of OpenID configurations, Registry token, and GitHub token for Feedback functionality. Adjust the settings that the values are not there (recommended; e.g. remove OpenID configuration), and save it.
  2. 2.
    Change secret in the configuration file and restart DSW server (re-create the container if using Docker).
  3. 3.
    Adjust the settings back to your previous values.
  4. 4.
    If you use also some "user properties" (for Document Submission feature), let your users know to change the values in their profiles.


Information for connection to PostgreSQL database.
  • connectionString (string) = PostgreSQL database connection string (typically: postgresql://{username}:{password}@{hostname}:{port}/{dbname}, for example, postgresql://postgres:[email protected]:5432/postgres).


Information for connection to S3 storage (used for document and template asset files).
  • url (URI) = endpoint of S3 storage, e.g., http://minio:9000
  • username (string) = username (or Access Key ID) for authentication
  • password (string) = password (or Secret Access Key) for authentication
  • bucket (string, default: engine-wizard) = bucket name used by DSW


This configuration section is used only by Server. It must be filled with SMTP connection information to allow sending emails (registration verification, password recovery, project invitation, etc.).
  • enabled (boolean) = It should be set to true unless used for local testing only.
  • name (string) = Name of the DS Wizard instance that will be used as “senders name” in email headers.
  • email (string) = Email address from which the emails will be sent.
  • host (string) = Hostname or IP address of SMTP server.
  • port (int) = Port that is used for SMTP on the server (usually 25 for plain or 465 for SSL).
  • ssl (boolean, default: false) = If SMTP connection is encrypted via SSL (we highly recommend this).
  • authEnabled (boolean) = If authentication using username and password should be used for SMTP.
  • username (string) = Username for the SMTP connection.
  • password (string) = Password for the SMTP connection.


This configuration section is used only by Server and it allows you to receive email notifications when a new user registers.
  • enabled (boolean) = If analytic emails should be sent.
  • email (string) = Target email address where analytics to which will be sent.


This configuration section is used only by Document Worker. You can affect steps for templates that use external tools (pandoc and wkhtmltopdf). It is usually sufficient to keep the defaults. Each of them has configuration options:
  • executable (string) = Command or path to run the external tool.
  • args (string) = Command line arguments used to run the tool.
  • timeout (int) = Optional for limiting time given to run the tool.

Integrations Configuration

Integrations in the DS Wizard are using external APIs and you might need some configured variables such as API keys or endpoints. For example, integration with ID dbase might use following configuration.
apiKey: topSecretDBaseApiKey
apiUrl: https://api.dbase.example:10666
someConfig: someValue4Integration
There can be multiple integrations configured in single file. These can be used then when setting up the integration in the Editor as ${apiKey}, ${apiUrl}, etc. More about integrations can be found in separate integrations documentation.
Different knowledge models may use different variable naming, please read the information in README to find out what is required. We recommend authors to stick with apiKey and apiUrl variables as our convention.

Client Configuration

If you are running the client app using “With Docker”, the all you need is to specify API_URL environment variable inside docker-compose.yml. In case you want to run the client locally, you need to create a config.js file in the project root:
window.dsw = {
apiUrl: 'http://localhost:3000'
Client also provides wide variety of style customizations using SASS variables or message localization. Then you can mount it as volumes in case Docker as well:
# mount SCSS file
- /path/to/extra.scss:/src/scss/customizations/_extra.scss
- /path/to/overrides.scss:/src/scss/customizations/_overrides.scss
- /path/to/variables.scss:/src/scss/customizations/_variables.scss
- /path/to/provisioning.json:/configuration/provisioning.json:ro
# mount other assets, you can then refere them from scss using '/assets/...'
- /path/to/assets:/usr/share/nginx/html/assets
  • _extra.scss = This file is loaded before all other styles. You can use it, for example, to define new styles or import fonts.
  • _overrides.scss = This file is loaded after all other styles. You can use it to override existing styles.
  • _variables.scss = A lot of values related to styles are defined as variables. The easiest way to customize the style is to define new values for these variables using this file.
For more information about variables and assets, visit Theming Bootstrap. The color of illustrations can be adjusted using $illustrations-color variable.

Document Templates

You can freely customize and style templates of documents (DMPs). HTML and CSS knowledge is required and for doing more complex templates that use some conditions, loops, or macros, knowledge of Jinja templating language (pure Python implementation) is useful.
For further information, read Template Development.

Email Templates

Similarly to document templates, you can customize templates for emails sent by the Wizard located in templates/mail folder. It also uses Jinja templating language (for email templates we use its implementation called Ginger). And you can create HTML template, Plain Text template, add attachments, and add inline images (which can be used inside the HTML using Content-ID equal to the filename).

Templates structure

The structure is following:
  • templates/mail/_common = layout, styles, common files
  • templates/mail/_common/attachments = attachments for all emails
  • templates/mail/_common/images = inline images for all emails
  • templates/mail/<name> = templates specific for this email type, should contain message.html.j2 and message.txt.j2 files (or at least one of them, mail servers prefer both variants)
  • templates/mail/<name>/attachments = attachments specific for email type
  • templates/mail/<name>/images = inline images specific for email type
All attachments are loaded from the template-specific and common folders and included to email with detected MIME type. It similarly works for inline images but those are not displayed as attachments just as related part to HTML part (if present). We highly recommend to use ASCII-only names without whitespaces and with standard extensions. Also, sending minimum amount of data via email is suggested.

Templates variables

All templates are provided also with variables:
  • appTitle = from the configuration appTitle
  • clientAddress = from the configuration clientUrl
  • mailName = from the configuration name
  • user = user (subject of an email), structure with attributes accessible via . (dot, e.g. user.name)

Email types

Currently, there are following types of mail:
  • registrationConfirmation = email sent to user after registration to verify email address, contains activationLink variable
  • registrationCreatedAnalytics = email sent to address specified in the configuration about registration of a new user (see Analytics config)
  • resetPassword = email sent to user when requests resetting a password, contains resetLink variable

Docker deployment

Including own email templates while using dockerized Wizard is practically the same as for DMP templates. You can also bind whole templates/mail folder (or even templates if want to change both):
image: datastewardshipwizard/wizard-server
restart: always
- 3000:3000
- /dsw/application.yml:/application/engine-wizard/config/application.yml
- /dsw/templates/mail:/application/engine-wizard/templates/mail:ro
# ... (continued)