Configuration¶

Server¶

Server configuration is done using YAML format. We provide examples directly in config folder of the repository https://github.com/ds-wizard/dsw-server. For tests there exist special versions suffixed by -test.

Build Info¶

A build configuration (build-info.yml file) contains information for the build of the application. This configuration can be created simply by running a prepared script build-info.sh. Normally this script is run by a CI Tool (Travis CI) during build process.

Important

If you build server app locally, you should also run build-info.sh otherwise your app will show bad build information and version.

Application¶

The mail configuration file that provide a lot of options and contains necessary settings for server to be running properly. You can see the example application.yml below. Next, all options are described in detail.

application.yml¶

general:
  environment: Production
  serverPort: 3000
  clientUrl: http://localhost:8080
  serviceToken: NlQSNbGvh7EtcpinGnHE9g91
  integrationConfig: integration.yml
  registrationEnabled: true
  publicQuestionnaireEnabled: true
  levelsEnabled: true
  itemTitleEnabled: true
  questionnaireAccessibilityEnabled: true

client:
  appTitle:
  appTitleShort:
  welcomeWarning:
  welcomeInfo:
  privacyUrl:

database:
  host: mongo
  databaseName: dsw-server
  port: 27017
  authEnabled: false
  username:
  password:

jwt:
  secret: gVoYNuEJuGGAQMIaYw43BN3e
  version: 1
  expiration: 14

roles:
  defaultRole: DATASTEWARD
  admin: [UM_PERM, ORG_PERM, KM_PERM, KM_UPGRADE_PERM, KM_PUBLISH_PERM, PM_READ_PERM, PM_WRITE_PERM, QTN_PERM, DMP_PERM]
  dataSteward: [KM_PERM, KM_UPGRADE_PERM, KM_PUBLISH_PERM, PM_READ_PERM, PM_WRITE_PERM, QTN_PERM, DMP_PERM]
  researcher: [PM_READ_PERM, QTN_PERM, DMP_PERM]

mail:
  enabled: false
  name:
  email:
  host:
  port:
  ssl:
  username:
  password:

analytics:
  enabled: false
  email:

registry:
  enabled: true
  token: <token from registry.ds-wizard.org>

feedback:
  enabled: false
  token:
  owner:
  repo:
  issueurl:

Section aside General and JWT may be omitted and default values will be used for whole sections (typically disabled, see below).

General¶

Configuration related to general operations of the server application.

environment¶

Type: Enumeration [Production, Staging, Development, Test]
Default: Production

Environment that your deployment is using. This affects which migrations are used and other minor things can be different in various environments.

serverPort¶

Type: Integer [0-65535]
Default: 3000

Port that will be the web server listening on.

clientUrl¶

Type: URI
Default: "" (empty)

