- Created by Robert Reiner, last modified on 24. Aug 2023
projectdoc Toolbox
Final Data Center Compatibility, Feature release with dynamic value handling and Calculation Macro.
- Release Date
Today we released version 6.0 of the projectdoc Toolbox which is made available on the Atlassian Marketplace on November 1, 2022.
Extensions and Doctype Add-ons
As of all versions of the apps related to the release 6.0 of the projectdoc Toolbox are available on the Atlassian Marketplace.
This is release provides new features and a couple of fixes and improvements and is approved by Atlassian to be compatible with Confluence Data Center. This version still supports Confluence Server.
The projectdoc Toolbox is an add-on for Confluence supporting agile software development teams to collaborate on process, project, system, and product documentation.
If you want to learn more about the projectdoc Toolbox and how it helps to create good project documentation, please refer to the introduction video!
The following image is a link to a video on YouTube. When you click the link your browser will serve a page from youtube.com.
Very interesting, but way too fast?
Step through at your own pace with with our Prezi Presentation (external link to prezi.com)!
In the Online Manual you’ll find additional video material that introduces you in the concepts of the projectdoc Toolbox.
Refer to use cases and show cases for information on how to use the projectdoc Toolbox.
New and Noteworthy
Data Center Compatibility
To save resources on a Data Center installation of Confluence, macros are required to limit the number of hits processed in one request.
Since the projectdoc Toolbox is intended be used to design documents to be exported to formats like PDF, paging is not supported by most macros. If the result set generated by a macro is larger than the configured limit, dependent on the macro either a warning or an error is rendered. Users are required to adjust their queries to pass the limit test.
The following macros are also affected by this limitation.
| Name | Short Description |
|---|---|
Lists references to projectdoc documents in a table. Allows to select document properties for columns. Also non-list representations are provided. | |
Lists references to projectdoc documents in a list. List contain names and optional short descriptions. | |
Lists references to projectdoc documents in a list. List items are defined by templates referencing properties. | |
Renders transcluded content fetched from documents of a result set. | |
Renders transcluded content fetched from documents of a result set. | |
Renders a table of index entries. | |
Renders the list of child documents, matching the given filter criteria. | |
Autoconnect to aspect documents. | |
Similar to the original Tasks Report Macro provided by Confluence, but allows to select on document with a Where clause. | |
Run calculations on a set of result documents and renders the results. |
The following macros process tables and will render an error message if the underlying macros render a warning message.
| Name | Short Description |
|---|---|
Renders the count of rows, list items, or definition terms. | |
Merges tables (and lists) into one table (or list). | |
Applies a simple set operation on tables in its body. |
Administrator configure the page size, which defaults to 100, via the administration screen.
Not that also the Web API is limited by the page size. The Web API supports paging.
For more information, please refer to Limitations on Query Results.
Data Center Support
The following apps are approved to be used on Confluence Data Center.
Extensions
The following extensions are available for Confluence Data Center and Confluence Server.
| Doctype Add-on | Version |
|---|---|
11.0.0 | |
6.0.0 |
Doctype Add-ons
The following doctype add-ons are available for Confluence Data Center and Confluence Server.
| Doctype Add-on | Version |
|---|---|
| Core Doctypes Add-on | 18.0.0 |
15.0.0 | |
15.0.0 | |
8.0.0 | |
6.0.0 | |
5.0.0 | |
| Doctypes for Software Development | 14.0.0 |
12.0.0 | |
5.0.0 | |
6.0.0 |
The following apps are currently not provided for Confluence Data Center. The Maven Extension will not be supported because it relies on libraries which are not updated regularly and the extension is considered unfit to meet the requirements imposed by a data center installation. It may still be used in some use cases.
Extensions
The following extensions are not provided for Confluence Data Center.
| Doctype Add-on | Remarks |
|---|---|
May be available in the future | |
Is only available for Confluence Server |
Doctype Add-ons
The user base is considered to small to continue the support of these doctype add-ons. The source for these add-ons is still available on Bitbucket.
| Doctype Add-on |
|---|
Dynamic Value Handling
Although property values must not be dynamic, it seems that users just love to use them. There are use cases where this makes sense, but mostly the information architecture will get in trouble, once the whole set of projectdoc documents needs to be rebuild.
This version provides some tools to check the current state of dynamic values on your server. It also provides some configurations to handle the use of dynamic values in the future.
In case you need to stick with the old lenient model, set the checking to off. This approach is not recommended. You can use REST services to check which mode is most appropriate to your information architecture.
For more information, please refer to Dynamic Property Values
Calculation Macro
Prior to this version there was only minor support to do some calculations. With this version there is the Calculation Macro and the Calculation Result Macro. It allows to run calculations on double values and render the results.
Currently there is no support for integer values, therefore use cases that require "full precision" (for instance calculations with currencies) are currently not supported.
Please refer to Calculation Macro for more information on how to use calculations in your Confluence instance using the projectdoc Toolbox.
Form Identifiers
Due to issues where the form identifiers are not properly encoded, we decided to replace the dots as separators with underscores. Therefore the name/identifier of a form field, for instance projectdoc.doctype.common.name is now specified as projectdoc_doctype_common_name. This is true for all identifiers used in the wizard.
This will reduce the amount of failures when the forms are processed with code that does not properly encode these identifiers.
Uncaught DOMException: Failed to execute 'querySelector' on 'Element': 'label[for=projectdoc.doctype.common.name]' is not a valid selector.
More information on using dots with identifiers can be found in Identifiers with Dots.
Due to this change all doctype add-ons are required to be updated for version 6.0 of the projectdoc Toolbox!
Breaking Changes
Result Size for REST API
When fetching documents with the REST API the maximum result set size also applies.
In case client scripts assume that the whole result set is returned, they now need to be adjusted to use the paging.
This also applies to the Web API Extension.
Installation Instructions
For new users of the projectdoc Toolbox who install this app the first time.
- Install the new OBR of the projectdoc Toolbox.
- Check if extensions are required to be installed for your use cases
- Check if doctype add-ons are required to be installed for your use cases
All extensions and doctype add-ons are free of charge. The doctype add-ons are available with an open source license.
Configuration
Dynamic Values
For backward compatibility the default mode for Dynamic Value Handling is set to allow. It is recommended to use the value of lenient. The value can be configured in the administration section of the projectdoc Toolbox.
For more information, please refer to Dynamic Property Values
Upgrade Instructions
Please follow this short guide to update your existing installation to this new version of the projectdoc Toolbox. For detailed information on dependencies, please consult the documentation of the add-ons.
Installation Order
Please install the projectdoc Toolbox first, then the extensions and finally update the doctype add-ons.
So this is the basic order:
- projectdoc Toolbox
- extension add-ons (start with Web API Extension)
- doctype add-ons (start with Core Doctypes)
Please install only those add-ons that are actually used! In case you do not use the Web API, there is no need to install it. 
Configuration
Page Size
Due to requirements of Confluence Data Center, the result set returned on queries is now limited to the page size configured in the administration section.
The default value is 100. Therefore there is a warning or error message if there are more than 100 hits in the result.
You may want to alter this value according to the resources provided for Confluence and the use cases to support with the projectdoc Toolbox.
Page Size is Max Size for Macros
The name page size may be misleading as this is currently implemented as the maximum size of the result set for macros. It is the page size for paging when using the REST API.
Since the projectdoc Toolbox is used to create documentation to be exported to PDF, there is no use of paging in the macros. Therefore no macro currently supports paging. Users are required to adjust their queries so that the rendered content in HTML can be exported to PDF and both versions show the same result.
Dynamic Values
The use of dynamic values may impose problems. Users may expect that a query as a property value will be updated on every change of any page of Confluence. This is actually not the case. Therefore the use of dynamic properties (properties whose value are not fixed after the page has been saved) is limited to some very specific use cases. With other words: typically dynamic values for properties must not be used.
This version provides tools to help users to prevent making mistakes by making false assumptions. The handling of dynamic values is now controlled via the administration screen, where a mode can be configured. Per default it is set to allow. It is recommended to use a value of lenient (if users know exactly what to do and still need dynamic property values to implement their use cases) or strict (to prevent to force dynamic values where they do not belong). If the default mode does not work for your use cases, off will deactivate the checks completely.
For more information, please refer to Dynamic Property Values
List of Changes
The following changes are part of version 6.0 of the projectdoc Toolbox for Confluence.
Related Releases
This version does not require updates of doctype-add-ons, but we recommend the update of the Web API Extension.
Extension Add-ons
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.
This app is not available for Confluence Data Center.
Doctype Add-ons
The following doctype add-ons are required to be updated for the projectdoc Toolbox.
| Doctype Add-on | Version |
|---|---|
| Core Doctypes Add-on | 18.0.0 |
15.0.0 | |
15.0.0 | |
8.0.0 | |
6.0.0 | |
5.0.0 | |
| Doctypes for Software Development | 14.0.0 |
12.0.0 | |
5.0.0 | |
6.0.0 |
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.
In case any of the following doctype add-ons are used, they are required to be installed to work with this version of the projectdoc Toolbox.
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 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.
Resources
- Release Notes
- 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.
