- Created by Robert Reiner, last modified on 24. Aug 2023
Improvements heading to data center support. Requires rebuild of database tables which may take up to hours to run.
- Release Date
Today we released version 5.0 of the projectdoc Toolbox. It includes changes from version 5.0.0 to 5.0.10.
Since this is a major release, expect breaking changes!
This major update includes changes to the database tables containing projectdoc documents. The rebuild process will be started automatically by default when updating the app. Dependent on the amount of projectdoc documents on your Confluence server, this process will require quite a long time (half an hour to several hours) to complete. Although the process runs in the background, the results of queries on projectdoc documents are not reliable until the process completes successfully.
Please read this release notes carefully prior to updating the projectdoc Toolbox!
We highly recommend to run this process on your test system to estimate the time for the rebuild of projectdoc documents on your system.
This version 5 includes a couple of changes required for data center support. Data center support is planned to be supported by the major version of the projectdoc Toolbox.
This version is a preparation step to support Confluence Data Center (DC). We are about to start the approval process for DC and once this process is completed, a DC version of the projectdoc Toolbox will be available on the Atlassian Marketplace. Customers with a DC configuration will then need to move to a DC license of the projectdoc Toolbox. More information on Data Center Pricing & Licensing or Collaborate without compromise on DC can be found at Atlassian.
The projectdoc Toolbox is an add-on for Confluence supporting agile software development teams to collaborate on process, project, system, and product documentation.
Summary
This version provides
- Preparation for Confluence Data Center
- Support for Confluence Server version 7.4.16 to 7.17.1.
- Improvements in the user interface
This release has Breaking Changes. Therefore it is required to update extensions and doctype add-ons (see Related Releases for details).
New and Noteworthy
Very quickly the most relevant changes in this release.
Preparation for Data Center Support
This version add some performance improvements to support Confluence Data Center (DC).
One of the most relevant news for your upgrade is the new database structure the projectdoc Toolbox. Since the projectdoc tables did not store any information that cannot be derived from the Confluence pages, you simply need to rebuild the table data from scratch. Unfortunately this requires – especially for large installations – quite a lot of time. We recommend to check the upgrade process in a test environment on real data to get an estimation about how long this would take on your Confluence instance.
This also includes support for the Confluence Read-Only Mode (a must have for DC).
Editing Experience
A couple of improvements address the user experience when working with projectdoc documents in the Confluence page editor.
All these features are considered experimental and are currently in an early release status with some limitations (for details please follow the links below).
- Section Expander: Macros in the page editor can be collapsed or expanded
- Section Navigation: The editor can be opened at a specified location
- Dynamic Editor Content: Provides dynamic content generated by macros when in the page editor
Reading Experience
A new feature allows readers to collapse or expand sections.
The chevron icon allows to hide the contents of a section and therefore allows the user to focus.
The chevron may be at a different position, dependent on the CSS.
For more information, please visit Section Collapse.
Administration UI
The administration user interface provides new elements.
Features
Features that interact with the user interface may now be configured to be activated or deactivated by user groups.
More information for these features are found on Doctools.
Rebuilder UI
The rebuild processes may be launched via the administration user interface. The REST services, providing more configuration options, are still available, tough.
For more information on the Rebuild Service, please refer to the projectdoc Rebuild Manual.
Database Tables
We updated the database tables to store projectdoc data. This is required to cope with the increased load on Confluence when run in a data center environment.
The old tables (identified by "PD_" in the table name) will stay untouched and the new structures will be stored in new tables (identified by "PD5_"). Even if the old data will still be available we highly recommend to have access to a current backup of your database.
PD5 Tables
AO_63F547_PD5_DOCAO_63F547_PD5_NAME_REFSAO_63F547_PD5_PAGE_REFSAO_63F547_PD5_PG_FRGMNTAO_63F547_PD5_PROP
The upgrade process will only affect projectdoc tables in Active Objects (AO). In case the process cannot complete successfully, because an accidental server downtime, please clear (not drop) the new PD5 tables from corrupt content and restart the server. The process can also be started manually via a Representational state transfer service.
For more information on updating information in the projectdoc database tables, please refer to projectdoc Rebuild Manual, especially Upgrade Task.
Breaking Changes
Installation Instructions
Install the new OBR of the projectdoc Toolbox.
Installation Order
In case this is the first time the projectdoc Toolbox is installed, please follow these instructions. In case you upgrade from an older version, please continue with Upgrade Instructions
Please install the projectdoc Toolbox first, then the extensions and finally update the doctype add-ons.
So this is the basic order to upgrade:
- Install projectdoc Toolbox
- Install extension add-ons (start with Web API Extension)
- Install doctype add-ons (start with Core Doctypes)
Please install only those add-ons that you need! The add-ons provide additional features to the projectdoc Toolbox. The projectdoc Toolbox works without any further add-ons.
Upgrade Instructions
Here is a short guide to update to this new version of the projectdoc Toolbox. For detailed information on dependencies, please consult the documentation of the add-ons.
Backup first, install add-on second!
This upgrade requires an upgrade of the projectdoc tables. This upgrade will be started automatically!
Expect this to be huge. Do not install this version of the projectdoc Toolbox without a backup plan!
Upgrading from an alpha Version
Upgrading from a previous alpha version (for example version 5.0.3) to the latest alpha version (for example version 5.0.9) does not require any of these steps. Simply update the app by uploading it manually to replace the 5.0.3 with the new 5.0.9.
Upgrade Order
Please check again!
Make sure you have a recent backup and checked the upgrade in a test environment before you continue with the following steps.
projectdoc Toolbox only
In case you are only using the projectdoc Toolbox without any extensions, you may install the projectdoc Toolbox and the automatic upgrade process of the projectdoc tables in your database will start automatically.
Order, when only the projectdoc Toolbox is in use (only one step):
- Update projectdoc Toolbox
projectdoc Toolbox with additional projectdoc add-ons
The projectdoc Toolbox will check that the versions of the add-ons are correct. If not, the upgrade process will be postponed. The issue will be logged at error level to the log and on each projectdoc document page online. This is the default process.
Alternatively you get full control over the process by setting the Java System system property de.smartics.projectdoc.upgrade.skip-auto to true. This will prevent the upgrade process to start. Install the projectdoc Toolbox then the extensions, unset the system property and restart the server.
For more information on updating information in the projectdoc database tables, please refer to projectdoc Rebuild Manual, especially Upgrade Task.
Please install only those add-ons that are actually used! In case you do not use any of the projectdoc extensions, there is no need to install it. 
The migration process only starts when the projectdoc tables of version 5 are empty.
If these tables are not empty and the migration should be startet, please clear all tables of the projectdoc Toolbox with the PD5_ prefix.
It is highly recommended NOT to remove tables with the PD_ prefix until your migration process has completed successfully.
Automatic (recommended)- projectdoc Toolbox with extension and doctype add-ons:
- Update projectdoc Toolbox
- Check logs or open a projectdoc page to see if add-on updates are required
- update extension add-ons (start with Web API Extension)
- update doctype add-ons (start with Core Doctypes)
Manual - projectdoc Toolbox with extension and doctype add-ons:
- Set the system property when starting the JVM
-Dde.smartics.projectdoc.upgrade.skip-auto=true - Update projectdoc Toolbox
- Update extension add-ons (start with Web API Extension)
- Update doctype add-ons (start with Core Doctypes)
- Remove the system property added in step 1
-Dde.smartics.projectdoc.upgrade.skip-auto=true
Rebuild
Due to the following issues a rebuild is required to update properties.
Expect this to be huge. Do not upgrade without a backup plan!
This is detected by the automatic upgrade process. So there is no need to start the rebuild manually if the automatic upgrade has been selected.
For complex navigation structure between projectdoc documents it may be required to run a refresh on the tables.
Please refer to projectdoc Rebuild Manual for details on how to rebuild or refresh the projectdoc tables.
List of Changes
The following changes are part of the latest projectdoc Toolbox for Confluence.
Changes in 5.0.10
Changes in 5.0.9
Changes in 5.0.8
Changes in 5.0.7
Changes in 5.0.6
Changes in 5.0.5
Changes in 5.0.4
Changes in 5.0.0 to 5.0.3
Related Releases
The projectdoc Toolbox provides an internal API for extension add-ons and doctype add-ons. Therefore these additional app need to updated according to the version of the projectdoc Toolbox.
Extension Add-ons
All extensions are optional. If you do not need the features provided by an extension, there is no need to install it.
If in use, the following extension are required to be updated for the projectdoc Toolbox to the specified versions.
Web API Extension
The following changes are part of the latest Web API Extension.
Bookmarklets Extension
The following changes are part of the latest Bookmarklets Extension.
Information Systems Extension
The following changes are part of the latest Information Systems Extension.
Maven Extension
The following changes are part of the latest Maven Extension.
Doctype Add-ons
The following doctype add-ons are recommended to be updated for the projectdoc Toolbox.
All doctype add-ons are optional. In case an add-on is not installed, there is no need to install it for this version of the projectdoc Toolbox.
Core Doctypes
The following changes are part of the latest Core Doctypes Add-on.
Doctypes for Agile Planning
The following changes are part of the latest Doctypes for Agile Planning.
projectdoc Developer Diaries
The following changes are part of the latest projectdoc Developer Diaries.
Doctypes for Project Management
The following changes are part of the latest Doctypes for Project Management.
Doctypes for Risk Management
The following changes are part of the latest Doctypes for Risk Management.
This extension is experimental.
Doctypes for Service Management
The following changes are part of the latest Doctypes for Service Management.
Doctypes for Business Strategy
The following changes are part of the latest Doctypes for Business Strategy.
Doctypes for Software Development
The following changes are part of the latest Doctypes for Software Development.
Doctypes for Teamwork
The following changes are part of the latest Doctypes for Teamwork.
Doctypes for V-Modell XT
The following changes are part of the latest Doctypes for V-Modell XT.
projectdoc arc42 Template
The following changes are part of the latest projectdoc Add-on for arc42.
Doctypes for Java Developers
The following changes are part of the latest projectdoc for Java Developers.
This extension is experimental.
Doctypes for Maven Developers
The following changes are part of the latest projectdoc for Maven Developers.
This extension is experimental.
Resources
- Release Notes for the projectdoc Toolbox
- Information on all released versions of the projectdoc Toolbox for Confluence.
- Glossary
- Terms used in and defined for projectdoc.
- FAQs
- Questions and answers related to the projectdoc Toolbox and Confluence.