Address of client application (e.g. https://localhost:8080).

serviceToken¶

Type: String
Default: "" (empty)

Randomly generated string that matches configuration of Worker component.

integrationConfig¶

Type: String
Default: "integration.yml"

Filename or whole path of integration configuration file (see Integration). In case of path, it is relative to the config folder.

registrationEnabled¶

Type: Boolean
Default: true

If registrations within the DS Wizard instance are enabled or disabled.

publicQuestionnaireEnabled¶

Type: Boolean
Default: false

If public questionnaire (i.e. questionnaire demo without registration) functionality within the DS Wizard instance is enabled or disabled.

levelsEnabled¶

Type: Boolean
Default: true

If questions can be related to certain desirability levels/phases.

itemTitleEnabled¶

Type: Boolean
Default: false

If list questions require specific title per item or are just groups of subquestions.

questionnaireAccessibilityEnabled¶

Type: Boolean
Default: true

If questionnaires can be set private, public read-only, or public. When disabled (i.e. value is set to false), all questionnaires are private.

Client¶

Configuration related to parts displayed in the client application.

appTitle¶

Type: String
Default: (nothing)

Full name of the DS Wizard instance (displayed, for example, in tab title or before login).

appTitleShort¶

Type: String
Default: (nothing)

Short name of the DS Wizard instance (displayed, for example, on the top of the navigation bar)

Tip

Use consistent appTitle and appTitleShort.

welcomeWarning¶

Type: String
Default: (nothing)

Warning text for users that displays after login (if any).

welcomeInfo¶

Type: String
Default: (nothing)

Info text for users that displays after login (if any).

privacyUrl¶

Type: String (URL)
Default: "https://ds-wizard.org/privacy.html"

URL to page with privacy policy of the service.

Database¶

Configuration of connection to MongoDB database.

host¶

Type: String
Default: "mongo"

Hostname or IP address of the server running MongoDB.

port¶

Type: Integer [0-65535]
Default: 27017

Port that is used for MongoDB on the server (usually 27017).

databaseName¶

Type: String
Default: "dsw-server"

Name of the database for DS Wizard within MongoDB.

authEnabled¶

Type: Boolean
Default: false

Whether authentication is enabled on MongoDB server and is required to connect to the database.

username¶

Type: String
Default: "" (empty)

Username for authentication to database connection (if authEnabled is true).

password¶

Type: String
Default: "" (empty)

Password for authentication to database connection (if authEnabled is true).

JWT¶

JSON Web Token configuration for communication.

secret¶

Type: String
Default: "" (empty)

Secret string used for JWT signing and validation (we recommend to generate some randomly).

version¶

Type: Integer
Default: 1

Our internal version of JWT Payload for DS Wizard (only 1 at the moment).

expiration¶

Type: Integer
Default: 14

Number of days until a token expires.

Roles¶

Basic configuration of roles and privileges within the DS Wizard instance. All roles and permission use capitalized names. There are three roles: Researcher, Data Steward, and Administrator. We recommend to leave the permission as in example application.yml, otherwise our Usage documentation may not match your configuration.

defaultRole¶

Type: Role (Enumeration [RESEARCHER, DATASTEWARD, ADMIN])
Default: DATASTEWARD

Role that will be assigned to newly registered user.

admin¶

Type: Permissions
Default: [ UM_PERM, ORG_PERM, KM_PERM, KM_UPGRADE_PERM, KM_PUBLISH_PERM, PM_READ_PERM, PM_WRITE_PERM, QTN_PERM, DMP_PERM]

List of permissions for Administrator/ADMIN.

dataSteward¶

Type: Permissions
Default: [KM_PERM, KM_UPGRADE_PERM, KM_PUBLISH_PERM, PM_READ_PERM, PM_WRITE_PERM, QTN_PERM, DMP_PERM]

List of permissions for Data Steward/DATASTEWARD.

researcher¶

Type: Permissions
Default: [PM_READ_PERM, QTN_PERM, DMP_PERM]

List of permissions for Researcher/RESEARCHER.

Mail¶

Configuration for sending emails (such as registration activation or for forgotten password mechanism) from the DS Wizard using SMTP connection.

Tip

You should enable emails unless you test the application for yourself only. It is used for email confirmations and mechanism of resetting password.

enabled¶

Type: Boolean
Default: true

If emails will be sent and SMTP configured.

name¶

Type: String

Name of the DS Wizard instance that will be used as “senders name” in email headers.

email¶

Type: String
Default: "" (empty)

Email address from which the emails will be sent.

host¶

Type: String
Default: "" (empty)

Hostname or IP address of SMTP server.

port¶

Type: Integer [0-65535]
Default: 465

Port that is used for SMTP on the server (usually 25 for plain or 465 for SSL).

ssl¶

Type: Boolean
Default: true

If SMTP connection is encrypted via SSL (we highly recommend this).

username¶

Type: String
Default: "" (empty)

Username for the SMTP connection.

password¶

Type: String
Default: "" (empty)

Password for the SMTP connection.

Analytics¶

Configuration of analytic/informational emails for administrators, e.g., that a new user registered into the DS Wizard.

enabled¶

Type: Boolean
Default: false

If analytic emails should be sent.

email¶

Type: String
Default: "" (empty)

Target email address where analytics to which will be sent.

Registry¶

enabled¶

Type: Boolean
Default: false

If connection with Registry should be made.

token¶

Type: String
Default: "" (empty)

Your organization token aquired by registration within the Registry service. More information can be found in Registry section of installation documentation.

Feedback¶

Configuration for feedback functionality within questionnaires via GitHub issues.

enabled¶

Type: Boolean
Default: true

If feedback functionality will be used.

token¶

Type: String
Default: "" (empty)

GitHub personal access token with permission to create issues in the selected repository.

owner¶

Type: String
Default: "" (empty)

GitHub username or organization under which is the repository for feedback created.

repo¶

Type: String
Default: "" (empty)

Name of the repository (without owner name).

issueurl¶

Type: URI
Default: "https://github.com/:owner/:repo/issues/:issueId"

Template URL for feedback issue.

Integration¶

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.

integration.yml¶

dbase:
  apiKey: topSecretDBaseApiKey
  baseUrl: 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.

Client¶

If you are running the client app using “Via 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:

config.js¶

window.dsw = {
    apiUrl: 'http://localhost:3000'
}

Client also provides wide variety of style customizations using SASS variables. Then you can mount it as volumes in case Docker as well:

volumes:
  # mount variables.scss file
  - /path/to/customizations.scss:/customizations/variables.scss
  # mount other assets, you can then refere them from scss using '/assets/...'
  - /path/to/assets:/usr/share/nginx/html/assets

For more information about variables and assets, visit Theming Bootstrap.

Worker¶

For running scheduled service tasks, there is a (optional) server worker component. Its configuration is done with API_URL which is the same as when configuring Client but also SERVICE_TOKEN that must correspond with server configuration serviceToken.

API_URL=https://api.dsw.example.org
SERVICE_TOKEN=<secret_token>

DMP Templates¶

You can freely customize and style templates of DMPs (filled questionnaires). HTML and CSS knowledge is required and for doing more complex templates that use some conditions, loops, or macros, knowledge of Jinja templating language (we use its implementation called Ginger) is useful.

Template files¶

We provide currently basic root template but it is possible to get inpired and create more or edit it:

templates/dmp/root.json = metadata about the template
templates/dmp/root.html.j2 = main template file
templates/dmp/root.css = stylesheet file included in the main file

Templates allow you to iterate through questions and answers and find what you need to compose some output. For example, you can generate longer text based on answers of various questions by knowing its texts or UUIDs. To the template, object dmp is injected and can be used as variable - for information about its structure, browse current default template or visit source code.

You can have multiple DMP templates and users will be able to pick one of them when exporting a filled questionnaire. Each template must have its metadata JSON file that contain random and unique UUID, name to be displayed when picking a template, and relative path to root file of the template:

{
  "uuid": "43a3fdd1-8535-42e0-81a7-5edbff296e65",
  "name": "Common DSW Template",
  "rootFile": "root.html.j2"
}

Graphics and scripts¶

If you want to include some graphics or JavaScript, we recommend you to put it directly into the HTML template file. In case of graphics, use base64 encoded content (suitable for smaller images like icons and logos):

<img src="data:image/png;base64, iVBORw0KGgoAAAANSU
 hEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GI
 AXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="
 alt="Red dot" />

Alternatively, you can of course reference picture that is accessible online. For JavaScript, again you can put there directly some script or reference it, for example, from some CDN:

<style type="text/javascript" src="https://code.jquery.com/jquery-3.3.1.min.js"></style>
<style type="text/javascript">
  jQuery(".btn").click(function(){
    jQuery(this).toggleClass(".clicked");
  });
</style>

You can split your template code into multiple files and the use include directive that opens the file and inserts its content where the directive is placed - like we do for including CSS style in HTML template (only one complex HTML file is generated in the end):

<head>
  <title>Data Management Plan</title>
  <meta charset="utf-8">
  <style>{% include "root.css" %}</style>
</head>

Docker deployment¶

If you deploy the DS Wizard using Docker, you can mount custom files to templates/dmp folder and overwrite default template within docker-compose.yml:

dsw_server:
image: datastewardshipwizard/server
restart: always
ports:
  - 3000:3000
volumes:
  - /dsw/app-config.cfg:/dsw/config/app-config.cfg
  - /dsw/root.json:/dsw/templates/dmp/root.json
  - /dsw/root.html.j2:/dsw/templates/dmp/root.html.j2
  - /dsw/root.css:/dsw/templates/dmp/root.css
external_links:
  - mongo_mongo_1:mongo
networks:
  - default
  - mongo_default

Email Templates¶

Similarly to DMP Templates, you can customize templates for emails sent by the Wizard located in templates/mail folder. It also uses Jinja templating language. 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:

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):

dsw_server:
  image: datastewardshipwizard/server
  restart: always
  ports:
    - 3000:3000
  volumes:
    - /dsw/app-config.cfg:/dsw/config/app-config.cfg
    - /dsw/templates/mail:/dsw/templates/mail
# ... (continued)