Upgrade Guidelines
DSW releases regularly new versions according to the roadmap. It is required to keep your instance updated.
Usually, nothing special is required for the upgrade. Internal structure changes are migrated automatically using DB migrations and Metamodel migrations (since 1.8.0). See below the changes that need to be done by you (since 1.10.0):
(nothing)
(nothing)
- If you are running an older version than 3.16.X, you need to first upgrade to version 3.16 before upgrading to 3.17.
(nothing)
(nothing)
- You need to run wizard-server for the first time while document-worker and mailer are not running (to ensure database migration to proceed). Then you can start everything as usual.
(nothing)
(nothing)
(nothing)
- (optional) You can now use integration.yaml configuration in Settings instead of the file store on FS and mounted to Docker container.
- Standalone mailer component has been introduced, you need to adjust your deployment (e.g.
docker-compose.yml
) accordingly (see deployment-example).
(nothing)
- All KM migrations must be finished (completed or deleted); otherwise the upgrade of backend (database) will fail with corresponding message in the logs.
(nothing)
(nothing)
- The template metamodel version has been updated (to v5). Updating all document templates is needed (annotations were added, you can safely change version 4 to version 5 without breaking anything).
- All KM migrations must be finished (completed or deleted); otherwise the upgrade of backend (database) will fail with corresponding message in the logs.
(nothing)
(nothing)
- The template metamodel version has been updated (to v4). Updating all document templates is needed.
- All knowledge models have (after the automatic data migration) the default metrics and phases that can be changed in KM Editor.
- As an administrator, you should either disable the “Project Templates” feature (Settings - Projects - Project Creation, select “Custom only”) or prepare some project templates for your users to avoid confusion.
- All data must be migrated as we switched from MongoDB and RabbitMQ to PostgreSQL and S3. To support data migration, we provide dsw2to3 tool with step-by-step instructions.
(nothing)
(nothing)
- The metamodel for templates has been upgraded and accessing the reply values is changed due to additional metadata about each reply, see Document Context. But if you are using filters such as
reply_str_value
, it gets the reply object with value correctly. Moreover, for working with integration replies, the type values are renamedIntegrationValue
->IntegrationType
andPlainValue
->PlainType
for consistency.
- If you are using the
questionnaire-report
template, it is recommended to upgrade it to version 1.2.0 (from Registry or GitHub Release) so it displays also new Multi-Choice questions. Otherwise, the choices won’t appear in the exported document if there are any.
(nothing)
(nothing)
(nothing)
(nothing)
- The document templates including the default
questionnaire-report
must be updated from https://registry.ds-wizard.org/templates. - Upgraded template metamodel version 2 requires manual migration of custom templates:
questionnaireRepliesMap
(mappath:Reply
) is no longer present in the contextquestionnaireReplies
is now map withpath:ReplyValue
, provided filters (such asreply_str_value
) are adjusted but wherever you usedreply.value.value
it should bereply.value
with this change.- Reply for item questions is no longer an integer (number of answers) but a list of UUIDs representing the answers instead of integers. We added
reply_items
to extract the list from aReplyValue
.
- Since 2.6.0, we are using WebSockets (for live collaboration). If you are using a proxy, you need to configure it accordingly. For example, in the case of Nginx:
server {
# ...
location / {
# ...
# required for websockets
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 86400;
proxy_send_timeout 86400;
}
}
- Document templates have been moved from FS to the database. To simplify the transition for custom templates, we added to the Docker image a script that loads templates from FS to the database via DSW API. But there are several new information that you need to provide in
template.json
file:id
(instead ofuuid
),templateId
,organizationId
,version
(semver),license
,readme
(Markdown). Theid
should be in the formatorganizationId:templateId:version
. Please note that this applies only to custom templates, the default template can be removed from FS as it is added to the database automatically. The script must be enabled by setting envvarENABLE_TEMPLATE_LOAD `` to ``1
andSERVICE_TOKEN
according to the configuration. - Cron is no longer needed for the feedback synchronization (environment variables in
docker-compose.yml
) as DSW schedules synchronization internally.
- To unify configuration, document-worker now supports and prefers YAML configuration files.
- Local/custom
template.json
files must be updated (renamedallowedKMs
toallowedPackages
, and several new attributes:description
for template andshortName
+color
for each format).
(nothing)
- Configuration of client and several features is now moved from
application.yml
file to in-app Settings; therefore, it must be reconfigured during the upgrade process. Additionalsecret
must be configured inapplication.yml
for encryption and JWT tokens (JWT.secret section has been removed), see Server configuration. It is recommended to first add general.secret (32 chars secret), start DSW, migrate options fromapplication.yml
to Settings and then optionally clean upapplication.yml
file. - User files
name
andsurname
has been renamed tofirstName
andlastName
- it needs to be updated if used in custom mail or document templates. - The recommended version of MongoDB is updated to 4.2.3.
- There is a significant change related to the new Document Worker that handles the generation of documents from templates and filled questionnaires. You need to run RabbitMQ and document-worker with the correct configuration according to the server, see With Docker and Configuration for details.
- Changing the major version actually does not mean any problem in migration, it has been made due to significant internal changes (restructuring, new repositories, etc.)
- If you are using Docker for running DSW, you need to change it according to new documentation of With Docker and Configuration.
- Crontab image is no longer needed.
- A DMP template configuration file must contain a list of
allowedKMs
(see the default root template).
- Custom DMP templates need to be upgraded to a new structure (see the default root template).
Backup database and other important data (e.g., configuration) before upgrade!
In the case of using Docker, just use the tag in
docker-compose.yml
or pull the new Docker image and restart using down/up:docker pull
docker-compose down
docker-compose up -d
All you need to do is download or check out the new version from our repositories and rebuild the application (according to the guidelines above):
git checkout vX.Y.Z
DS Wizard components (server, client, document worker, registry) should always use matching version (compatibility is assured)!
The DS Wizard is compatible with all recent versions of web browsers Chrome, Opera, Firefox, and Edge. We do not recommend the use of Internet Explorer. Internally, there are components between is are following compatibility of versions:
DSW / Registry | KM Metamodel | Template Metamodel |
3.10 | 12 | 9 |
3.9 | 11 | 8 |
3.8 | 11 | 8 |
3.7 | 10 | 7 |
3.6 | 10 | 6 |
3.5 | 9 | 5 |
3.4 | 8 | 4 |
3.3 | 8 | 4 |
3.2 | 8 | 4 |
3.1 | 7 | 3 |
3.0 | 7 | 3 |
DSW / Registry | KM Metamodel | Template Metamodel |
2.14.0 | 7 | 3 |
2.13.0 | 7 | 3 |
2.12.0 | 6 | 3 |
2.6.0 - 2.11.0 | 5 | 2 |
2.5.0 | 5 | 1 |
2.0.0 - 2.4.0 | 5 | – |
DS Wizard | KM Metamodel | Registry |
1.10.0 | 4 | 1.2.0 |
1.9.0 | 3 | 1.1.0 |
1.8.0 | 3 | 1.0.0 |
1.7.0 | 2 | – |
1.6.0 | 1 | – |
1.5.0 (or lower) | – | – |
Last modified 26d ago