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
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
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:

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 public.

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

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
1
2
3
4
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
1
2
3
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

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)